# 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

Endpoint: POST /structured_prompt/generate

## Header parameters:

  - `api_token` (string, required)

## 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.

  - `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)