The Bria API is intended for users to interact with BriEngine and perform various operations, such as generating new images, customizing uploaded images, and searching. This document will provide an overview of the API's capabilities and guide users on how to effectively implement it.
The common use of the Bria API is according to the following order:
With the response from the Upload/Register Routes (visual_id), the following routes can be used without any particular order:
With the response from the Info Routes, the following routes can be used without any particular order:
The current version of the web API is known as V1 and is considered to be in a draft phase. While we don’t expect public endpoints to materially change, please bear in mind that the API is still under development.
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: <...>' \
...
You can register and access the API Token through Bria's platform by clicking here.
Description
The Upload Route is used to upload visuals to the database. This route returns a visual identification to the user. It's the first step for consuming the Bria API for new visuals.
Response
The visual id in the response of the Upload 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 uploaded 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/tools/{visual_id}
, where the {visual_id} comes from the response of the /upload route.
In Bria's web tool, the user has the ability to make many changes to the visual and also generate live videos, using an intuitive interactive platform.
Bria's web tool can also be embedded in other websites, with the use of an iframe HTML element:
Constraints
Files should not be larger than 12MB. The status code 413 will be returned if the file exceeds its maximum size.
Bria API currently only supports JPEG and PNG files. The status code 415 will be returned if the file is of a different type.
Successful operation.
File value was not provided.
File already uploaded.
Request doesn't contain file part.
Method not allowed.
Request entity too large.
Unsupported media type.
Failed to download image.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "visual_id": "string"
}
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.
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/tools/{visual_id}
, where the {visual_id} comes from the response of the /register route.
In Bria's web tool, the user has the ability to make many changes to the visual and also generate live videos, using an intuitive interactive platform.
Bria's web tool can also be embedded in other websites, with the use of an iframe HTML element:
Constraints
Bria API currently only supports JPEG and PNG files, which are not larger than 12MB.
Successful operation.
Image already registered.
Bad request.
Method not allowed.
Failed to download image.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "visual_id": "string"
}
Description
The Info Route is used to retrieve useful information on a specific visual that was previously uploaded to the database.
Additionally, it provides a description of each object and element within the scene along with its available changes, which are supported by the Bria API.
Successful operation.
File hasn’t finished onboarding. Please call /info again until you get 200.
One of the details does not meet specification. Please call /info again.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "description": "Coming Soon",
- "scene": [
- {
- "actions": {
- "age": [
- "mid-20",
- "mid-40",
- "mid-60"
], - "Beard": [
- "shaved",
- "medium",
- "full"
], - "diversity": [
- "africa",
- "korea",
- "india",
- "japan",
- "sweden",
- "germany",
- "russia",
- "mexico",
- "brazil",
- "england",
- "spain",
- "france"
], - "expression": [
- "happy",
- "surprised",
- "dreaming",
- "angry",
- "fear",
- "contempt",
- "disgusted",
- "sad"
], - "gender": [
- "femininity",
- "masculinity"
], - "glasses": [
- "light",
- "none",
- "heavy"
], - "hair_line": [
- "high",
- "low"
], - "haircolor": [
- "black",
- "brown",
- "red",
- "blond",
- "gray"
], - "makeup": [
- "light",
- "heavy",
- "none"
]
}, - "id": "a48284e4832c809e4475ad5de7bdd333658e363b417a28991022a6fa79488a6b",
- "labels": [
- "age_23-35",
- "calm"
], - "oracle": {
- "age": {
- "age": "high"
}, - "Beard": {
- "Beard": "high"
}, - "diversity": {
- "africa": "high",
- "brazil": "high",
- "england": "high",
- "france": "high",
- "germany": "high",
- "india": "high",
- "japan": "high",
- "korea": "high",
- "mexico": "high",
- "russia": "high",
- "spain": "high",
- "sweden": "high"
}, - "expression": {
- "angry": "high",
- "contempt": "high",
- "disgusted": "high",
- "dreaming": "high",
- "fear": "high",
- "happy": "high",
- "surprised": "high"
}, - "gender": {
- "gender": "high"
}, - "glasses": {
- "glasses": "high"
}, - "hair_line": {
- "hair_line": "high"
}, - "haircolor": {
- "haircolor": "high"
}
}, - "type": "person"
}, - {
- "id": "0a349cbe603a786570d4eec7dd9cf64e568ef72767a5847251b32988a2b99dff",
- "type": "chair",
- "labels": [
- "object"
], - "rect": {
- "x": 647.4609375,
- "y": 3910.6640625,
- "w": 1139.53125,
- "h": 2071.875
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0.4
}, - {
- "actions": {
- "remove": [
- true
]
}, - "id": "26bf1a1e6b7c5a802b804a52be420a14e44c7d4a393d695afb9d58c9f869cac3",
- "labels": null,
- "oracle": {
- "remove": true
}, - "type": "background"
}
]
}
Description
The Person/Info Route is used to retrieve useful information on the people in a specific visual that was previously uploaded to the database.
Additionally, it provides a description of each person within the scene along with its available changes, which are supported by the Bria API. This route should be used instead of the main /info route when you are only interested in information and available actions for the people in the image. With this route, you will save time by only obtaining information that is relevant to your needs.
Successful operation.
File hasn’t finished onboarding. Please call /info again until you get 200.
One of the details does not meet specification. Please call person/info again.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
[- {
- "actions": {
- "age": [
- "mid-20",
- "mid-40",
- "mid-60"
], - "Beard": [
- "shaved",
- "medium",
- "full"
], - "diversity": [
- "original",
- "africa",
- "korea",
- "india",
- "japan",
- "sweden",
- "germany",
- "russia",
- "mexico",
- "brazil",
- "england",
- "spain",
- "france",
- "unsplash"
], - "expression": [
- "happy",
- "surprised",
- "dreaming",
- "angry",
- "fear",
- "contempt",
- "disgusted",
- "sad",
- "smile"
], - "gender": [
- "femininity",
- "masculinity"
], - "glasses": [
- "light",
- "none",
- "heavy"
], - "hair_line": [
- "high",
- "low"
], - "haircolor": [
- "black",
- "brown",
- "red",
- "blond",
- "gray"
], - "makeup": [
- "light",
- "heavy",
- "none"
]
}, - "id:"c6bbe1cd719300c11e5c581889e9383245a0c1d923f210a3445e8ea5a25500e0"": null,
- "labels": [
- "age_14-26",
- "glasses",
- "Female"
], - "oracle": {
- "age": {
- "age": "low"
}, - "Beard": {
- "Beard": "low"
}, - "diversity": {
- "africa": "low",
- "brazil": "low",
- "england": "low",
- "france": "low",
- "germany": "low",
- "india": "low",
- "japan": "low",
- "korea": "low",
- "mexico": "low",
- "russia": "low",
- "spain": "low",
- "sweden": "low"
}, - "expression": {
- "angry": "high",
- "calm": "high",
- "contempt": "high",
- "disgusted": "high",
- "dreaming": "high",
- "fear": "high",
- "happy": "high",
- "surprised": "high"
}, - "gender": {
- "gender": "low"
}, - "glasses": {
- "glasses": "low"
}, - "hair_line": {
- "hair_line": "low"
}, - "haircolor": {
- "haircolor": "low"
}
}, - "rect": {
- "h": 375.98625326156616,
- "w": 280.4049072265625,
- "x": 1134.1341552734375,
- "y": 290.6307406425476
}, - "type:"person"": null
}, - {
- "actions": {
- "age": [
- "mid-20",
- "mid-40",
- "mid-60"
], - "Beard": [
- "shaved",
- "medium",
- "full"
], - "diversity": [
- "original",
- "africa",
- "korea",
- "india",
- "japan",
- "sweden",
- "germany",
- "russia",
- "mexico",
- "brazil",
- "england",
- "spain",
- "france",
- "unsplash"
], - "expression": [
- "happy",
- "surprised",
- "dreaming",
- "angry",
- "fear",
- "contempt",
- "disgusted",
- "sad",
- "smile"
], - "gender": [
- "femininity",
- "masculinity"
], - "glasses": [
- "light",
- "none",
- "heavy"
], - "hair_line": [
- "high",
- "low"
], - "haircolor": [
- "black",
- "brown",
- "red",
- "blond",
- "gray"
], - "makeup": [
- "light",
- "heavy",
- "none"
]
}, - "id:"d74da71f722b45de5f18f93e9dd7fc64a50a5a5dda001985ab9c2374807182b8"": null,
- "labels": [
- "age_26-42",
- "happy",
- "Female"
], - "oracle": {
- "age": {
- "age": "high"
}, - "Beard": {
- "Beard": "high"
}, - "diversity": {
- "africa": "high",
- "brazil": "high",
- "england": "high",
- "france": "high",
- "germany": "high",
- "india": "high",
- "japan": "high",
- "korea": "high",
- "mexico": "high",
- "russia": "high",
- "spain": "high",
- "sweden": "high"
}, - "expression": {
- "angry": "high",
- "calm": "high",
- "contempt": "high",
- "disgusted": "high",
- "dreaming": "high",
- "fear": "high",
- "happy": "high",
- "surprised": "high"
}, - "gender": {
- "gender": "high"
}, - "glasses": {
- "glasses": "high"
}, - "hair_line": {
- "hair_line": "high"
}, - "haircolor": {
- "haircolor": "high"
}
}, - "rect": {
- "h": 354.8530983924866,
- "w": 282.885498046875,
- "x": 555.80419921875,
- "y": 486.4655692577362
}, - "type:"person"": null
}
]
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 a description of each object within the scene along with its available changes, which are supported by the Bria API. 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 time by only obtaining information that is relevant to your needs.
Successful operation.
File hasn’t finished onboarding. Please call /info again until you get 200.
One of the details does not meet specification. Please call person/info again.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
[- {
- "id": "d34ef7cf0b4e1ea2e414cdff7ae9ded80162f1f93bb94df709fe29d9df3dbfb5",
- "type": "dining table",
- "labels": [
- "object"
], - "rect": {
- "x": 1294.921875,
- "y": 4143.75,
- "w": 2253.1640625,
- "h": 2071.875
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0.4
}, - {
- "id": "d1b004a7b3b065aa8b98b321b67806cb3e6ca09e596ad6d3f31c625e46e168e2",
- "type": "potted plant",
- "labels": [
- "object"
], - "rect": {
- "x": 4558.125,
- "y": 2667.5390625,
- "w": 517.96875,
- "h": 725.15625
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0.67
}, - {
- "id": "f173a0ad62749dbeb97f8055f51d3d125d4c9c968ee3ae46754e911f3fd12000",
- "type": "vase",
- "labels": [
- "object"
], - "rect": {
- "x": 3366.796875,
- "y": 2123.671875,
- "w": 595.6640625,
- "h": 284.8828125
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0.89
}, - {
- "id": "7a3bd30a268840cc3645abf7b512c3b9b8bc2d55d98aa5f7ef8c1e72348a016c",
- "type": "potted plant",
- "labels": [
- "object"
], - "rect": {
- "x": 3263.203125,
- "y": 1398.515625,
- "w": 854.6484375,
- "h": 751.0546875
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 1
}, - {
- "id": "0289aaf067a6d7d812738a8d42d17e54ffd2fa79e0decbca46a873018a6d791a",
- "type": "chair",
- "labels": [
- "object"
], - "rect": {
- "x": 2900.625,
- "y": 3858.8671875,
- "w": 1502.109375,
- "h": 2486.25
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0
}, - {
- "id": "0a349cbe603a786570d4eec7dd9cf64e568ef72767a5847251b32988a2b99dff",
- "type": "chair",
- "labels": [
- "object"
], - "rect": {
- "x": 647.4609375,
- "y": 3910.6640625,
- "w": 1139.53125,
- "h": 2071.875
}, - "actions": {
- "remove": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true
}, - "bg_overlap": 0.4
}
]
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 available changes for the background, which are supported by the Bria API. 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 time by only obtaining information that is relevant to your needs.
Successful operation.
File hasn’t finished onboarding. Please call /info again until you get 200.
One of the details does not meet specification. Please call person/info again.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "id": "67a9746d4c7939e2753869cdb4330852b6e2472b8110ae1fb59f8c033fc7fe1f",
- "type": "background",
- "labels": null,
- "rect": null,
- "actions": {
- "remove": [
- true
], - "blur": [
- true
], - "replace": [
- true
]
}, - "oracle": {
- "remove": true,
- "blur": true,
- "replace": true
}
}
Description
The Caption Route is used to get a caption that describes the given image.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "results": [
- {
- "caption": "woman walking on a bridge in the jungle"
}
]
}
Description
The Image Generation Route allows you to generate images based on any given text prompt.
2048 x 2048 pixels will be the size of the generated images.
Here are some examples:
prompt: alien world
style: photo realistic
atmosphere: dramatic
camera: portrait
medium: photography
results:
prompt: owl wearing a hat
style: fashion
atmosphere: vivid
camera: close up
medium: art
results:
Successful operation.
Bad request.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Insufficient resources to process the request.
Description
The Create Route is used to create a new visual, based on the changes requested by the user for a previously uploaded visual.
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.
Array of objects The requested changes to the original visual. |
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Description
The Recast Model Route is used to create customized and eye-catching images of people that match various themes or professions by modifying their outfit, body structure, hair, and background.
This provides an easy and quick way to generate high-quality visuals for businesses, creative projects, or personal use without the need for extensive photography or design work.
The feature is also fun and engaging for social media or entertainment purposes, allowing users to create custom avatars or profile pictures that reflect their personality.
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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "message": "Finished sucessfully",
- "sid": "aaeec35e-9904-21ed-a479-964fdf514767.JPEG",
- "status": "SUCCESS"
}
Description The Remove Object Route is used to remove objects, using the object id returned in the /info or objects/info request. You can send in one request multiple objects for removal. 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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Description
The Blur BG 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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Description
The Replace BG Route is used to replace the background of a previously uploaded image, with a generated background.
Additionally, you can change the image size of the final result as well as the positioning of the product or foreground of the image.
This will enable you to create new and unique variations of your original image.
Here are some examples:
original image:
bg_prompt: environment living room interior kitchen counter
placement_type: original
num_results:
results:
bg_prompt: environment living room interior kitchen counter
placement_type: automatic
num_results: 1
canvas_size: [1200,1000]
results:
bg_prompt: environment living room interior kitchen counter
placement_type: manual_padding
num_results: 3
padding_values: [100,100,200,200]
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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Insufficient resources to process the request.
{- "result": [
- [
- 1,
- "26b54-9812-11ed-884d-56304cc7efc8.JPEG"
], - [
- 2,
- "26bab854-9812-11ed-884d-56304cc7efc8.JPEG"
], - [
- 3,
- "26bab854-9812-11ed-884d-563c8.JPEG"
], - [
- 4,
- "26bab854-9812-884d-56304cc7efc8.JPEG"
]
]
}
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.
PNG files with transparency are not supported by this feature at the moment.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
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.
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.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
Description
By using the Search Route, you can utilize Bria's generative search capabilities, which don't require labels or keywords.
The user can send any text query and receive relevant images that match the query.
The Search Route returns the images, sorted by the match score, from highest match to lowest match. The images are returned in batches, and you can specify how many images to receive in one batch, and which batch to receive in each call.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "results": [
- {
- "visual_id": "a169a6862f24de75",
- "org_image_key": "None",
- "source_url": "None"
}
]
}
Description
By using the Search Similar Images Route, you can send an image as a query and receive relevant images that are similar.
The Search Similar Images Route returns the images, sorted by the similarity score, from the highest to the lowest.
The images are returned in batches, and you can specify how many images to receive in one batch, and which batch to receive in each call.
Successful operation.
Bad request.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "results": [
- {
- "visual_id": "a169a6862f24de75",
- "org_image_key": "None",
- "source_url": "None"
}
]
}
Description
The Video Route is used to create a new video, based on a previously uploaded single still image.
This route can also be used on an image that has been changed by the user using the /create route.
The Video Route will return the URL for accessing the new generated video and the confidence that Bria has in the quality of this video.
Successful operation.
Either pace
or duration
are required.
Specified Image does not exist.
Method not allowed.
Internal server error.
Insufficient data. The given input is not supported by the Bria API.
{- "video_response": "string",
- "confidence": "string"
}