Generate Structured Prompt

Image Generation

Generate Structured Prompt

Request

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 by clicking here.

Security

api_token

Bodyapplication/json

promptstring

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

imagesArray of strings, <= 1 items

Publicly available URL or Base64-encoded image. Currently supports a single image. Supported formats: JPEG, JPG, PNG, WEBP.

structured_promptstring

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

seedinteger

Seed for deterministic generation. Uses a random seed if omitted. This parameter is optional.

syncboolean

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.

Default:false

webhook_urlstring, (uri)

Optional URL for receiving the result via webhook when the async job completes. See webhooks.

ip_signalboolean

If true, returns a warning for potential IP content in the prompt parameter. This parameter is optional.

Default:false

prompt_content_moderationboolean

If true, returns 422 on input prompt moderation failure in the prompt parameter. This parameter is optional.

Default:true

visual_input_content_moderationboolean

If true, returns 422 on visual input moderation failure. This parameter is optional.

Default:true

POST

/structured_prompt/generate

from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

response = client.run(
    endpoint="structured_prompt/generate",
    payload={
        "images": [
            "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo/ref_1.jpg",
        ],
    },
)
print(response.result.structured_prompt)

Responses

Successful operation (Synchronous Success)

Bodyapplication/json

resultobjectrequired

request_idstringrequired

warningstring

Returned only when ip_signal = true and the prompt field included IP content.

Response

{
  "result": {
    "seed": 0,
    "structured_prompt": "string"
  },
  "request_id": "string",
  "warning": "string"
}