---
title: "Generate Structured Instruction"
method: POST
path: "/structured_instruction/generate"
tags: ["v2 endpoints"]
---

# Generate Structured Instruction

`POST /structured_instruction/generate`

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

## Headers

- `api_token` string, required

## Request body

- object
  - `instruction` string, required — Required. Text-based edit instruction (e.g., "make the sky blue", "add a cat"). This parameter serves as the text prompt.
  - `images` string[], required — 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.**
  - `mask` string — 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.**
  - `seed` integer — Optional. Seed for deterministic generation. If omitted, a random seed is generated and used.
  - `sync` boolean — 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_url` string, uri — Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
  - `ip_signal` boolean — If true, returns a warning for potential IP content in the instruction. Optional.
  - `prompt_content_moderation` boolean — If true, returns 422 on instruction moderation failure. Optional.
  - `visual_input_content_moderation` boolean — If true, returns 422 on images or mask moderation failure. Optional.

## Response `200`

Successful operation (Synchronous Success)

- SyncStructuredInstructionResponse
  - `result` object, required
    - `seed` integer, required
    - `structured_instruction` string, required
  - `request_id` string, required
  - `warning` string — Returned only when ip_signal = true and the instruction field included IP content.

## Other responses

- `202` — Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.
- `400` — Bad request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found.
- `415` — Unsupported media type.
- `422` — Unprocessable Entity.
- `429` — Request limit exceeded.
- `5XX` — Internal Server Error.

---

[API](https://skmtc.dev/bria-ai/apis/image-editing-api-reference.md) · [All operations](https://skmtc.dev/bria-ai/apis/image-editing-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bria-ai/image-editing-api-reference/revisions/b69d3f84c7f7/schema)