The Bria API

We are happy to answer any questions you may have at: support@bria.ai

Introduction

The Bria API is designed to provide a comprehensive suite of tools for generating and customizing images. With Bria, you can:

  • Generate Images Using Bria Models: Utilize pre-trained Bria models to generate high-quality images based on text prompts.

  • Train Your Own Tailored Models: Create and manage custom-tailored models to generate images in specific styles or themes using your datasets.

  • Enhance Product Imagery with E-commerce Solutions: Use specialized features to create professional product shots, packshots, and lifestyle images for e-commerce platforms.

  • Upload or Register Images: Bring your own images into Bria and modify them using various routes to suit your needs.

This document provides an overview of the API's capabilities and guides users on how to effectively implement them.

Using Bria for Image Generation

Image Generation: - Use the /text-to-image endpoints to generate any image you would like, based on the provided prompt, without needing to upload or register images first. Tailored Generation: The Tailored Generation API allows you to create and manage custom-tailored models for generating unique visual content based on your datasets. Tailored models can be trained using the API or through the Bria platform here.

Using the Tailored Generation API:

  • Dataset Management:
    • Use the /datasets endpoint to create a new dataset or retrieve existing datasets that belong to the client organization.
    • Use the /datasets/{dataset_id}/images endpoint to upload new images to a dataset or retrieve existing images that belong to the dataset.
    • Use the /datasets/{dataset_id}/images/{image_id} endpoint to get or delete a specific image from a dataset.
  • Model Management:
    • Use the /models endpoint to create a new model or retrieve all models that belong to the client organization.
    • Use the /models/{id} endpoint to retrieve a specific model by its ID or delete a specific model.
  • Training Management:
    • Use the /models/{id}/start_training endpoint to initiate the training process. Ensure that the dataset includes the minimum required number of images and has a status of 'completed' before starting training.
    • Use the /models/{id}/stop_training endpoint to stop a training job for a model.

Training a Tailored Model:

  1. Create a Dataset: Use the /datasets endpoint to create a dataset.
  2. Upload Images: Upload your images to this dataset using the /datasets/{dataset_id}/images endpoint.
  3. Create a Model: Use the /models endpoint to create a model associated with your dataset.
  4. Complete the Dataset: Ensure the dataset meets the minimum image requirements and change its status to 'completed'.
  5. Start Training: Initiate the training process using the /models/{id}/start_training endpoint.
  6. Monitor Training: Optionally, you can check the training status to monitor progress.
  7. Generate Images: Once the model is trained, use the /text-to-image/tailored/{model_id} route to generate images.

E-commerce Suite

Bria offers a variety of solutions for products and apps in the e-commerce industry, which allow to enhance product imagery for online stores and product catalogs. These solutions include:

  • Product Cutout: Create clean and professional product cutouts.

  • Product Packshot: Generate professional-standard packshots with customizable background colors and optimal product placement.

  • Lifestyle Product Shot by Text: Enrich product images by placing them in various environments using textual descriptions, enhancing appeal and providing context.

  • Lifestyle Product Shot by Image: Generate product images in enriched environments using a reference image for inspiration, allowing for creative and unique presentations.

Uploading and Modifying Images

Uploading and Registering Images:

  • Use the /register endpoint to send a new image to Bria without being uploaded to the database. This is the recommended method to onboard images to Bria when needed.

With the response from the Upload/Register Routes (visual_id), the following routes can be used without any particular order:

  • /campaign_generator - The Campaign Generator Route enables the creation of customized campaigns. It allows for the generation of visual ads, including various elements like text, images, and layout, based on specific parameters provided by the user.
  • /info - By using the Info Route, you can understand the possible changes for each object in the image. The following routes can be used if you do not require information for people, objects, and background, but rather only one of them:
    • /person/info
    • /objects/info
    • /background/info
  • /increase_resolution - The Increase Resolution route is used to upscale any image.
  • /image_to_psd - The Image To PSD route is used to create a layered PSD file out of any image.
  • /mask_generator - By using the Mask Generator, you can get all the available masks for an image, a segmentation for the image.
  • /search - Utilizing the Search Route to look for images you uploaded or registered to Bria that match a text query.
  • /search_similar_images - Utilizing the Search Similar Images Route to look for images you uploaded or registered to Bria that match the chosen image.
  • /caption - By using the Caption Route, you can get a caption that describes the given image.
  • /crop - The Crop Route is used to crop an image without a background, tightly around the remaining region of interest.

With the response from the Info Routes or from the Mask Generator, the following routes can be used without any particular order:

  • /create - Using the Create Route to create a new visual with requested changes of elements according to the /info route possibilities.
  • /objects/remove - Using the Remove Object Route to remove the objects from an image. You can also use this route with any mask, that is created manually by a user or generated by the /mask_generator endpoint.
  • /background/remove - Using the Remove BG Route to remove the background of an image.
  • /background/blur - Using the Blur BG Route to create a blur effect on the background of an image.
  • /replace_bg - Using the Replace BG Route to generate new backgrounds for an image.

Quality Predictions

The "Oracle" capability within the API can significantly elevate the user experience by offering quality prediction functionalities.

With the Oracle integrated into your product, you can ensure optimal outcomes for your end users.

This feature covers various endpoints, including /create, objects/remove, and background operations, providing you with a range of quality prediction options to enhance your product's capabilities.

The orcale value predicts the quality of the result, for each possible action.

By using the "info" for all endpoints, "person/info" endpoint for face modifications, "objects/info" for object removal, and "background/info" for background actions, you can access the Oracle's predictions, and help your users to make informed decisions.

Incorporating Oracle predictions into the API workflow enhances efficiency, minimizes errors, and fosters an optimized API experience.

Authentication

The Bria API consists of a number of methods for uploading and creating new visual assets. The REST (representational state transfer) API methods can be called directly from within your own custom code.

curl --location --request POST 'https://engine.prod.bria-api.com/v1' \
--header: 'api_token: <...>' \
...

API Access

You can register and access the API Token through Bria's platform by clicking here.

Image

Generate Image - Base model

Description

The /text-to-image/base Route empowers users to create stunning images directly from textual prompts. This model allows for generating high-quality, photorealistic and artistic, images with a resolution of up to 1024x1024 pixels, supporting a variety of aspect ratios natively to accommodate diverse creative needs.

Advanced Customization and Access:

Beyond the API, developers interested in deeper customization can access BRIA's models directly through Hugging Face. This alternative provides access to the underlying model source code, offering additional features such as Bria 2.3 Fast LoRA and ControlNets: Canny , Depth, and ReColoring. This option is ideal for developers seeking advanced control over the image generation process and those who wish to integrate cutting-edge AI directly into their workflows.

Examples:

prompt: A professional headshot of a CEO

BRIA BASE model 2.3:

prompt: A vaporwave detailed illustration of a street in London in pastel hues, under a Union Jack sky

BRIA BASE model 2.3:

prompt: A portrait of a Beautiful and playful ethereal singer, art deco, fantasy, intricate art deco golden designs, elegant, highly detailed, sharp focus, blurry background, teal and orange shades

BRIA BASE model 2.3:

Request
path Parameters
model_version
required
string

The model version you would like to use in the request.

Value: "2.3"
header Parameters
api_token
required
string
Request Body schema: application/json
required
prompt
string

The prompt you would like to use to generate images. Bria currently supports prompts in English only.

num_results
integer [ 1 .. 4 ]
Default: 4

How many images you would like to generate.

aspect_ratio
string
Default: "1:1"

The aspect ratio of the image.

Enum: "1:1" "2:3" "3:2" "3:4" "4:3" "4:5" "5:4" "9:16" "16:9"
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. Use polling for the URLs to retrieve images once ready.

seed
integer

You can choose whether you want your generated result 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 with the prompt, model type and model version. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

negative_prompt
string

Specisfy here elements that you didn't ask in the prompt, but are being generated, and you would like to exclude. This parameter is optional. Bria currently supports prompts in English only.

steps_num
integer [ 20 .. 50 ]
Default: 30

The number of iterations the model goes through to refine the generated image. This parameter is optional.

text_guidance_scale
number <float> [ 1 .. 10 ]
Default: 5

Determines how closely the generated image should adhere to the input text description. This parameter is optional.

medium
string

Which medium should be included in your generated images. This parameter is optional.

Enum: "photography" "art"
prompt_enhancement
boolean
Default: false

When set to true, enhances the provided prompt by generating additional, more descriptive variations, resulting in more diverse and creative output images. Note that turning this flag on may result in a few additional seconds to the inference time. Built with Meta Llama 3.

Responses
200

Successful operation.

209

Successful operation, a model version that is no longer available was requested. The request was redirected to the latest model version.

400

Bad request.

405

Method not allowed.

500

Internal server error.

post/text-to-image/base/{model_version}
Request samples

Generate Image - fast model

Description

The /text-to-image/fast Route is optimized for speed, enabling rapid image creation without compromising quality. This model allows for generating high-quality, photorealistic and artistic, images with a resolution of up to 1024x1024 pixels, supporting a variety of aspect ratios natively to accommodate diverse creative needs. Ideal for applications requiring quick turnaround without sacrificing image fidelity.

Advanced Customization and Access:

Beyond the API, developers interested in deeper customization can access BRIA's models directly through Hugging Face. This alternative provides access to the underlying model source code, offering additional features such as ControlNets: Canny , Depth, and ReColoring. This option is ideal for developers seeking advanced control over the image generation process and those who wish to integrate cutting-edge AI directly into their workflows.

An example:

prompt: A portrait of a Beautiful and playful ethereal singer, art deco, fantasy, intricate art deco golden designs, elegant, highly detailed, sharp focus, blurry background, teal and orange shades

BRIA FAST model 2.3:

Request
path Parameters
model_version
required
string

The model version you would like to use in the request.

Value: "2.3"
header Parameters
api_token
required
string
Request Body schema: application/json
required
prompt
string

The prompt you would like to use to generate images. Bria currently supports prompts in English only.

num_results
integer [ 1 .. 4 ]
Default: 4

How many images you would like to generate.

aspect_ratio
string
Default: "1:1"

The aspect ratio of the image.

Enum: "1:1" "2:3" "3:2" "3:4" "4:3" "4:5" "5:4" "9:16" "16:9"
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. Use polling for the URLs to retrieve images once ready.

seed
integer

You can choose whether you want your generated result 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 with the prompt, model type and model version. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

steps_num
integer [ 4 .. 10 ]
Default: 8

The number of iterations the model goes through to refine the generated image. This parameter is optional.

medium
string

Which medium should be included in your generated images. This parameter is optional.

Enum: "photography" "art"
prompt_enhancement
boolean
Default: false

When set to true, enhances the provided prompt by generating additional, more descriptive variations, resulting in more diverse and creative output images. Note that turning this flag on may result in a few additional seconds to the inference time.

Responses
200

Successful operation.

400

Bad request.

405

Method not allowed.

500

Internal server error.

post/text-to-image/fast/{model_version}
Request samples

Generate Image - HD model

Description

The /text-to-image/hd Route is tailored for projects demanding the utmost in image detail and clarity. This model allows for generating high-quality, photorealistic and artistic, images with unparalleled resolution of 1920x1080 (1:1 1536x1536) pixel, supporting a variety of aspect ratios natively to accommodate diverse creative needs.

Advanced Customization and Access:

Beyond the API, developers interested in deeper customization can access BRIA's models directly through Hugging Face. This alternative provides access to the underlying model source code, offering additional features such as ControlNets: Canny , Depth, and ReColoring. This option is ideal for developers seeking advanced control over the image generation process and those who wish to integrate cutting-edge AI directly into their workflows.

Examples:

prompt: A photo of detailed short female blond hair viewed from behind, with rich texture and clearly visible individual strands that give depth and realism, and featuring subtle waves reflect light

BRIA HD model 2.2:

prompt: A portrait of a Beautiful and playful ethereal singer, art deco, fantasy, intricate art deco golden designs, elegant, highly detailed, sharp focus, blurry background, teal and orange shades

BRIA HD model 2.2:

Request
path Parameters
model_version
required
string

The model version you would like to use in the request.

Value: "2.2"
header Parameters
api_token
required
string
Request Body schema: application/json
required
prompt
string

The prompt you would like to use to generate images. Bria currently supports prompts in English only.

num_results
integer [ 1 .. 4 ]
Default: 4

How many images you would like to generate.

aspect_ratio
string
Default: "1:1"

The aspect ratio of the image.

Enum: "1:1" "2:3" "3:2" "3:4" "4:3" "4:5" "5:4" "9:16" "16:9"
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous, and applicable to single-image requests. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. Use polling for the URLs to retrieve images once ready.

seed
integer

You can choose whether you want your generated result 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 with the prompt, model type and model version. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

negative_prompt
string

Specisfy here elements that you didn't ask in the prompt, but are being generated, and you would like to exclude. This parameter is optional. Bria currently supports prompts in English only.

steps_num
integer [ 20 .. 50 ]
Default: 30

The number of iterations the model goes through to refine the generated image. This parameter is optional.

text_guidance_scale
number <float> [ 1 .. 10 ]
Default: 5

Determines how closely the generated image should adhere to the input text description. This parameter is optional.

medium
string

Which medium should be included in your generated images. This parameter is optional.

Enum: "photography" "art"
prompt_enhancement
boolean
Default: false

When set to true, enhances the provided prompt by generating additional, more descriptive variations, resulting in more diverse and creative output images. Note that turning this flag on may result in a few additional seconds to the inference time.

Responses
200

Successful operation.

400

Bad request.

405

Method not allowed.

500

Internal server error.

post/text-to-image/hd/{model_version}
Request samples

Generate Campaign

Description

The campaign_generator Route enables users to create visual campaigns for various ad channels using a visual_id. This route facilitates the generation of templates featuring diverse layouts that incorporate elements like text, logos, and calls to action (CTA), tailored to various resolutions (placements) and target audiences.

Ad backgrounds are expanded to fit the necessary layout specifications.

Examples

original image (Generated by Bria):

Results:

Request
path Parameters
visual_id
required
string
header Parameters
api_token
required
string
Request Body schema: application/json
required
sid
string

Session ID. Optional. obtained from a previous route response. Optional.

preset_id
string

Preset id. Optional. The brand preset that defines which logo, colors and typography should be used. If one isn’t provided, and some or none of the following are not provided (header1_color, header1_font, header1_size,header1_color, header1_font, header1_size, logo), the default public brand will be used.

template_id
string

Template ID, Mandatory. template_id or layout_ids must be provided. You can contact Bria to get your own templates and layouts.

layout_ids
Array of strings

Layout IDs, Mandatory. the ids of the layouts to generate. template_id or layout_ids must be provided. You can contact Bria to get your own templates and layouts.

logo
string

Logo URL. Optional. Supported inputs include public image URL or a URL inside Bria s3.

cta
string

CTA image URL. Optional. Supported inputs include public image URL or a URL inside Bria s3.

header1_text
string

Header1 text. Optional.

header1_font
string

Header1 font. Optional. Supported inputs include public ttf URL or a URL inside Bria s3.

header1_size
integer

Header1 size. Optional.

header1_color
Array of integers

Header1 color in hex format. Optional.

header2_text
string

Header2 text. Optional.

header2_font
string

Header2 font. Optional. Supported inputs include public tiff URL or a URL inside Bria s3.

header2_size
integer

Header2 size. Optional.

header2_color
Array of integers

Header2 color in hex format. Optional.

seed
integer

Seed used for image expansion. Optional. Use this to recreate the same ad.

background_type
string
Default: "original"

Background type. Optional.

Enum: "original" "generated" "solid"
bg_prompt
string

Background generation prompt. Mandatory when background_type is generated. Bria currently supports prompts in English only.

bg_seed
integer

Background seed. Optional. Relevant when background_type is generated.

bg_color
string

Background color in hex code. Mandatory when background_type is solid.

Responses
200

Successful response with generated campaign visuals.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

post/{visual_id}/campaign_generator
Request samples
Response samples
application/json
{
  • "ads": [
    ]
}

Expand Image

Description

The Image Expension Route can be used to expand an image and its background, 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.

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

Optimal input range

Input Image Area: Ensure that the input image area is more than 15% of the canvas area to achieve optimal results.

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

original image (Generated by Bria):

results:

original image (Stock Image):

results:

You can use this route on a modified image by providing the sid from the response of the previously used route.

This route returns both the URL and the sid associated with the updated image.

Request
path Parameters
visual_id
required
string

The visual id of the image which the user wishes to expand

Example: 8487fb411f3c6716
header Parameters
api_token
required
string
Request Body schema: application/json
canvas_size
Array of integers
Default: [1000,1000]

The desired size of the final image, after the expansion. should have an area of less than 5000x5000 pixels.

original_image_size
Array of integers

The desired size of the original image, inside the full canvas. Should be over 15% of the canvas area.

original_image_location
Array of integers

The desired location of the original image, inside the full canvas. Provide the location of the upper left corner of the original image. The location can also be outside the canvas (the original image will be cropped).

prompt
string

Text on which you wish to base the image expansion. This parameter is optional. Bria currently supports prompts in English only.

seed
integer

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.

sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to modify the result of that route, please provide this information. This parameter is optional.

negative_prompt
string

This parameter is optional. Bria currently supports prompts in English only.

Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

512

Insufficient resources to process the request.

post/{visual_id}/image_expansion
Request samples

Increase Resolution - Isolated

Description

The Isolated Increase Resolution Route is used to upsacle the resolution of any image.

The main difference between the regular and this isolated Increase Resolution endpoint is that you can use this endpoint without uploading or registering the image to Bria.

Constraints

The Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned.

It's possible to increase the resolution of an image up to a total area of 8192x8192 pixels.

Increase the Resolution of an image using the image file

In our documentation request example, we demonstrate how to Increase the Resolutio of an image using the image URL.

If you want to use an image from a file, follow the example below:

  import requests

  url = "https://engine.prod.bria-api.com/v1/image/increase_resolution?desired_increase=2"

  payload = {}
  files=[
    ('file',('image_name.jpeg',open('/path_to_local_file/image_name.jpeg','rb'),'image/jpeg'))
  ]
  headers = {
    'api_token': 'xxxx'
  }

  response = requests.request("POST", url, headers=headers, data=payload, files=files)

  print(response.text)
            
Request
query Parameters
desired_increase
integer

The resolution multiplier. The possible value are 2,4. It's possible to increase the resolution of an image up to a total area of 8,192x8,192 pixels.

Example: desired_increase=2
header Parameters
api_token
required
string
Request Body schema: application/x-www-form-urlencoded
required
file
string <binary>

The image file you would like to increase the resolution for. Minimum resolution supported for width and/or height is 216 pixels.

image_url
string

The URL of the image file you would like to increase the resolution for. The URL should lead to an image publicly available online. Either a file or an image_url should be provided. If both are provided, then the route will use image_url. Minimum resolution supported for width and/or height is 216 pixels.

Responses
200

Successful operation.

400

Bad request

405

Method not allowed.

460

Failed to download image.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Increase Resolution

Description

The Increase Resolution Route is used to upsacle the resolution of any image.

You can also use this route on a modified image by providing the sid from the response of the previously used route.

Request
path Parameters
visual_id
required
string

visual id of the image the user would like to upscale

Example: 8487fb411f3c6716
query Parameters
sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to apply on the result of that route, please provide this information. This parameter is optional.

Example: sid=Remove this parameter if the image has not been modified using Bria.
desired_increase
integer

The resolution multiplier. The possible value are 2,4.

Example: desired_increase=2
header Parameters
api_token
required
string
Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Delayer Image

Description

The Image to PSD Route is used to create a layered PSD file from any image.

The image is divided into different layers (depending on the image): a background layer with all identified objects removed, a foreground layer without the background, and a layer for each object.

You can also use this route on a modified image by providing the sid from the response of the previously used route.

Request
path Parameters
visual_id
required
string

visual id of the image, for which the user would like to create a layered PSD file

Example: 8487fb411f3c6716
query Parameters
sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to apply on the result of that route, please provide this information. This parameter is optional.

Example: sid=Remove this parameter if the image has not been modified using Bria.
header Parameters
api_token
required
string
Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Crop out foreground

Description

The Crop Route is used to crop an image without a background tightly around the remaining region of interest.

You can also use this route on a modified image by providing the sid from the response of the previously used route. You can utilize Bria's /background/remove endpoint and then use the result of that route in the /crop route.

This route returns both the URL and the sid associated with the updated image.

On images without transparent backgrounds, the response will be the provided image at the selected resolution.

Request
path Parameters
visual_id
required
string

visual id of the image the user would like to crop

Example: 8487fb411f3c6716
query Parameters
sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to modify the result of that route, please provide this information. This parameter is optional.

Example: sid=Remove this parameter if the image has not been modified using Bria.
header Parameters
api_token
required
string
Request Body schema: application/json
optional
padding
integer
Default: 0

Cropping the object with padding around it. Currently, padding is applied to all four borders of the remaining region. This parameter is optional.

Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Tailored Generation

Generate Image - Tailored model

Description

This route allows you to generate images using a tailored model. Tailored models are trained using your own datasets to create unique visual styles, character illustrations, or icons. You can train a tailored model through the API or using the Bria platform.

Overview of Tailored Model API

The Tailored Model API provides a set of endpoints to manage the entire lifecycle of a tailored model:

  1. Dataset Management: Create and manage datasets which will be used to train your tailored models. You can:

    • Create and Retrieve Datasets: Use the /datasets endpoint to create a new dataset or retrieve existing datasets that belong to the client organization.
    • Upload and Retrieve Images: Use the /datasets/{dataset_id}/images endpoint to upload a new image to a dataset or retrieve existing images that belong to the dataset.
    • Manage Individual Images: Use the /datasets/{dataset_id}/images/{image_id} endpoint to get or delete a specific image from a dataset.
  2. Model Management: Create and manage models based on your datasets. You can:

    • Create and Retrieve Models: Use the /models endpoint to create a new model or retrieve all models that belong to the client organization.
    • Get and Delete Specific Models: Use the /models/{id} endpoint to retrieve a specific model by its ID or delete a specific model.
  3. Training Management: Start and stop training jobs for your models. You can:

    • Start Training: Use the /models/{id}/start_training endpoint to initiate the training process. Note that the dataset must include the minimum required number of images and have a status of 'completed' before training can start.
    • Stop Training: Use the /models/{id}/stop_training endpoint to stop a training job for a model.

Training a Tailored Model

To train a tailored model via the API:

  1. Create a Dataset: Use the /datasets endpoint to create a dataset.
  2. Upload Images: Upload your images to this dataset using the /datasets/{dataset_id}/images endpoint.
  3. Create a Model: Use the /models endpoint to create a model associated with your dataset.
  4. Complete the Dataset: Ensure the dataset meets the minimum image requirements and change its status to 'completed'.
  5. Start Training: Initiate the training process using the /models/{id}/start_training endpoint. Training of a tailored model takes between 1-3 hours.
  6. Monitor Training: Optionally, you can check the training status to monitor progress.
  7. Generate Images: Once the model is trained, use this route to generate images.

Alternatively, you can use the Bria platform to manage and train your tailored models through a user-friendly interface. Access the Bria platform here.

Request
path Parameters
model_id
required
string

The model id of the tailored model you would like to use in the request.

header Parameters
api_token
required
string
Request Body schema: application/json
required
prompt
string

The prompt you would like to use to generate images. Bria currently supports prompts in English only.

num_results
integer [ 1 .. 4 ]
Default: 4

How many images you would like to generate.

aspect_ratio
string
Default: "1:1"

The aspect ratio of the image.

Enum: "1:1" "2:3" "3:2" "3:4" "4:3" "4:5" "5:4" "9:16" "16:9"
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. Use polling for the URLs to retrieve images once ready.

seed
integer

You can choose whether you want your generated result 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 with the prompt, model type and model version. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

steps_num
integer [ 4 .. 20 ]
Default: 8

The number of iterations the model goes through to refine the generated image. This parameter is optional.

Responses
200

Successful operation.

400

Bad request.

405

Method not allowed.

500

Internal server error.

post/text-to-image/tailored/{model_id}
Request samples

Create Dataset

Description This endpoint allows the creation of a new dataset that will belong to the organization associated with the used API token. The dataset will be created with a default status of "draft".

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
use_case
string

Specifies the use case of the dataset.

Enum: "illustrative_style" "illustrative_single_object"
style_description
string

Description of the visual style. This is currently required but might change in the future.

name
string

Name of the dataset.

Responses
201

Dataset successfully created.

400

Bad request.

401

Unauthorized.

500

Internal server error.

post/tailored-gen/datasets
Request samples
Response samples
application/json
{
  • "id": 123,
  • "use_case": "illustrative_style",
  • "style_description": "A 2d vibrant and colorful flat illustration.",
  • "name": "My Illustrations",
  • "status": "draft",
  • "images_count": 0,
  • "images": [ ],
  • "created_at": "2024-05-26T12:00:00Z",
  • "updated_at": null
}

Get Datasets

Description Retrieve a list of datasets that belong to the organization associated with the used API token. If no datasets are found, an empty array is returned.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

401

Unauthorized.

500

Internal server error.

get/tailored-gen/datasets
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Get Dataset by ID

Description Retrieve a specific dataset by its ID. The response includes all the details of the dataset and an array of associated images.

Request
path Parameters
id
required
integer

The ID of the dataset to retrieve.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

401

Unauthorized.

404

Dataset with the specified ID does not exist.

500

Internal server error.

get/tailored-gen/datasets/{id}
Request samples
Response samples
application/json
{
  • "id": 123,
  • "use_case": "illustrative_style",
  • "style_description": "A 2d vibrant and colorful flat illustration.",
  • "name": "My Illustrations",
  • "status": "draft",
  • "images": [
    ],
  • "created_at": "2024-05-26T12:00:00Z",
  • "updated_at": null
}

Update Dataset

Description Update the details of a specific dataset by its ID. If the status of the dataset is completed, the style_description and use_case cannot be updated. Additionally, if the status is completed, it cannot be returned to draft if a model has already been trained based on it.

Request
path Parameters
id
required
integer

The ID of the dataset to update.

header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
use_case
string

Specifies the use case of the dataset. Accepted values are "illustrative_style" and "illustrative_single_object".

style_description
string

Description of the visual style.

name
string

Name of the dataset.

status
string

Status of the dataset.

Value: "COMPLETED"
Responses
200

Successful operation.

400

Bad request.

401

Unauthorized.

404

Dataset with the specified ID does not exist.

409

Conflict.

500

Internal server error.

put/tailored-gen/datasets/{id}
Request samples
Response samples
application/json
{
  • "id": 123,
  • "use_case": "illustrative_style",
  • "style_description": "A 2d vibrant and colorful flat illustration.",
  • "name": "My Illustrations",
  • "status": "draft",
  • "images": [],
  • "created_at": "2024-05-26T12:00:00Z",
  • "updated_at": "2024-05-26T12:00:00Z"
}

Delete Dataset

Description Delete a specific dataset. Changes status to deleted.

Request
path Parameters
id
required
integer

The ID of the dataset to delete.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
204

Dataset successfully deleted.

404

Dataset with the specified ID does not exist.

409

Conflict.

500

Internal server error.

delete/tailored-gen/datasets/{id}
Request samples
Response samples
application/json
{
  • "error": "Cannot delete a dataset that is used by a model that is in training or has the status 'ready'."
}

Upload Image to Dataset

Description Upload a new image to a specific dataset. One of the following parameters, file or image_url, must be provided.

Upload a new image using the image file

In our documentation request example, we demonstrate how to upload a new image using the image URL.

If you want to use an image from a file, follow the example below:

  import requests

  url = "/tailored-gen/datasets/{dataset_id}/images"

  payload = {}
  files=[
    ('file',('image_name.jpeg',open('/path_to_local_file/image_name.jpeg','rb'),'image/jpeg'))
  ]
  headers = {
    'api_token': 'xxxx'
  }

  response = requests.request("POST", url, headers=headers, data=payload, files=files)

  print(response.text)
Request
path Parameters
dataset_id
required
integer

The ID of the dataset to which the image will be uploaded.

header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: multipart/form-data
file
string <binary>

Image file to upload. Either file or image_url must be provided.

image_url
string

URL of the image to upload. Either file or image_url must be provided.

image_name
string

Name of the image. If not provided, the file name will be used. If neither is available, a default name will be set. This field is only relevant when an image_url is provided.

Responses
201

Image successfully uploaded.

400

Bad request.

404

Dataset with the specified ID does not exist.

409

Conflict.

412

Precondition Failed.

415

Unsupported Media Type.

422

Unprocessable Entity.

500

Internal server error.

post/tailored-gen/datasets/{dataset_id}/images
Request samples
Response samples
application/x-www-form-urlencoded
id=123&dataset_id=123&caption=A%20vibrant%202D%20illustration%20of%20a%20sunny%20day%20with%20children%20playing%20in%20a%20park.&file_name=Illustration1.png&image_url=https%3A%2F%2Fexample.com%2Fimage1.png&thumbnail_url=https%3A%2F%2Fexample.com%2Fimage1_thumbnail.png&created_at=2024-05-26T12%3A00%3A00Z

Get Images

Description Retrieve a list of images in a specific dataset.

Request
path Parameters
dataset_id
required
integer

The ID of the dataset for which to retrieve images.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

404

Dataset with the specified ID does not exist.

500

Internal server error.

get/tailored-gen/datasets/{dataset_id}/images
Request samples
Response samples
application/json
[]

Get Image by ID

Description Retrieve a specific image by its ID.

Request
path Parameters
dataset_id
required
integer

The ID of the dataset to which the image belongs.

image_id
required
integer

The ID of the image to retrieve.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

404

Not Found.

500

Internal server error.

get/tailored-gen/datasets/{dataset_id}/images/{image_id}
Request samples
Response samples
application/json
{}

Delete Image

Description Delete a specific image.

Request
path Parameters
dataset_id
required
integer

The ID of the dataset to which the image belongs.

image_id
required
integer

The ID of the image to delete.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
204

Image successfully deleted.

404

Not Found.

409

Conflict.

500

Internal server error.

delete/tailored-gen/datasets/{dataset_id}/images/{image_id}
Request samples
Response samples
application/json
{
  • "error": "Image with the specified ID does not exist."
}

Create Model

Description Create a new model.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
name
string

Name of the model.

description
string

Description of the model.

dataset_id
integer

ID of the dataset to be used for training the model.

Responses
201

Model successfully created.

404

Dataset with the specified ID does not exist.

500

Internal server error.

post/tailored-gen/models
Request samples
Response samples
application/json
{
  • "id": 123,
  • "name": "My Model",
  • "description": "This model is designed for generating illustrative style images.",
  • "status": "Created",
  • "dataset_id": 123,
  • "created_at": "2024-05-26T12:00:00Z"
}

Get Models

Description Retrieve a list of models. If there are no models, an empty array is being returned.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

401

Unauthorized.

500

Internal server error.

get/tailored-gen/models
Request samples
Response samples
application/json
[
  • {
    },
  • {
    }
]

Get model by ID

Description Retrieve a specific model by its ID.

Request
path Parameters
id
required
integer

The ID of the model to retrieve.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Successful operation.

404

Model with the specified ID does not exist.

500

Internal server error.

get/tailored-gen/models/{id}
Request samples
Response samples
application/json
{
  • "id": 123,
  • "name": "My Model",
  • "description": "This model is designed for generating illustrative style images.",
  • "status": "Created",
  • "dataset_id": 123,
  • "created_at": "2024-05-26T12:00:00Z"
}

Delete model

Description Delete a specific model.

Request
path Parameters
id
required
integer

The ID of the model to delete.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
204

Model successfully deleted.

404

Model with the specified ID does not exist.

500

Internal server error.

delete/tailored-gen/models/{id}
Request samples
Response samples
application/json
{
  • "status": "Deleted"
}

Start Training

Description Start a new training job for a specific model. Training of a tailored model takes between 1-3 hours.

Request
path Parameters
id
required
integer

The ID of the model for which to start the training job.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Training job successfully started.

404

Model with the specified ID does not exist.

409

Conflict.

412

Precondition Failed.

500

Internal server error.

post/tailored-gen/models/{id}/start_training
Request samples
Response samples
application/json
{
  • "id": 123,
  • "status": "Training In Progress"
}

Stop Training

Description Stop a specific training job for a model.

Request
path Parameters
id
required
integer

The ID of the model for which to stop the training job.

header Parameters
api_token
required
string

API token associated with the organization.

Responses
200

Training job successfully stopped.

404

Model with the specified ID does not exist.

409

Conflict.

500

Internal server error.

post/tailored-gen/models/{id}/stop_training
Request samples
Response samples
application/json
{
  • "error": "Model with the specified ID does not exist."
}

E-commerce Suite

Product Cutout

This capability allows you to create a precise cutout of a product from any given image. This feature is especially valuable for e-commerce platforms and applications, serving as a fundamental building block for crafting a user-friendly interface.

The following interactive Colab notebook demonstrates how to use this API effectively. Explore the example code and try it out for yourself to fully appreciate the potential of this suite.

Request
header Parameters
api_token
required
string

API token associated with the organization

Request Body schema: application/json
sku
string

The Stock Keeping Unit identifier for the product. This parameter is optional.

image_url
string

The URL of the image containing the product to be cut out. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

file
string <binary>

The image file containing the product to be cut out, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

Responses
200

Successful operation.

400

Bad request.

401

Unauthorized. Invalid API key or authentication token.

404

Not found. Image could not be found at the provided URL.

413

Payload too large. Image file size exceeds the 12MB limit.

415

Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.

451

Unavailable for legal reasons.

460

Failed to download image.

500

Internal server error. An error occurred on the server.

post/product/cutout
Request samples
Response samples
application/json
{
  • "result_url": "URL"
}

Product Packshot

The Product Pack Shot feature is designed to create professional standard pack shots. The output is a 2000x2000 px image, with the product size and location according to best practices. This feature can allow users to take any photo of a product and transform it into a professional pack shot, placing the product on a clean, seamless background, typically white but customizable to any color.

The following interactive Colab notebook demonstrates how to use this API effectively. Explore the example code and try it out for yourself to fully appreciate the potential of this suite.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
sku
string

The Stock Keeping Unit identifier for the product. This parameter is optional.

image_url
string

The URL of the product image or product cutout. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

file
string <binary>

The product image or product cutout file, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

background_color
string
Default: "#FFFFFF"

The background hex color code for the pack shot. Optionally, use 'transparent' for a transparent background.

Responses
200

Successful operation.

400

Bad request.

401

Unauthorized. Invalid API key or authentication token.

404

Not found. Image could not be found at the provided URL.

413

Payload too large. Image file size exceeds the 12MB limit.

415

Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.

451

Unavailable for legal reasons.

460

Failed to download image.

500

Internal server error. An error occurred on the server.

post/product/packshot
Request samples
Response samples
application/json
{
  • "result_url": "URL"
}

Lifestyle Product Shot by Text

Creates enriched product shots by placing them in various environments using textual descriptions. Additionally, you can change the image size of the final result as well as the positioning of the product in the image. This will enable you to create new and unique variations of your original image.

The following interactive Colab notebook demonstrates how to use this API effectively. Explore the example code and try it out for yourself to fully appreciate the potential of this suite.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
sku
string

The Stock Keeping Unit identifier for the product. This parameter is optional.

sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. It is recommended to use sync=false for optimal performance. When generating more than 1 result, you should use the value false. When placement_type is automatic, sync has to be false.

fast
boolean
Default: false

Determines the generation mode. When true, the generation will utilize the fast mode which provides the best balance between speed and quality. The false, the regular mode will be utilized.

image_url
string

The URL of the product shot to be placed in a lifestyle shot. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

file
string

The product shot file to be placed in a lifestyle shot, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

scene_description
string

Text description of the new scene or background for the provided product shot. Bria currently supports prompts in English only.

optimize_description
boolean
Default: false

It is recommended to set this parameter to 'true'. When true, an additional logic takes the scene_description that was included and adjusts it to achieve optimal results. Built with Meta Llama 3.

num_results
integer
Default: 1

The number of lifestyle product shots you would like to generate. You will get num_results10 results when placement_type=automatic and according to the number of required placementsnum_results if placement_type=manual_placement.

exclude_elements
string

Elements or features that should be excluded from the generated scene. This parameter is optional. Bria currently supports descriptions in English only.

placement_type
string

This parameter allows you to control the positioning of the product in the image. Choosing 'original' will preserve the original position of the product in the image. Choosing 'automatic' will generate results with the 10 recommended positions for the product. Choosing 'manual_placement' will allow you to select predefined positions (using the parameter 'manual_placement_selection'). Selecting 'manual_padding' will allow you to control the position and size of the image by defining the desired padding in pixels around the product.

Enum: "original" "automatic" "manual_placement" "manual_padding"
shot_size
Array of integers
Default: [1000,1000]

The desired size of the final product shot. For optimal results, the total number of pixels should be around 1,000,000. This parameter is only relevant when placement_type=automatic or placement_type=manual_placement.

manual_placement_selection
Array of strings
Default: ["upper_left"]

If you've selected placement_type=manual_placement, you should use this parameter to specify which placements/positions you would like to use from the list. You can select more than one placement in one request.

Items Enum: "upper_left" "upper_right" "bottom_left" "bottom_right" "right_center" "left_center" "upper_center" "bottom_center" "center_vertical" "center_horizontal"
padding_values
Array of integers
Default: [0,0,0,0]

The desired padding in pixels around the product, when using placement_type=manual_padding. The order of the values is [top, bottom, left, right]. For optimal results, the total number of pixels, including padding, should be around 1,000,000. It is recommended to first use the product cutout API, get the cutout and understand the size of the result, and then define the required padding and use the cutout as an input for this API.

Responses
200

Successful operation.

400

Bad request. Missing or invalid parameters.

401

Unauthorized. Invalid API key or authentication token.

404

Not found. Image could not be found at the provided URL.

413

Payload too large. Image file size exceeds the 12MB limit.

415

Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.

451

Unavailable for legal reasons.

460

Failed to download image.

500

Internal server error. An error occurred on the server.

post/product/lifestyle_shot_by_text
Request samples
Response samples
application/json
{
  • "result": [
    ]
}

Lifestyle Product Shot by Image (Coming Soon)

Generates product images in enriched environments using a reference image for inspiration. Additionally, you can change the image size of the final result as well as the positioning of the product in the image. This will enable you to create new and unique variations of your original image.

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
sku
string

The Stock Keeping Unit identifier for the product. This parameter is optional.

sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. It is recommended to use sync=false for optimal performance. When generating more than 1 result, you should use the value false. When placement_type is automatic, sync has to be false.

image_url
string

The URL of the product shot to be placed in a lifestyle shot. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

file
string <binary>

The product shot file to be placed in a lifestyle shot, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

reference_image_url
string

The URL of the reference image to be used for generating the lifestyle shot. If both reference_image_url and reference_image_file are provided, reference_image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

reference_image_file
string <binary>

The reference image file to be used for generating the lifestyle shot, in base64 format. Used if reference_image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

num_results
integer
Default: 1

The number of lifestyle product shots you would like to generate. When placement_type is automatic or manual_placement, num_results should be 1. You will get 10 results when automatic and according to the number of required placements if manual_placement.

placement_type
string

This parameter allows you to control the positioning of the product in the image. Choosing 'original' will preserve the original position of the product in the image. Choosing 'automatic' will generate results with the 10 recommended positions for the product. Choosing 'manual_placement' will allow you to select predefined positions (using the parameter 'manual_placement_selection'). Selecting 'manual_padding' will allow you to control the position and size of the image by defining the desired padding in pixels around the product.

Enum: "original" "automatic" "manual_placement" "manual_padding"
shot_size
Array of integers
Default: [1000,1000]

The desired size of the final product shot. For optimal results, the total number of pixels should be around 1,000,000. This parameter is only relevant when placement_type=automatic or placement_type=manual_placement.

manual_placement_selection
Array of strings
Default: ["upper_left"]

If you've selected placement_type=manual_placement, you should use this parameter to specify which placements/positions you would like to use from the list. You can select more than one placement in one request.

Items Enum: "upper_left" "upper_right" "bottom_left" "bottom_right" "right_center" "left_center" "upper_center" "bottom_center" "center_vertical" "center_horizontal"
padding_values
Array of integers
Default: [0,0,0,0]

The desired padding in pixels around the product, when using placement_type=manual_padding. The order of the values is [top, bottom, left, right]. For optimal results, the total number of pixels, including padding, should be around 1,000,000. It is recommended to first use the product cutout API, get the cutout and understand the size of the result, and then define the required padding and use the cutout as an input for this API.

Responses
200

Successful operation.

400

Bad request. Missing or invalid parameters.

401

Unauthorized. Invalid API key or authentication token.

404

Not found. Image could not be found at the provided URL.

413

Payload too large. Image file size exceeds the 12MB limit.

415

Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.

451

Unavailable for legal reasons.

460

Failed to download image.

500

Internal server error. An error occurred on the server.

post/product/lifestyle_shot_by_image
Request samples
Response samples
application/json
{
  • "result": [
    ]
}

Consistent Product Shots (Coming Soon)

Description This feature allows users to create consistent product shots by providing either a textual description of a scene or an image, along with a group of product images. The resulting consistent product shots are ideal for use on social media, e-commerce websites, product catalogs, and other marketing materials, ensuring a uniform and professional appearance across all platforms.

Responses
200

Successful operation.

post/products/consistent_shots
Request samples

Contextual Keyword Extraction (Coming Soon)

Description This feature allows users to extract relevant keywords from an image and its context, focusing on the primary product rather than secondary elements. This capability enhances search optimization in e-commerce by ensuring that the keywords accurately represent the product being sold. It can be particularly useful for improving product searchability on e-commerce websites, enhancing SEO for product listings, automating content management, and optimizing social media marketing efforts.

Responses
200

Successful operation.

post/product/contextual_keyword_extraction
Request samples

Image Onboarding

Register Image

Description

A new visual can be registered to Bria without being uploaded to the database using the Register Route. This route returns a visual identification to the user. This is the recommended method to onboard images to Bria, when needed.

It's the first step for consuming the Bria API for new visuals (instead of using the /upload route).

Response

The visual id in the response of the Register Route must be kept by the user in order to query image info, modify the image and use the search routes.

{ "visual_id": "9ea9a4d2d19977a7c" }

The visual_id in the response of the /upload route will be used for all other routes. Store the visual_id in your database and map it to your image identification method for easy reference

Bria generative Web tool

The registered visual can be seen and used in the Bria generative web tool in cases where the tool is licensed as part of the project.

To do so, the user can access the following url: https://labs.bria.ai/gallery/{visual_id}, where the {visual_id} comes from the response of the /upload route.

Constraints

Files should not be larger than 12MB. The status code 413 will be returned if the file exceeds its maximum size.

The Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned.

Request
header Parameters
api_token
required
string
Request Body schema: application/json
required
org_image_key
string

The internal image id in your API, of the image you would like to register to Bria. If accessing your images requires authentication, you will be able to register them using org_image_key only after giving Bria the API authentication information. It is also possible to register images using an org_image_key, without any authentication data.

image_url
string

The URL of the image you would like to register to Bria. The URL should lead to an image publicly available online. Either an org_image_key or an image_url should be provided. If both are provided, then the route will use image_url and org_image_key will be saved but not used. Images can only be registered using an image_url if they do not require authentication.

is_private
string
Default: true

The image can be included in the Bria public gallery (is_private=false) or only in the Bria gallery of your organization (is_private=true). This parameter is optional and the default value is true.

Responses
200

Successful operation.

208

Image already registered.

400

Bad request.

405

Method not allowed.

460

Failed to download image.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

post/register
Request samples
Response samples
application/json
{
  • "visual_id": "string"
}

Remove Image

Description

With this route, you can remove an image from the gallery of your organization. The image won't be removed from Bria.

Request
path Parameters
visual_id
required
string
Example: b3cecc33cc31cc31
header Parameters
api_token
required
string
Responses
200

Successful operation.

400

Bad request.

405

Method not allowed.

460

Failed to download image.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

post/{visual_id}/remove_image
Request samples

Get Image info

Description

The Info Route is used to retrieve useful information on a specific visual that was previously uploaded or registered.

Additionally, it provides the following:

  1. A description of each object and element within the scene

  2. The available changes, which are supported by the Bria API for each object and element

  3. The Oracle value for each available change. The orcale value predicts the quality of the result, for each possible action. The possible oracle values for object removal or background actions are true and false. The possible values for person modification are high, medium, and low.

Request
path Parameters
visual_id
required
string

visual id of the image, received after using the /upload or /register route.

Example: 8487fb411f3c6716
query Parameters
lean
boolean
Default: false

Set the value 'true' for this parameter if you wish to receive only the high-level information (currently, this means only the description, org_height, and org_width) from the info route. This parameter is optional and as default the value is 'false'.

header Parameters
api_token
required
string
Responses
200

Successful operation.

205

File hasn’t finished onboarding. Please call /info again until you get 200.

400

One of the details does not meet specification. Please call /info again.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

get/{visual_id}/info
Request samples
Response samples
application/json
{
  • "description": "Coming Soon",
  • "scene": [
    ]
}

Background

Get Background info

Description

The Background/Info Route is used to retrieve useful information on the background of a specific visual that was previously uploaded to the database.

Additionally, it provides the following:

  1. The available background actions, which are supported by the Bria API.

  2. The Oracle value for each available action. The orcale value predicts the quality of the result, for each possible action. The possible oracle values for background actions are true and false.

This route should be used instead of the main /info route when you are only interested in the available actions for the background of the image. With this route, you will save runtime by only obtaining information that is relevant to your needs.

Request
path Parameters
visual_id
required
string

visual id of the image, received after using the /upload or register route.

Example: f49943971e3039c7
header Parameters
api_token
required
string
Responses
200

Successful operation.

205

File hasn’t finished onboarding. Please call /info again until you get 200.

400

One of the details does not meet specification. Please call person/info again.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

get/{visual_id}/background/info
Request samples
Response samples
application/json
{
  • "id": "67a9746d4c7939e2753869cdb4330852b6e2472b8110ae1fb59f8c033fc7fe1f",
  • "type": "background",
  • "labels": null,
  • "rect": null,
  • "actions": {
    },
  • "oracle": {
    }
}

Remove Background - Isolated

Description

The Remove BG Route can be used to remove the background of an image.

The main difference between the regular and this isolated background removal endpoint is that you can use this endpoint without uploading or registering the image to Bria.

Constraints

The Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned.

Remove the background from an image using the image file

In our documentation request example, we demonstrate how to remove the background from an image using the image URL.

If you want to use an image from a file, follow the example below:

  import requests

  url = "https://engine.prod.bria-api.com/v1/background/remove"

  payload = {}
  files=[
    ('file',('image_name.jpeg',open('/path_to_local_file/image_name.jpeg','rb'),'image/jpeg'))
  ]
  headers = {
    'api_token': 'xxxx'
  }

  response = requests.request("POST", url, headers=headers, data=payload, files=files)

  print(response.text)
Request
header Parameters
api_token
required
string
Request Body schema: application/x-www-form-urlencoded
required
file
string <binary>

The image file you would like to remove the background from.

image_url
string

The URL of the image file you would like to remove the background from. The URL should lead to an image publicly available online. Either a file or an image_url should be provided. If both are provided, then the route will use image_url.

Responses
200

Successful operation.

206

File value was not provided.

400

Request doesn't contain file part.

405

Method not allowed.

415

Unsupported media type.

460

Failed to download image.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

post/background/remove
Request samples
Response samples
application/json
{
  • "result_url": "string"
}

Remove Background

Description

The Remove BG Route is used to remove the background of a previously uploaded image.

You can also use this route on a modified image by providing the sid from the response of the previously used route.

This route returns both the URL and the sid associated with the updated image.

Before making any modifications, please call the /info or background/info route to obtain information on the available modifications, and their oracle values.

Request
path Parameters
visual_id
required
string

visual id of the image from which the user wishes to remove the background

Example: 8487fb411f3c6716
query Parameters
sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to modify the result of that route, please provide this information. This parameter is optional.

Example: sid=Remove this parameter if the image has not been modified using Bria.
desired_resolution
string

The desired resolution of the updated image. This parameter is optional.

Enum: "original" "nhd" "svga" "xga" "hd" "wuxga" "uwfhd" "wqxga" "uwqhd" "uhd"
Example: desired_resolution=original
original_quality
boolean

If you would like to retain the quality of the original image, please set this parameter to true. Enabling this parameter during background removal may cause longer response times, depending on the quality and size of the original image. This parameter is optional.

Example: original_quality=true
header Parameters
api_token
required
string
Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Blur Background

Description

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

You can also use this route on a modified image by providing the sid from the response of the previously used route.

This route returns both the URL and the sid associated with the updated image.

Before making any modifications, please call the /info or background/info route to obtain information on the available modifications, and their oracle values.

Request
path Parameters
visual_id
required
string

visual id of the image for which the background should be blurred.

Example: 8487fb411f3c6716
query Parameters
scale
integer [ 1 .. 5 ]
Default: 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.

Example: scale=4
sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to modify the result of that route, please provide this information. This parameter is optional.

Example: sid=Remove this parameter if the image has not been modified using Bria.
desired_resolution
string

The desired resolution of the updated image. This parameter is optional.

Enum: "original" "nhd" "svga" "xga" "hd" "wuxga" "uwfhd" "wqxga" "uwqhd" "uhd"
Example: desired_resolution=original
header Parameters
api_token
required
string
Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

Generate Background - Isolated

Description

The Replace BG Route is used to replace the background of any image with a generated background using the state-of-the-art BRIA 2.3 ControlNet BG-Gen model (available on Hugging Face). We offer a fast version of this feature, powered by Bria 2.3 Fast LoRA (model card on Hugging Face), which provides an optimal balance between speed and quality. This endpoint also supports solid colors - you can take a color code and use it in the prompt.
Here are some examples:

original image:

bg_prompt: in a parking lot

num_results: 3

results:

Request
header Parameters
api_token
required
string

API token associated with the organization.

Request Body schema: application/json
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. It is recommended to use sync=false for optimal performance. When generating more than 1 result, you should use the value false.

fast
boolean
Default: false

Determines the generation mode. When true, the generation will utilize the fast mode which provides the best balance between speed and quality. When false, the regular mode will be utilized.

image_url
string

The URL of the image to which a new background should be generated. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

file
string

The product of the image to which a new background should be generated, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

bg_prompt
string

Text description of the new scene or background for the provided image. Bria currently supports prompts in English only.

refine_prompt
boolean
Default: false

It is recommended to set this parameter to 'true'. When true, an additional logic takes the bg_prompt that was included and adjusts it to achieve optimal results. Built with Meta Llama 3.

num_results
integer
Default: 1

The number of backgrounds you would like to generate for the image. If placement_type!=original, then for each selected placement you will get results in the amount specified in this parameter.

negative_prompt
string

Elements or features that should be excluded from the generated scene. This parameter is optional. Bria currently supports descriptions in English only.

seed
integer

You can choose whether you want your generated results 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.

Responses
200

Successful operation.

400

Bad request. Missing or invalid parameters.

401

Unauthorized. Invalid API key or authentication token.

404

Not found. Image could not be found at the provided URL.

413

Payload too large. Image file size exceeds the 12MB limit.

415

Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.

451

Unavailable for legal reasons.

460

Failed to download image.

500

Internal server error. An error occurred on the server.

post/background/replace
Request samples
Response samples
application/json
{
  • "result": [
    ]
}

Generate Background

Description

The Replace BG Route is used to replace the background of a previously uploaded image with a generated background using the state-of-the-art BRIA 2.3 ControlNet BG-Gen model (available on Hugging Face). We offer a fast version of this feature, powered by Bria 2.3 Fast LoRA (model card on Hugging Face), which provides an optimal balance between speed and quality. This endpoint also supports solid colors - you can take a color code and use it in the prompt. Before making any modifications, please call the /info or background/info route to obtain information on the available modifications, and their oracle values.

Here are some examples:

original image:

bg_prompt: in a parking lot

num_results: 3

results:

You can use this route on a modified image by providing the sid from the response of the previously used route.

This route returns both the URL and the sid associated with the updated image.

Request
path Parameters
visual_id
required
string

The visual id of the image for which the user wishes to replace the background

Example: fa8f8572986ccb03
header Parameters
api_token
required
string
Request Body schema: application/json
sync
boolean
Default: false

Determines the response mode. When true, responses are synchronous. With false, responses are asynchronous, immediately providing URLs for images that are generated in the background. It is recommended to use sync=false for optimal performance. When generating more than 1 result, you should use the value false.

fast
boolean
Default: false

Determines the generation mode. When true, the generation will utilize the fast mode which provides the best balance between speed and quality. When false, the regular mode will be utilized.

sid
string

This session id was obtained from the response of a route that had been applied to this visual id. If you have used another route on the provided visual before, and you would like the current route to modify the result of that route, please provide this information. This parameter is optional.

desired_resolution
string

The desired resolution of the updated image. This parameter is optional.

Enum: "original" "nhd" "svga" "xga" "had" "wuxga" "uwfhd" "wqxga" "uwqhd" "uhd"
bg_prompt
string

Text based on which you wish to generate the new background. Bria currently supports prompts in English only.

refine_prompt
boolean
Default: false

It is recommended to set this parameter to 'true'. When true, an additional logic takes the bg_prompt that was included and adjusts it to achieve optimal results. Built with Meta Llama 3.

num_results
integer
Default: 4

The number of backgrounds you would like to generate for the image. If placement_type!=original, then for each selected placement you will get results in the amount specified in this parameter.

seed
integer

You can choose whether you want your generated results 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_prompt
string

This parameter is optional. Bria currently supports prompts in English only.

Responses
200

Successful operation.

400

Bad request.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

512

Insufficient resources to process the request.

post/{visual_id}/replace_bg
Request samples
Response samples
application/json
{
  • "result": [
    ]
}

Object

Get Objects info

Description

The Objects/Info Route is used to retrieve useful information on the objects in a specific visual that was previously uploaded to the database.

Additionally, it provides the following:

  1. The available object actions, which are supported by the Bria API.

  2. The Oracle value for each available action. The orcale value predicts the quality of the result, for each possible action. The possible oracle values for object actions are true and false.

This route should be used instead of the main /info route when you are only interested in information and available actions for the objects in the image. With this route, you will save runtime by only obtaining information that is relevant to your needs.

Request
path Parameters
visual_id
required
string

visual id of the image, received after using the /upload or register route.

Example: 92bf8ce17584de82
header Parameters
api_token
required
string
Responses
200

Successful operation.

205

File hasn’t finished onboarding. Please call /info again until you get 200.

400

One of the details does not meet specification. Please call objects/info again.

404

Specified Image does not exist.

405

Method not allowed.

500

Internal server error.

506

Insufficient data. The given input is not supported by the Bria API.

get/{visual_id}/objects/info
Request samples