# Image Edit by Text

[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/fibo-image-edit)
**Description**
Powered by the **Fibo models family**, Bria's Image Editing by Text API equips builders with the ability to modify existing images using natural language instructions or structured JSON instructions.
This endpoint now supports **multi-reference editing** — you can supply up to 4 input images in a single request, enabling use cases like combining a product with a reference scene, matching a reference object's color or texture, or maintaining character consistency across images.
Fibo 2 features **native masking support** for precise, localized editing on single-image requests. You can supply a binary mask to restrict changes to specific regions while preserving the rest of the image.
The masking logic operates as a **generative replacement**; the model generates entirely new content within the masked area based on your instruction, rather than modifying the existing pixels.
**Core Technology: The Fibo Architecture**
This endpoint utilizes the **Fibo** architecture, a unique two-step process ensuring precise and controllable edits:
1. **Translation:** A VLM bridge converts your inputs into a detailed `structured_instruction` (JSON).
2. **Generation:** Fibo 2 performs the final, deterministic edit on the input image(s), based on that JSON.

**Advanced Control & Recreation**
* To recreate a specific result: You must provide the exact source images, the mask (if used), the `structured_instruction` returned in the original response, and the `seed` used to create it.
* For advanced, programmatic control, you can pass in your own `structured_instruction` (e.g., from the `/v2/structured_instruction/generate` endpoint) to bypass the internal VLM bridge.



---

**Multi-Reference Editing**
You can now provide **1 to 4 reference images** in a single edit request. All input images are considered together when generating the edit, guided by your `instruction` or `structured_instruction` — for example, placing a product from one image into the scene from another, or keeping a character or style consistent across multiple inputs.
|  | Single reference | Multi-reference (2–4 images) |
|  --- | --- | --- |
| Masking (`mask`) | Supported | Not supported |
| Aspect ratio control | Supported with restriction (see disclaimer in parameter below) | Fully supported |

Requests with more than 4 images will return an error. See new validation errors below.


---

**Input Combination Rules**
The request body must include `images` (1–4 items) and one of the following combinations:
* **Edit by Text (single or multi-reference):** `images` (1–4) + `instruction`
* **Edit by JSON Instruction (single or multi-reference):** `images` (1–4) + `structured_instruction`
* **Masked Edit by Text (single reference only):** `images` (exactly 1) + `mask` + `instruction`
* **Masked Edit by JSON Instruction (single reference only):** `images` (exactly 1) + `mask` + `structured_instruction`



---

**Examples**
**Use Case 1: Multi-reference edit (3 images)**
**Instruction:** *"luxury fragrance poster. A single large grey boulder sits in perfectly calm, mirror-like water…"* The full instruction is in the multi-reference request example.
<table>
<tr>
<th style="text-align: center;">Input Image 1</th>
<th style="text-align: center;">Input Image 2</th>
<th style="text-align: center;">Input Image 3</th>
<th style="text-align: center;">Output Image</th>
</tr>
<tr>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_still_rock.jpg" alt="A boulder in still, misty water" width="180" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_still_bottle.jpg" alt="A square perfume bottle with rose-gold liquid" width="180" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_still_logo.jpg" alt="The STILL eau de parfum wordmark" width="180" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-outputs/fibo2_edit_still_s202.jpg" alt="Fibo 2: a STILL perfume poster, the bottle on the boulder under the logo" width="180" style="border-radius: 8px;">
</td>
</tr>
</table>
<br>
**Use Case 2: Edit one image by text**
**Instruction:** *"Change the car's paint to glossy cherry red, keep everything else the same"*
<table>
<tr>
<th style="text-align: center;">Input Image</th>
<th style="text-align: center;">Output Image</th>
</tr>
<tr>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_car.jpg" alt="A blue car on a salt flat at dusk" width="300" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-outputs/fibo2_edit_car_red.jpg" alt="Fibo 2: the same car in glossy cherry red" width="300" style="border-radius: 8px;">
</td>
</tr>
</table>
<br>
**Use Case 3: Masked edit**
**Instruction:** *"Replace the bottle with a frosted pink perfume bottle with a gold cap"*
<table>
<tr>
<th style="text-align: center;">Input Image</th>
<th style="text-align: center;">Input Mask</th>
<th style="text-align: center;">Output Image</th>
</tr>
<tr>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_perfume.jpg" alt="A teal perfume bottle splashing into water" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_perfume_mask.png" alt="Mask over the bottle" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-outputs/fibo2_edit_perfume_pink.jpg" alt="Fibo 2: a frosted pink bottle with a gold cap in the same splash" width="200" style="border-radius: 8px;">
</td>
</tr>
</table>
Outside the mask the image is kept as it was.
<br>
**Use Case 4: Masked edit on a 4K image**
**Instruction:** *"Make the sneaker electric blue with neon green laces"*
<table>
<tr>
<th style="text-align: center;">Input Image (3840×2160)</th>
<th style="text-align: center;">Input Mask</th>
<th style="text-align: center;">Output Image (3840×2160)</th>
</tr>
<tr>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_runner_4k.jpg" alt="A runner stretching on a bridge at dusk" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_runner_4k_mask.png" alt="Mask over the sneaker" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://labs-assets.bria.ai/sandbox-example-outputs/fibo2_edit_runner_4k_blue.jpg" alt="Fibo 2: the same photo with an electric blue sneaker" width="200" style="border-radius: 8px;">
</td>
</tr>
</table>
The output keeps the input's exact size.
<br>

Endpoint: POST /image/edit
Security: api_token

## Request fields (application/json):

  - `images` (array, 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.** Requests with more than 4 images will return an error.

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

  - `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.** If `images` contains more than one item, including a `mask` will return an error.
This parameter is optional.

  - `structured_instruction` (string)
    A string containing the structured edit instruction in JSON format. Use this instead of `instruction` for precise, programmatic control. (check generate structured instruction endpoint)

  - `aspect_ratio` (string)
    The aspect ratio of the output image. Supported for both single-image and multi-reference requests. This parameter is optional. 16:10, 10:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3, 4:1, 1:4, 5:1 and 1:5 are rendered by Fibo 2 and return 422 on a request it doesn't serve (a tailored `model_id`, `original_vgl` or `new_vgl`).
**Default:** aspect ratio of the first image in `images`.
**Note:** for single-reference requests, the model was not trained to change aspect ratio dramatically from the source image — results may degrade if the requested aspect ratio differs significantly from the input image's own aspect ratio. Multi-reference requests fully support all listed aspect ratios.
    Enum: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "16:10", "10:16", "2:1", "1:2", "21:9", "9:21", "3:1", "1:3", "4:1", "1:4", "5:1", "1:5"

  - `seed` (integer)
    Seed for deterministic generation. Uses a random seed if omitted. This parameter is optional.

  - `sync` (boolean)
    Specifies the response mode. This parameter is 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 image URL in the response.

  - `webhook_url` (string)
    Optional URL for receiving the result via webhook when the async job completes. See [webhooks](/getting-started/async-requests#webhooks).

  - `output_type` (string)
    The desired output format
    Enum: "png", "jpeg"

  - `ip_signal` (boolean)
    If true, returns a warning for potential IP content in the instruction. This parameter is optional.

  - `prompt_content_moderation` (boolean)
    If true, returns 422 on instruction moderation failure. This parameter is optional.

  - `visual_input_content_moderation` (boolean)
    If true, returns 422 on images or mask moderation failure. This parameter is optional.

  - `visual_output_content_moderation` (boolean)
    If true, returns 422 on visual output moderation failure. This parameter is optional.

## Response 200 fields (application/json):

  - `result` (object, required)

  - `result.image_url` (string, required)

  - `result.seed` (integer, required)

  - `result.structured_instruction` (string, required)

  - `request_id` (string, required)

  - `warning` (string)
    Returned only when ip_signal = true and the instruction field included IP content.

## Response 202 fields (application/json):

  - `request_id` (string, required)

  - `status_url` (string, required)

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

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

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

  - `request_id` (string, required)

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 415 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

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

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

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

  - `request_id` (string, required)

