Sign in

v1

latestOpenAPI 3.0.02026-08-062312216.0 KB
v2 endpoints

Generate Structured Instruction

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 <a href="https://platform.bria.ai/console/account/api-keys" target="_blank">by clicking here</a>.

post/structured_instruction/generate

Headers

api_tokenstring required

Request body

instructionstring required

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

imagesstring[] required

Required. The source image to be edited. Publicly available URL or Base64-encoded. Must contain exactly one item.

maskstring

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

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

prompt_content_moderationboolean

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

visual_input_content_moderationboolean

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

Response

Successful operation (Synchronous Success)

request_idstring required
warningstring

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