The Bria API (2)

Introduction

The Bria API was designed for users to interact with the BriEngine, creating new images and videos with specific requests. This document will outline the capabilities of the API and explain to users how to implement it.

The common use of the Bria API is according to the following order:

/upload - (Coming Soon) Using the Upload Route to upload a new image to the database
/info - Using the Info Route to understand the change possibilities for each object in the image

With the response from the Upload Route, the following routes can be used without any particular order:

/remove_bg - (Coming Soon) Using the Remove BG Route to remove the background of a stil image.
/video - (Coming Soon) Using the Video Route to make a short video based on a single still image.

With the response from the Info Route, the following route 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.

The following route can be used at any moment:

/generate - (Coming Soon) Using the Generate Route to generate a completely new visual without the need to upload a seed image

Versioning

The current version of the web API is known as V2 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.

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 'http://bria-api.com:5000/v2' \
--header: 'api_token: <...>' \
--header: 'api_secret: <...>' \
...

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

Demonstration of usage

For a full example of the Bria API usage, using python code, please check this link.

upload (Coming Soon)

Uploading file

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 and make changes to it

{ "visual_id": "9ea9a4d2d19977a7c" }

The visual_id in the response of the /upload route can be used for all other routes.

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 files. The status code 415 will be returned if the file is of a different type.

Request

Request Body schema: multipart/form-data

Upload new image

file	string <binary>

Responses

200

Successful operation.

206

File value was not provided.

208

File already uploaded.

400

Request doesn't contain file part.

405

Method not allowed.

413

Request entity too large.

415

Unsupported media type.

500

Internal server error.

506

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

post/upload

Request samples

curl
Node.js
JavaScript
Python

curl -i -X POST \
  http://bria-api.com:5000/v2/upload \
  -H 'Content-Type: multipart/form-data' \
  -F file=string

Response samples

application/json

{"visual_id": "string"
}

info

Getting image info

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.

Request

path Parameters

visual_id

required

string

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

Example: 8487fb411f3c6716

Responses

200

Successful operation.

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

curl
Node.js
JavaScript
Python

curl -i -X GET \
  'http://bria-api.com:5000/v2/{visual_id}/info'

Response samples

application/json

{"description": "Coming Soon",
"scene": [{"id": "a48284e4832c809e4475ad5de7bdd333658e363b417a28991022a6fa79488a6b",
"type": "person",
"labels": ["age_22-34",
"calm",
"Male"
],
"actions": {"age": ["mid-20",
"mid-40",
"mid-60"
],
"diversity": ["africa",
"korea",
"india",
"japan",
"sweden",
"germany",
"russia",
"mexico",
"brazil"
],
"expression": ["happy",
"calm",
"surprised",
"dreaming",
"angry"
],
"glasses": ["light",
"heavy",
"none"
],
"haircolor": ["black",
"brown",
"red",
"blond",
"gray"
],
"gender": ["femininity",
"masculinity"
],
"makeup": ["light",
"heavy",
"none"
],
"hair_line": ["high",
"low"
],
"beard": ["shaved",
"medium",
"full"
]
}
}
]
}

create

Create new image based on changes requested by user

Description

The Create Route is used to create a new visual, based on the changes requested by the user for a previously uploaded visual.

The Create Route will return the url for accessing the new generated visual and the confidence that Bria has in the quality of the new visual.

Request

path Parameters

visual_id

required

string

visual id of the image the user wants to create a new visual from.

Example: 8487fb411f3c6716

Request Body schema: application/json

Array of objects

The requested changes to the original visual.

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.

post/{visual_id}/create

Request samples

curl
Node.js
JavaScript
Python

curl -i -X POST \
  'http://bria-api.com:5000/v2/{visual_id}/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [
      {
        "id": "a48284e4832c809e4475ad5de7bdd333658e363b417a28991022a6fa79488a6b",
        "actions": {
          "age": "mid-60",
          "diversity": "france",
          "expression": "happy",
          "glasses": "light",
          "haircolor": "brown",
          "gender": "masculinity",
          "makeup": "none",
          "hair_line": "high",
          "beard": "medium"
        }
      }
    ]
  }'

Response samples

application/json

{"image_res": "https://d1uzvjowrxhw13.cloudfront.net/api/create_results/8487fb411f3c6716_05e8a8dc-b723-11ec-be15-c28fc8b4a55b.JPEG?AWSAccessKeyId=ASIAUL5JH7ABM5GPF244&Signature=OaE%2BTJW%2FBJFDB2xGXpy%2F%2F8TYkAE%3D&x-amz-security-token=FwoGZXIvYXdzEEsaDHAX5TxTwymFAQYSwSKYBK3lKAwEipl9tjg1QQwWMdQDqS%2B0rYkexasgxxW78Vz4DvJUVPISpnTOZk4h%2Fy6%2BikLC5%2FYGY86SL8980ZHZzRgqcodDJ0n6ljB7SgbkfJnSpgx%2F8iCHzoDH%2BS7YrUjnR7e%2FUz%2B4sIbV%2BSHGn36EXTNnrm%2FOgCsiL9vqLSGFEo5R1pLYIbezxWCEWMLcDO5x9WsVoPRYW7c%2B5B%2B1Ku3qybQEBFRex4BVisJU4NTXbwQKFWMbkTjHg5vK%2FEdQn7OzmCA7SfCSHe%2FqDZIBQG0ki%2BHt%2Fs4bAYYTZpl%2FjoUJTldlltdWH2uitj%2BBeyQKcUnHrPjTY1CsAOEC6OV%2FKlZfOjbNJTvlmHc7%2BKP3iICKlCVJwvRK6%2FnmU7mUVOb%2FmgD2kIvBq5G6fNxXQlKfFGZE2lSs8HR83sp44Qz8hm60DPfK45hE0XdVnIS2jY%2F1a%2BYBmijCr4HDTgv52D53CdnOiQ%2BQ8Yld0bBZRC4aDBATcvcsDcnO4BBMY0NS1c%2BSJ6b4IMxDK2OKdanf9EYiDgzr3ebsS1m7j4NX3pEvNC99YF%2B5PQwDYhbMwlMCAG9AMs9%2FF86Al3czOJFOxV1ClBEoUKy2TgntGraCp76UoLmRrHuRq7WKQUvIj2HAXsIlyNkBg3z498M1Gh7vyD%2F7xQgA0Ny6zYeC1gBH4HmYtFlBS%2BJimmxFlCoCuyFhBmUXp7p6oBI3APuSyQYLKLmQwJIGMioiS3mUno68q7GAsD%2FPmSCM8xMeEWF8IegvlU4XWAQuNnQJLVtqwkZb1Qo%3D&Expires=1650276159",
"confidence": "low"
}

remove_bg (Coming Soon)

Remove the background of an image

Description

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

This route can also be used on an image that has been changed by the user using the /create route.

The Remove BG Route will return the URL for accessing the updated image.

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

visual_url

string

URL of the new image the user has created from the original image, using the /create route

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.

post/{visual_id}/remove_bg

Request samples

curl
Node.js
JavaScript
Python

curl -i -X POST \
  'http://bria-api.com:5000/v2/{visual_id}/remove_bg?visual_url=string'

Response samples

application/json

{"image_res": "https://bria-temp.s3.amazonaws.com/engine_no_bg/727b73c6-b723-11ec-947a-c28fc8b4a55b.png?AWSAccessKeyId=ASIAUL5JH7ABNOAGDDHM&Signature=IIZp7MtiAoY32wIq%2BAVoUd7U3XY%3D&x-amz-security-token=FwoGZXIvYXdzEEwaDJNBqgbCH8ZLEjbtwCKYBByHo1V0nSnkoDy3kvaujvGHcNdmw0pYIwWYuvYdnKYv5zmzE4k%2FcgcB8YfY8DXKBOZR9DB%2FpzwoMPYf%2FxDMy4NenzSXw4VymF3j97bTEy6M00j%2BVO3K5fJOpN7iWlrxTaFHQICUW7%2FHE4CvaQ%2FB%2BWoCakNiEESUQxGglIygfJpviyexXNsxNGpeq7BPSSrTdsuD6R27pKmdFgdkL3xzUgMQMKzSeTJL4hUVGVldOp5sI4Qlvwnb8L%2FW7ciHHjUCf8WuHtDjDSdBIAqNci6wtXL6SQwLG%2Fo3oryPr0tNOMsbnrIIoFP5ZnH3VQISPCITBkWuUu9bdXkBm2R7rJyfPPOusFLuom2GDyVEHJfA%2FUtwGELxtv7Co29Tujd2N%2BHRhcdyrNsngwYwU2AiLyopMglYIDNQpv9%2FIKnH9ikuki%2F%2FWQ2PnzepcttQuXzlsqlUJRg%2Fcqhqis%2BxwJXZL1vpPJb%2BJz22oMp%2FJqZw%2BOIBWdxiL0pRq%2FF6EmyQz8iuhVBkr%2BnN5eWWxOrizMLFoVRTP34NPOWvWLwZJlrHzryCY8wZ01u2OLu3jxMcBhwypIp4pCzwx%2BAo39AXU1iMHJq36S6Bl5uptEr1NONKQvvz%2BpndF5t1dnoK7lfD9XExjk16shJXIImqiN7kxP2RTIrKsvm8wJY6iPxE35%2Bn0Cw8BS1eRmXFIOdEcfzbJVq80SQRIMko4CePyoOiKPCRwJIGMipiGM2hMspLQDThPJdlIiCOIh670Q2pu95y27iI3i87WQB55KJ9JNTL39I%3D&Expires=1650276342"
}

video (Coming Soon)

Generate a video from a still image

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.

Request

path Parameters

visual_id

required

string

visual id of the image the user wants to create a new video from

query Parameters

visual_url

string

URL of the new image the user has created from the original image, using the /create route

Request Body schema: application/json

Array of objects

The requested change to the selected visual or object.

Responses

200

Successful operation.

400

Either pace or duration are required.

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}/video

Request samples

curl
Node.js
JavaScript
Python

curl -i -X POST \
  'http://bria-api.com:5000/v2/{visual_id}/video?visual_url=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [
      {
        "id": "string",
        "actions": {
          "zoom": {
            "type": "zoom_in",
            "focus_area": "center_middle",
            "video_depth": "shallow",
            "boomerang_loop": false,
            "pace": "medium",
            "duration": 5
          },
          "hover": {
            "start_area": "top_left",
            "end_area": "center_middle",
            "video_depth": "shallow",
            "boomerang_loop": false,
            "pace": "medium",
            "duration": 5
          },
          "smart_zoom": {
            "boomerang_loop": false,
            "pace": "medium",
            "duration": 5
          }
        }
      }
    ]
  }'

Response samples

application/json

{"video_response": "string",
"confidence": "string"
}