Skip to content
Image Editing
/
/
Generate Structured Instr...

Generate Structured Instruction

Request

Description

Translates a user's text-based edit instruction and source image/mask into a detailed, machine-readable structured edit instruction in JSON format.

This endpoint uses the state-of-the-art Gemini 2.5 Flash VLM bridge to understand the edit context. It only returns the JSON string and does not generate an image.

Context-Aware Masking

When a mask is provided, the VLM analyzes the specific region of interest in relation to the rest of the image. It generates a structured_instruction tailored specifically for that area (e.g., ensuring lighting and perspective match the unmasked background), ensuring seamless integration when the edit is applied.

Why use this endpoint?

  • Decoupling: Decouples the "intent translation" step from the "image editing" step, giving you maximum flexibility.
  • 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_instruction and pass it to /v2/image/edit 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_instruction can be used as input for the /v2/image/edit endpoint.

Input Combination Rules The request body must use exactly one of the following combinations:

  • Global Instruction: images + instruction
  • Masked Instruction: images + mask + instruction

API Access

You can register and access the API Token through Bria's platform by clicking here.

Headers
api_tokenstringrequired
Bodyapplication/json
instructionstringrequired

Required. Text-based edit instruction (e.g., "make the sky blue", "add a cat"). This parameter serves as the text prompt.

imagesArray of strings, [ 1 .. 4 ] itemsrequired

The source/reference image(s) to be edited. Publicly available URL or Base64-encoded. Accepted formats: JPEG, JPG, PNG, WEBP. Accepts 1 to 4 images.

maskstring

Publicly available URL or Base64-encoded mask image (black and white). Black areas will be preserved, white areas will be edited. If omitted, the edit applies to the entire image. The input image and the input mask must be of the same size. Only supported when images contains exactly one item.

seedinteger

Optional. Seed for deterministic generation. If omitted, a random seed is generated and used.

syncboolean

Specifies the response mode. Optional.

  • When false (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.
  • When true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final result in the response.
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 instruction. Optional.

Default:false
prompt_content_moderationboolean

If true, returns 422 on instruction moderation failure. Optional.

Default:true
visual_input_content_moderationboolean

If true, returns 422 on images or mask moderation failure. Optional.

Default:true
POST
/structured_instruction/generate
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/structured_instruction/generate \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "images": [
      "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082.jpg"
    ],
    "instruction": "create a detailed realistic photo, with contemporary color scheme, and balanced exposure photo roughly based on this sketch"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
request_idstringrequired
warningstring

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

Response
{
  "result": {
    "seed": 0,
    "structured_instruction": "string"
  },
  "request_id": "string",
  "warning": "string"
}