openapi: 3.2.0
info:
title: Bria Endpoints API
version: ''
description: 'Operations tagged Endpoints across 5 of this provider''s published API definitions: bria-ad-generation-openapi-original.yml, bria-ai-search-deperecated-openapi-original.yml, bria-image-generation-openapi-original.yml, bria-image-onboarding-openapi-original.yml, bria-status-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://engine.prod.bria-api.com/v1
- url: https://engine.prod.bria-api.com/v2
tags:
- name: Endpoints
paths:
/ads/generate:
servers:
- url: https://engine.prod.bria-api.com/v1
post:
summary: Generate Ads
tags:
- Endpoints
description: "Bria's Ads Generation API enables builders to create multiple ads (scenes) in various sizes and resolutions, all unified by the same branding, style, and messaging. You can start exploring immediately with our public templates and brands.\nFor creating your own private templates and brands, please [Contact Us](https://bria.ai/contact-us).\n**Getting Started with Public Assets**\nYou can start exploring the API immediately using our public templates and brands, with no setup required.\n* **Public Template IDs**: \n * **`1062`**: A template that requires a brand ID.\n * **`1061`**: A brand-independent template (does not require a brand ID).\n* **Public Brand IDs**: **`167`**, **`166`**, **`122`**, **`121`**, **`120`**. These can be used for testing with compatible templates like **`1062`**. * **Important**: Public templates and brands can only be used with each other and cannot be mixed with private assets.\n\n \n<img src=\"https://bria-datasets.s3.us-east-1.amazonaws.com/temp_exp_or/Campaign.jpg\" width=\"400\"/>\n\n**Template** \nTemplates enable to repurpose and reuse well-design ads that share the same style, content and branded elements.It consists of multiple ads (“scenes”) and includes configurations for customizing the content at scale.\n\n**Smart Image Feature** \nA standout feature of BRIA's Ads Generation API is its ability to seamlessly embed objects, products, and presenter images into another image (a \"smart image\"). This AI-powered capability allows for generating diverse backgrounds for the embedded image or extending the background to fit the ad's design perfectly.\n\n**How It Works** \nThe Ads Generation API works by sending a template ID along with inputs such as text, images, the main object with its background definition, and a brand ID (including logos, colors, and fonts). In response, the API generates a set of ad images.\n\nIn thie endpoint, responses are asynchronous, immediately providing URLs for ads that are generated in the background. Use polling for the URLs to retrieve ads once ready.\n\nTemplates can be easily created using BRIA’s Ads Editor. Once a template is ready, it can be used to produce multiple ad versions with varying messaging, branding, and images.\n\nThis API endpoint supports content moderation via an optional parameter that can prevent generation if input images contain inappropriate content, and filters out unsafe generated images - the first blocked input image will fail the entire request.\n"
operationId: generate-ads
parameters:
- in: header
name: api_token
schema:
type: string
required: true
description: API token associated with the organization.
requestBody:
content:
application/json:
schema:
type: object
properties:
content_moderation:
type: boolean
default: false
description: 'When enabled, applies content moderation to both input visuals and generated outputs.
For input images:
- Processing stops at the first image that fails moderation
- Returns a 422 error with details about which parameter failed
For generated ads:
- Failed ads are replaced with zero-byte files at their placeholder URLs
- Successful ads are stored at their original placeholder URLs
'
template_id:
type: string
description: The ID of the template to be used for generating the ads scenes.
brand_id:
type: string
description: The ID of the brand to be used across all generated ads. A required field, unless the template is non brand related template and in that case even if brand if is provided, it isn't used.
smart_image:
type: object
description: 'Smart image object for generating an image based on the embedded image, including the main object and its background definition (`expand` or `generate_by_text`).
'
properties:
input_image_url:
type: string
description: URL of the input image that will be embedded within the smart image.
scene:
type: object
properties:
operation:
type: string
enum:
- expand_image
- lifestyle_shot_by_text
input:
type: string
description: Background prompt or hex color for the image’s background. If the operation chosen is "expand" this parameter is ignored.
required:
- main_object_url
elements:
type: array
description: List of text/images objects
items:
type: object
properties:
layer_type:
type: string
description: The element type, either "text" or "image".
enum:
- text
- image
content_type:
type: string
description: 'The heading level configuration for the text. This allows the same text to be inserted into multiple elements across scenes.
Value should be in the format - Heading *, Body *, Image * when * can be replaced with any value between #1-#5 (for example Heading #1, Image #1 and etc.)
'
content:
type: string
description: 'Content of the text or image, if `content_type` is set to `text` it should be a string, and if `content_type` is `image` it should be an image URL.
To ignore this element, set this parameter to an empty string.
'
id:
type: string
description: Unique identifier for the element.
example:
template_id: '123'
smart_image:
input_image_url: https://example.com/image.jpg
scene:
operation: lifestyle_shot_by_text
input: A scenic background
brand_id: '456'
elements:
- layer_type: text
content_type: 'Heading #1'
content: Sale Now!
responses:
'200':
description: Successfull operation.
content:
application/json:
schema:
type: object
properties:
result:
type: array
description: A list of objects, where each object contains an image URL corresponding to a scene in the template, the scene's name, and its resolution.
items:
type: object
properties:
id:
type: string
description: The unique ID for the generated scene.
name:
type: string
description: The name of the scene from the template used to generate the image.
example: scene_name
url:
type: string
description: The URL to download the generated scene result as a .png image.
example: IMAGE_URL
resolution:
type: object
description: An object containing the width and height of the generated image. Can be an empty object if resolution is not available.
properties:
width:
type: integer
height:
type: integer
example:
width: 1920
height: 1080
editor_iframe:
type: string
description: "A URL to open the generated ad within the Ads Editor. This URL is designed to be embedded in an iframe (white-labeled, no Bria branding) and opens the editor focused on this specific ad scene. It maintains the context of the template and brand used. \n"
example: URL
'400':
description: Bad request.
'401':
description: Unauthorized. Invalid API key or authentication token.
'403':
description: Forbidden
content:
application/json:
schema:
type: string
examples:
quota_exceeded:
value: 'Quota exceeded: Free users can make up to 1000 requests in total. Please upgrade your plan to continue using the service.'
access_denied:
value: 'Access denied: Your subscription does not include access to this feature/product.'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: string
examples:
input_violation:
value: The request could not be completed because the visual in the '{parameter_name}' parameter did not pass content moderation.
invalid_url:
value: Unprocessable Entity. The URL does not point to a valid image or is inaccessible.
'500':
description: Internal server error.
/ads/brands:
servers:
- url: https://engine.prod.bria-api.com/v1
get:
summary: Get Brands
tags:
- Endpoints
description: 'Retrieves the list of your private brands. For initial testing, you can use our public brand IDs directly in the `/ads/generate` endpoint. To create your own private brands that will appear in this list, please [Contact Us](https://bria.ai/contact-us).
'
operationId: get-brands
parameters:
- in: header
name: api_token
schema:
type: string
required: true
description: API token associated with the organization.
responses:
'200':
description: Successfully retrieved list of brands.
content:
application/json:
schema:
description: The list of brands, where each brand is an object containing the following properties - ID, name, description, and creation date.
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
created_at:
type: string
'401':
description: Unauthorized. Invalid API key or authentication token.
/ads/templates:
servers:
- url: https://engine.prod.bria-api.com/v1
get:
summary: Get Templates
tags:
- Endpoints
description: 'Retrieves the list of your private templates. To start experimenting right away, use our public template IDs (**1062**, **1061**) directly in the `/ads/generate` endpoint. To create your own private templates that will appear here, please [Contact Us](https://bria.ai/contact-us).
'
operationId: get-templates
parameters:
- in: header
name: api_token
schema:
type: string
required: true
description: API token associated with the organization.
responses:
'200':
description: Successfully retrieved list of templates.
content:
application/json:
schema:
type: array
description: The list of templates, where each template is an object containing the following properties - ID, name, description, creation date, number of scenes, and a preview.
items:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
created_at:
type: string
number_of_ads:
type: integer
preview:
type: string
'401':
description: Unauthorized. Invalid API key or authentication token.
/ads/templates/{template_id}:
servers:
- url: https://engine.prod.bria-api.com/v1
get:
summary: Get Template info by ID
tags:
- Endpoints
description: 'Retrieve details for a specific private template by its ID.
Please note: This endpoint is for inspecting your private templates only and cannot be used to retrieve details for public template IDs.
'
parameters:
- in: header
name: api_token
schema:
type: string
required: true
description: API token associated with the organization.
- in: path
name: template_id
schema:
type: string
required: true
description: The ID of the template.
responses:
'200':
description: Successfully retrieved template details.
content:
application/json:
schema:
type: object
description: 'An object containing scene definitions and their resolutions. Keys representing scenes (e.g., "scene_1") map to arrays of their elements. The specific key "scene_resolutions" maps to an object containing resolution details for each scene.
'
properties:
scene_resolutions:
type: object
description: A dictionary mapping scene keys (e.g., "scene_1") to their resolution dimensions.
additionalProperties:
type: object
properties:
width:
type: integer
height:
type: integer
additionalProperties:
type: array
description: Dynamic keys (e.g., "scene_1", "scene_2") containing the list of elements for that scene.
items:
type: object
properties:
id:
type: string
description: The unique identifier for the element.
layer_type:
type: string
description: The type of element.
enum:
- text
- image
- smartImage
- logo
- shape
content_type:
type:
- string
- 'null'
description: 'The configurable content type. Examples: "Heading #1", "Body #1", "Image #1", "smartImage", "Logo #1", "Basic Shape #1". Can be null.
'
content:
type: string
description: The default content of the element (text or an image URL).
scene_number:
type: integer
description: The scene number this element belongs to.
example:
scene_1:
- id: 6n_yngnjyHm9rbVRyE69z
layer_type: smartImage
content_type: smartImage
content: https://org-assets.bria.ai/...
scene_number: 1
- id: mSYZhrISh4EeYRFsvxJQG
layer_type: text
content_type: 'Heading #1'
content: Sale
scene_number: 1
scene_2:
- id: logo_ref_123
layer_type: logo
content_type: 'Logo #1'
content: https://org-assets.bria.ai/logo.png
scene_number: 2
- id: shape_ref_456
layer_type: shape
content_type: 'Basic Shape #1'
content: https://org-assets.bria.ai/shape.png
scene_number: 2
scene_resolutions:
scene_1:
width: 1920
height: 1080
scene_2:
width: 1080
height: 1080
'401':
description: Unauthorized. Invalid API key or authentication token.
'404':
description: Template not found for the provided template ID.
/caption:
servers:
- url: https://engine.prod.bria-api.com/v1
post:
summary: Get Caption
tags:
- Endpoints
description: '
**Description**
The *Caption Route* is used to get a caption that describes the given image.'
operationId: get-caption
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
image_url:
type: string
description: The URL of the input image. 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:
type: string
description: The file of the input image, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
caption:
type: string
example: woman walking on a bridge in the jungle
'400':
description: Bad request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid API key or authentication token.
'404':
description: Not found. Image could not be found at the provided URL.
'413':
description: Payload too large. Image file size exceeds the 12MB limit.
'415':
description: Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp.
'429':
description: Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later.
'460':
description: Failed to download image.
'500':
description: Internal server error. An error occurred on the server.
/search:
servers:
- url: https://engine.prod.bria-api.com/v1
get:
summary: Search by text
tags:
- Endpoints
description: '**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.
Search will only work on images that have been onboarded using the `register` endpoint.
**Note:** To use this endpoint, please [Contact Us](https://bria.ai/contact-us).'
operationId: search
parameters:
- in: header
name: api_token
schema:
type: string
required: true
- name: query
in: query
schema:
type: string
example: woman traveling in the world
description: the text query for which the user is looking for matching images.
- name: num_results_per_page
in: query
schema:
type: integer
example: 1
description: how many images you would like to receive from the gallery search. The default value is 50. The maximum value is 500. No need to use this parameter when gallery_search=false.
- name: page
in: query
schema:
type: integer
example: 1
description: which batch of images you would like to receive in the current call. Synthetic results will only be included in page no. 1. The default value is 1. For each query, we support 800 results, so if you set num_results_per_page=50, you will have 16 pages of results.
- name: gallery_id
in: query
schema:
type: string
example: '425'
description: Bria will provide you with this parameter which represents your account's image gallery. You must include this parameter.
- name: style
in: query
schema:
type: string
example: photo realistic
enum:
- stock photography
- photo realistic
- fashion
- retro
- sports
- still life
- hyper realistic
- travel
- artistic
- 3d render
- realistic
- fantasy
- comic book
- minimalistic
description: Which style you would like to see in your results, this parameter is optional.
- name: atmosphere
in: query
schema:
type: string
enum:
- dramatic
- vivid
- warm
- cool
example: dramatic
description: Which atmosphere you would like to get in your results, this parameter is optional.
- name: camera
in: query
schema:
type: string
enum:
- portrait
- close up
- aerial
- landscape
example: portrait
description: Which camera angle you would like to see in your results, this parameter is optional.
- name: medium
in: query
schema:
type: string
enum:
- photography
- art
example: photography
description: Which medium should be included in your results, this parameter is optional.
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: there are multiple objects in this array (based on the amount specified in num_results_per_page) and each object represents a single image. The images in the array are sorted by the similarity score, from the highest to the lowest. If the specified batch (=page) is empty, the results array will be empty.
items:
type: object
properties:
visual_id:
type: string
description: visual id of the image, documented in Bria.
example: a169a6862f24de75
org_image_key:
type: string
description: It will be returned if the image was registered using an org_image_key.
example: None
source_url:
type: string
description: It will be returned if the image was registered using a URL.
example: None
'400':
description: Bad request.
'404':
description: Specified Image does not exist.
'405':
description: Method not allowed.
'429':
description: Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later.
'500':
description: Internal server error.
'506':
description: Insufficient data. The given input is not supported by the Bria API.
/search_similar_images:
servers:
- url: https://engine.prod.bria-api.com/v1
get:
summary: Search by Image
tags:
- Endpoints
description: '**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.
Search will only work on images that have been onboarded using the `register` endpoint.
**Note:** To use this endpoint, please [Contact Us](https://bria.ai/contact-us).'
operationId: search-similar-images
parameters:
- in: header
name: api_token
schema:
type: string
required: true
- name: vhash
in: query
schema:
type: string
example: e01592ef1188df76
description: the visual id of the image for which the user is looking for similar images.
- name: num_results_per_page
in: query
schema:
type: integer
example: 1
description: how many images you would like to receive in the current call. The default value is 50. The maximum value is 500.
- name: page
in: query
schema:
type: integer
example: 1
description: which batch of images you would like to receive in the current call. The default value is 1. For each query, we support 800 results, so if you set num_results_per_page=50, you will have 16 pages of results.
- name: gallery_id
in: query
schema:
type: string
example: '425'
description: Bria will provide you with this parameter which represents your account's image gallery. You must include this parameter.
- name: url
in: query
schema:
type: string
example: If you are using the vhash paramater, there is no need to use this parameter
description: URL of an image, for which you would like to find similar images. When you want to search based on modified images, or images that have not been uploaded or registered to Bria, you can use this parameter. When this parameter is provided, the visual_id parameter can be None. The supported file types are jpg, jpeg and png, up to 12 mb.
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: there are multiple objects in this array (based on the amount specified in num_results_per_page) and each object represents a single image. The images in the array are sorted by the similarity score, from the highest to the lowest. If the specified batch (=page) is empty, the results array will be empty.
items:
type: object
properties:
visual_id:
type: string
description: visual id of the image, documented in Bria.
example: a169a6862f24de75
org_image_key:
type: string
description: It will be returned if the image was registered using an org_image_key.
example: None
source_url:
type: string
description: It will be returned if the image was registered using a URL.
example: None
'400':
description: Bad request.
'404':
description: Specified Image does not exist.
'405':
description: Method not allowed.
'429':
description: Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later.
'500':
description: Internal server error.
'506':
description: Insufficient data. The given input is not supported by the Bria API.
/image/generate:
servers:
- url: https://engine.prod.bria-api.com/v2
post:
summary: Generate Image
tags:
- Endpoints
servers:
- url: https://engine.prod.bria-api.com/v2
description: "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-generation/fibo-generate/sandbox)\n\n**Description**\n\nGenerates a new image based on your inputs.\n\nThis all-in-one endpoint first translates your input (`prompt` and/or `images`) into a structured JSON prompt using the state-of-the-art **Gemini 2.5 Flash** VLM bridge. It then *internally* uses that JSON to generate the final, deterministic image.\n\nUse this endpoint for professional workflows that demand the highest-fidelity interpretation of your creative vision. The response includes both the final `image_url` and the `structured_prompt` (JSON).\n\nFor advanced, programmatic control, you can also pass in your own `structured_prompt` (e.g., from a previous response or the `/v2/structured_prompt/generate` endpoint) to bypass the internal VLM bridge. This allows for precise, auditable refinement or recreation of an image, or to generate multiple variations from the same structured prompt.\n\n---\n\n**Input Combination Rules**\n\nThe request body must include **one** of the following mutually exclusive combinations:\n\n* `prompt` (Generates a new image from text)\n* `images` (Generates a new image inspired by a reference image)\n* `images` + `prompt` (Generates a new image inspired by an image and guided by text)\n* `structured_prompt` (Recreates a previous image exactly, combined with a seed)\n* `structured_prompt` + `prompt` (Refines a previous image using new text instructions, combined with a seed)\n\n---\n**API Access**\n\nYou can register and access the API Token through Bria's platform <a href=\"https://platform.bria.ai/console/account/api-keys\" target=\"_blank\">by clicking here</a>.\n\n---\n***Examples***\n\n**Use Case 1: Using a textual prompt**\n\n* **Input Prompt:** `photorealistic, high resolution rendering, balloon of lettering, \"HAPPY NEW YEAR
# --- truncated at 32 KB (148 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bria/refs/heads/main/openapi/bria-endpoints-api-openapi.yml