Skip to content
Image Editing
/
/
Expand Image

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

Blur Background

Request

Description

The background/blur Route is used to create a blur effect on the background of an image.

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.
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.

scaleinteger[ 1 .. 5 ]

A scale for determining how blurry the background of the image should be. The options are 1, 2, 3, 4, 5. This parameter is optional.

Default 5
preserve_alphaboolean

Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.

  • When true: The output image maintains the original transparency of fully and partially transparent pixels.
  • When false: The output image is fully opaque.
  • Has no effect if the input image does not include an alpha channel.
Default true
syncboolean

Specifies the response mode.

  • 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
visual_input_content_moderationboolean

When enabled, applies content moderation to input visual.

Expected behavior:

  • Processing stops if the image fails moderation.
  • Returns a 422 error with details about which parameter failed.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/blur_background \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "example"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string"
  },
  "request_id": "string"
}

Expand Image

Request

Description

The Image Expension Route can be used to expand an image, by utilizing generative AI.

You can decide on the image size of the final result as well as the position and size of the original image compared to the final result.

Alternatively, you can define a desired aspect_ratio, and the service will automatically place the input image in the center and expand the canvas to match that ratio.

In this way, you can create unique variations of your original image instead of cropping it into different aspect ratios and losing important details.

If aspect_ratio is not provided, both original_image_size and original_image_location must be specified.

Optimal input range

Input Image Area: Ensure that the ratio of the input image foreground or main subject to the canvas area is greater than 15% to achieve optimal results.

Canvas Size: The canvas size should be up to an area of 5000x5000 pixels.

Prompt: This parameter is optional. If not provided or left empty, the service will automatically generate a prompt based on the input image.

Alpha Channel Handling

  • If the input image includes an alpha channel and preserve_alpha=true, newly generated pixels inherit the alpha values of the nearest original pixels along the same row or column, ensuring smooth transparency transitions.

  • If the input image contains fully transparent pixels along any edge (top, bottom, left, or right), the request is rejected with a 422 error. Expansion is not supported in such cases to avoid undefined transparency behavior.

Here are some examples:

original image (Generated by Bria):

results:

original image (Stock Image):

results:

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Prompt Moderation – Validates the provided prompt and rejects requests containing unsafe or prohibited terms before processing starts.
  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.
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.

aspect_ratiostring or number

Automatically expands or crops the input image to the specified aspect ratio.

Either aspect_ratio or the combination of original_image_size and original_image_location must be provided.

When provided, canvas_size, original_image_size, and original_image_location are ignored.

Centers the input image, expanding edges to reach the target ratio.

Accepts either:

  • A predefined string: "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9"
  • A custom float between 0.5 and 3.0

If the target ratio equals the input image’s current ratio, no changes are made.

If the computed final dimensions exceed 5000×5000 px in total area, the input image is automatically resized so the area stays within limits.

canvas_sizeArray of integers

Desired output canvas dimensions (width, height). Defaults to [1000, 1000] if not provided. Ignored when aspect_ratio is used. Maximum allowed area is 25M pixels (i.e., width × height ≤ 5,000 × 5,000). Exceeding this returns a 400 error.

Default [1000,1000]
original_image_sizeArray of integers

The desired size of the original image inside the final canvas, as [width, height] in pixels. Ensure that the visible part of the input image (foreground or main subject) occupies more than 15% of the total canvas area for optimal results. This field is required when aspect_ratio is not provided. Must be used together with original_image_location.

original_image_locationArray of integers

The position of the top-left corner of the original image within the final canvas, provided as [x, y] in pixels. This defines where the input image will be placed before expansion occurs. The values can be outside the canvas bounds—if so, the image will be cropped accordingly. Required when aspect_ratio is not provided. Must be used together with original_image_size.

promptstring

Optional text prompt to guide the image expansion. If not provided or left empty, a prompt will be automatically generated as part of the service based on the input image. Currently, Bria supports prompts in English only and does not support special characters.

prompt_content_moderationboolean

When enabled (default: true), the input prompt is moderated before processing.

Expected Behavior

  • The prompt is scanned for NSFW content and terms that violate Bria’s ethical guidelines.
  • If the prompt fails moderation, the request is blocked and the API responds with a 422 error.
Default true
seedinteger

You can choose whether you want your generated expension to be random or predictable. You can recreate the same result in the future by using the seed value of a result from the response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

negative_promptstring

This parameter is optional. Currently, Bria supports prompts in English only and does not support special characters.

preserve_alphaboolean

Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.

  • When true: The output image maintains the original transparency of fully and partially transparent pixels.
  • When false: The output image is fully opaque.
  • Has no effect if the input image does not include an alpha channel.
Default true
syncboolean

Specifies the response mode.

  • 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
visual_input_content_moderationboolean

When enabled, applies content moderation to input visual.

Expected behavior:

  • Processing stops if the image fails moderation.
  • Returns a 422 error with details about which parameter failed.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/expand \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "example",
    "aspect_ratio": "2:3"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedinteger
result.​promptstring

Original prompt sent by the user.

request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "prompt": "string"
  },
  "request_id": "string"
}

Enhance Image

Request

Description

The /enhance_image endpoint improves the visual quality of an input image by generating richer details, sharper textures, and enhanced clarity. It also supports upscaling to higher resolutions and returns a refined version of the original visual.

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.

Unlike the Increase Resolution route, this endpoint regenerates the image to enhance visual richness while preserving essential details.

Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
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.

syncboolean

Specifies the response mode.

  • 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
visual_input_content_moderationboolean

When enabled, applies content moderation to input visual.

Expected behavior:

  • Processing stops if the image fails moderation.
  • Returns a 422 error with details about which parameter failed.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
seedinteger

Optional seed for controlling generation randomness. You can recreate the same result in the future by using the same seed with the same input parameters.

steps_numinteger[ 10 .. 50 ]

Number of enhancement steps. Higher values improve quality but increase processing time. Most quality gains occur within the first 20 steps.

Default 20
resolutionstring

Target output resolution of the enhanced image.

Default "1MP"
Enum"1MP""2MP""4MP"
preserve_alphaboolean

Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.

  • When true: The output image maintains the original transparency of fully and partially transparent pixels.
  • When false: The output image is fully opaque.
  • Has no effect if the input image does not include an alpha channel.
Default true
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/enhance \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "example",
    "resolution": "2MP"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedstring
request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": "string"
  },
  "request_id": "string"
}

v1 endpoints

Endpoints that are part of BRIA API version 1.

Operations