Editing

Image Edit by Text

Changed on

Try out this capability in Bria's sandbox

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 referenceMulti-reference (2–4 images)
Masking (mask)SupportedNot supported
Aspect ratio controlSupported 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>
post/image/edit

Request

  • Base URL: https://engine.prod.bria-api.com/v2
  • URL: https://engine.prod.bria-api.com/v2/image/edit
  • Auth: API key in header api_token

Request body

imagesstring[] 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.

instructionstring

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

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

structured_instructionstring

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

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.

seedinteger

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

syncboolean

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_urlstring uri

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

output_type'png' | 'jpeg'

The desired output format

ip_signalboolean

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

prompt_content_moderationboolean

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

visual_input_content_moderationboolean

If true, returns 422 on images or mask moderation failure. This parameter is optional.

visual_output_content_moderationboolean

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

Response

Successful operation (Synchronous Success)

request_idstring required
warningstring

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

Changes

  • ff15f86ae88fRevision changes
    • info

      added the new 10:16 enum value to the request property

    • info

      added the new 16:10 enum value to the request property

    • info

      added the new 1:2 enum value to the request property

    • info

      added the new 1:3 enum value to the request property

    • info

      added the new 1:4 enum value to the request property

    • info

      added the new 1:5 enum value to the request property

    • info

      added the new 21:9 enum value to the request property

    • info

      added the new 2:1 enum value to the request property

    • info

      added the new 3:1 enum value to the request property

    • info

      added the new 4:1 enum value to the request property

    • info

      added the new 5:1 enum value to the request property

    • info

      added the new 9:21 enum value to the request property

  • 1d2fc668005fRevision changes
    • warning

      deleted the header request parameter api_token

    • info

      api tag Editing added

    • info

      api tag v2 endpoints removed