Skip to content
Image Editing
/
/
Image Edit by Text

Image Edit by Text

Request

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.

Input Image 1Input Image 2Input Image 3Output Image
A boulder in still, misty waterA square perfume bottle with rose-gold liquidThe STILL eau de parfum wordmarkFibo 2: a STILL perfume poster, the bottle on the boulder under the logo

Use Case 2: Edit one image by text

Instruction: "Change the car's paint to glossy cherry red, keep everything else the same"

Input ImageOutput Image
A blue car on a salt flat at duskFibo 2: the same car in glossy cherry red

Use Case 3: Masked edit

Instruction: "Replace the bottle with a frosted pink perfume bottle with a gold cap"

Input ImageInput MaskOutput Image
A teal perfume bottle splashing into waterMask over the bottleFibo 2: a frosted pink bottle with a gold cap in the same splash

Outside the mask the image is kept as it was.


Use Case 4: Masked edit on a 4K image

Instruction: "Make the sneaker electric blue with neon green laces"

Input Image (3840×2160)Input MaskOutput Image (3840×2160)
A runner stretching on a bridge at duskMask over the sneakerFibo 2: the same photo with an electric blue sneaker

The output keeps the input's exact size.


Security
api_token
Bodyapplication/json
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. 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_ratiostring

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"
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.
Default:false
webhook_urlstring, (uri)

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

output_typestring

The desired output format

Default:"png"
Enum:"png""jpeg"
ip_signalboolean

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

Default:false
prompt_content_moderationboolean

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

Default:true
visual_input_content_moderationboolean

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

Default:true
visual_output_content_moderationboolean

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

Default:true
POST
/image/edit
from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

response = client.run(
    endpoint="image/edit",
    payload={
        "images": [
            "https://labs-assets.bria.ai/sandbox-example-inputs/fibo2_edit_car.jpg",
        ],
        "instruction": "Change the car's paint to glossy cherry red, keep everything else the same",
    },
)
print(response.result.image_url)

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": {
    "image_url": "string",
    "seed": 0,
    "structured_instruction": "string"
  },
  "request_id": "string",
  "warning": "string"
}