Skip to content
Image Editing
/
/
Add Object by Text

Overview

Bria's Image Editing API equips builders with a comprehensive suite of tools for manipulating and enhancing images, ranging from open-ended textual edits to specialized, task-specific operations.

General Image Editing (FIBO Edit)

Powered by the FIBO models family, our newest endpoints enable open-ended editing using natural language instructions. This allows for:

  • Global Edits: Modify the style, lighting, or atmosphere of an entire image via text prompts.
  • Localized Edits: Use native masking support to precisely alter specific regions while preserving the rest of the image.
  • Structured Control: Convert text instructions into structured JSON for deterministic and auditable results.

Specialized Capabilities

For focused, high-volume tasks, the API provides optimized endpoints for specific editing capabilities:

  • Background Operations: Removal, replacement, and blur.
  • Content Manipulation: Eraser (object removal) and generative fill.
  • Image Transformation: Expansion (outpainting), resolution increase (upscaling), and automatic cropping.
  • Object & Person Tools: Person modification and automatic mask generation.

Asynchronous Requests and the Status Service Bria API v2 endpoints process requests asynchronously by default. When you make an asynchronous request, the API immediately returns a request_id and a status_url instead of the final result. Use the Status Service to track the request's progress until it reaches a completed state.

See the full guide at Status Service Documentation for complete details and usage examples.

Register and get API Access
Download OpenAPI description
image-editing.json
image-editing.yaml
Languages
Servers
https://engine.prod.bria-api.com/v2/image/edit
https://engine.prod.bria-api.com/v1

v2 endpoints

Endpoints that are part of BRIA API version 2.

Operations

Generate Structured Instruction

Request

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 by clicking here.

Headers
api_tokenstringrequired
Bodyapplication/json
instructionstringrequired

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

imagesArray of stringsrequired

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.
Default false
ip_signalboolean

If true, returns a warning for potential IP content in the instruction. Optional.

Default false
prompt_content_moderationboolean

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

Default true
visual_input_content_moderationboolean

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

Default true
curl -i -X POST \
  https://engine.prod.bria-api.com/structured_instruction/generate \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "images": [
      "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082.jpg"
    ],
    "instruction": "create a detailed realistic photo, with contemporary color scheme, and balanced exposure photo roughly based on this sketch"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​seedintegerrequired
result.​structured_instructionstringrequired
request_idstringrequired
warningstring

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

Response
application/json
{
  "result": {
    "seed": 0,
    "structured_instruction": "string"
  },
  "request_id": "string",
  "warning": "string"
}

Add Object by Text

Request

Description

Insert new objects into an image using natural language to describe the object and its position.

Example: Instruction: "Place a red vase with flowers on the table"

Input ImageOutput Image
Headers
api_tokenstringrequired
Bodyapplication/json
imagestringrequired

The source image to be handled by the API.
Supported input types:

  • Base64-encoded string - URL pointing to an image file that is publicly accessible and available at the time of processing.

Accepted formats: JPEG, JPG, PNG, WEBP.

instructionstringrequired

Natural language command.

curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/add_object_by_text \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "string",
    "instruction": "string"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedintegerrequired
result.​structured_instructionstringrequired
request_idstringrequired
warningstring

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

Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "structured_instruction": "string"
  },
  "request_id": "string",
  "warning": "string"
}

Replace Object by Text

Request

Description

Swap an existing object in an image with a new one using a natural language command.

Example: Instruction: "Replace the red apple with a green pear"

Input ImageOutput Image
Headers
api_tokenstringrequired
Bodyapplication/json
imagestringrequired

The source image to be handled by the API.
Supported input types:

  • Base64-encoded string - URL pointing to an image file that is publicly accessible and available at the time of processing.

Accepted formats: JPEG, JPG, PNG, WEBP.

instructionstringrequired

Natural language command.

curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/replace_object_by_text \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "string",
    "instruction": "string"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedintegerrequired
result.​structured_instructionstringrequired
request_idstringrequired
warningstring

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

Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "structured_instruction": "string"
  },
  "request_id": "string",
  "warning": "string"
}

v1 endpoints

Endpoints that are part of BRIA API version 1.

Operations