# Generate Structured Prompt

Creates a new detailed, machine-readable structured prompt in JSON format or refines an existing one using text or image inputs.
This endpoint uses the state-of-the-art **Gemini 2.5 Flash** VLM bridge to generate the prompt, providing superior understanding of nuanced or complex inputs. It **only returns the JSON string** and does not generate an image.
**Why use this endpoint?**
This endpoint decouples the "intent translation" step from the "image generation" step, giving you maximum flexibility.
* **It's Optional:** The same structured prompt generation happens automatically behind the scenes when using `/v2/image/generate`.
* **Control & Auditability:** Allows for a "human-in-the-loop" to inspect, programmatically edit, or version the JSON *before* generating an image (e.g., for a custom UI).
* **Consistency & Automation:** Generate one `structured_prompt` and pass it to `/v2/image/generate` multiple times to create consistent, auditable variations.
* **Hybrid Deployment:** Use Bria's state-of-the-art VLM bridge via API while self-hosting the open-source FIBO image model on your own private cloud.

The resulting `structured_prompt` can be used as input for the `/v2/image/generate` endpoint.
**Input Combination Rules**
The request body must use exactly one of the following combinations:
* **Text Only**: `prompt`
* **Image Only**: `images`
* **Image and Text**: `images` and `prompt`
* **Structured Prompt and Text**: `structured_prompt` and `prompt`



---

** API Access **
You can register and access the API Token through Bria's platform <a href="https://platform.bria.ai/console/account/api-keys" target="_blank">by clicking here</a>.

Endpoint: POST /structured_prompt/generate
Security: api_token

## Request fields (application/json):

  - `prompt` (string)
    Text-based instruction. Can be used alone to create a new prompt, or as a refinement command with an `images` or `structured_prompt`.

  - `images` (array)
    Publicly available URL or Base64-encoded image. Currently supports a single image.
Supported formats: **JPEG**, **JPG**, **PNG**, **WEBP**.

  - `structured_prompt` (string)
    A string containing the structured prompt in JSON format. Use a `structured_prompt` from a previous generation's response.

  - `seed` (integer)
    Seed for deterministic generation. Uses a random seed if omitted. This parameter is optional.

  - `sync` (boolean)
    Response mode. This parameter is optional.
* `false` (default): Asynchronous. Returns 202 with a `status_url` to poll.
* `true`: Synchronous. Holds the connection and returns 200 with the final result.

  - `webhook_url` (string)
    Optional URL for receiving the result via webhook when the async job completes. See [webhooks](/getting-started/async-requests#webhooks).

  - `ip_signal` (boolean)
    If true, returns a warning for potential IP content in the `prompt` parameter. This parameter is optional.

  - `prompt_content_moderation` (boolean)
    If true, returns 422 on input prompt moderation failure in the `prompt` parameter. This parameter is optional.

  - `visual_input_content_moderation` (boolean)
    If true, returns 422 on visual input moderation failure. This parameter is optional.

## Response 200 fields (application/json):

  - `result` (object, required)

  - `result.seed` (integer, required)

  - `result.structured_prompt` (string, required)

  - `request_id` (string, required)

  - `warning` (string)
    Returned only when ip_signal = true and the prompt field included IP content.

## Response 202 fields (application/json):

  - `request_id` (string, required)

  - `status_url` (string, required)

  - `warning` (string)
    Returned only when ip_signal = true and the prompt field included IP content.

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)

## Response 401 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)

## Response 422 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)

## Response 429 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)

## Response 5XX fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string)

  - `request_id` (string, required)