openapi: 3.2.0
info:
title: Product Shot API Reference Product Endpoints API
version: ''
description: "Below you will find the technical specifications, request schemas, and response models for our endpoints. \n \nChoose an endpoint from the sidebar to view code samples and run test requests. \n"
servers:
- url: https://engine.prod.bria-api.com/v1
tags:
- name: Product Endpoints
paths:
/product/cutout:
post:
summary: Product Cutout
tags:
- Product Endpoints
description: "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/product-shot-editing/product-cutout)\n\n**Description**\n\nThis capability allows you to create a precise cutout of a product from any given image. This feature is especially valuable for eCommerce platforms and applications, serving as a fundamental building block for crafting a user-friendly interface. \n\n\nThis API endpoint supports content moderation via an optional parameter that can prevent processing if input images contain inappropriate content or if the modified output would contain inappropriate content."
operationId: product-cutout
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:
sku:
type: string
description: The Stock Keeping Unit identifier for the product. This parameter is optional.
image_url:
type: string
description: The URL of the image containing the product to be cut out. If both image_url and file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.
file:
type: string
description: 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.
force_rmbg:
type: boolean
default: false
description: Forces background removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels.
preserve_alpha:
type: boolean
default: true
description: 'Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.
- When true: The output image maintains the original transparency of fully and partially transparent pixels.
- When false: The transparency values from the input are not preserved, but the output may still include an alpha channel (e.g., around the cropped area).
- Has no effect if the input image does not include an alpha channel.
'
content_moderation:
type: boolean
default: false
description: 'When enabled, applies content moderation to both input visuals and modified outputs.
For input images:
- Processing stops if the image fails moderation
- Returns a 422 error with details about which parameter failed
For output images:
- If the modified image fails moderation, returns a 422 error
'
example:
image_url: https://labs-assets.bria.ai/sandbox-example-inputs/product_cutout_example_image.jpg
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
result_url:
type: string
description: The URL of the processed product cutout image. This is a temporary URL that expires after 1 hour.
example:
result_url: 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.'
'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.
'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.
output_violation:
value: The request could not be completed because the modified visual did not pass content moderation.
'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.
/product/packshot:
post:
summary: Product Packshot
tags:
- Product Endpoints
description: '[**Try out this capability in Bria''s sandbox**](https://platform.bria.ai/product-shot-editing/product-packshot)
**Description**
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.
This API endpoint supports content moderation via an optional parameter that can prevent processing if input images contain inappropriate content or if the modified output would contain inappropriate content.'
operationId: product-packshot
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:
sku:
type: string
description: The Stock Keeping Unit identifier for the product. This parameter is optional.
image_url:
type: string
description: The URL of the product image or product cutout. If both image_url and file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.
file:
type: string
description: 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:
type: string
description: The background hex color code for the pack shot. Optionally, use 'transparent' for a transparent background. This parameter is optional.
default: '#FFFFFF'
force_rmbg:
type: boolean
default: false
description: Forces background removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels.
content_moderation:
type: boolean
default: false
description: 'When enabled, applies content moderation to both input visuals and modified outputs.
For input images:
- Processing stops if the image fails moderation
- Returns a 422 error with details about which parameter failed
For output images:
- If the modified image fails moderation, returns a 422 error
'
example:
image_url: https://labs-assets.bria.ai/sandbox-example-inputs/product_packshot_example_image.jpg
background_color: '#FFFFFF'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
result_url:
type: string
description: The URL of the processed product pack shot image. This is a temporary URL that expires after 1 hour.
example:
result_url: 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.'
'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.
'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.
output_violation:
value: The request could not be completed because the modified visual did not pass content moderation.
'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.
/product/shadow:
post:
summary: Product Shadow
tags:
- Product Endpoints
description: '[**Try out this capability in Bria''s sandbox**](https://platform.bria.ai/product-shot-editing/product-shadow)
**Description**
The Product Shadow API allows you to add consistent and customizable shadow to a product cutout. This feature is designed to work in combination with other capabilities like product cutout, product packshot and product lifestyle shots, enhancing the visual appeal of e-commerce and product imagery.
If the product image isn''t a product cutout, you should use the product cutout API first. The product shadow API accepts a product cutout as input. Once you have a product cutout with a shadow, you can use it in product packshot or product lifestyle shot APIs, where needed.
This API endpoint supports content moderation via an optional parameter that can prevent processing if input images contain inappropriate content or if the modified output would contain inappropriate content.'
operationId: product-shadow
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:
sku:
type: string
description: The Stock Keeping Unit identifier for the product. This parameter is optional.
image_url:
type: string
description: The URL of the product image or product cutout. If both image_url and file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB. The input image must have a transparent background, could be obtained by using our background removal or cutout features.
file:
type: string
description: 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. The input image must have a transparent background, could be obtained by using our background removal or cutout features.
type:
type: string
description: Specifies the type of shadow. It can be 'regular' or 'float'. This parameter is optional.
default: regular
background_color:
type: string
description: The background hex color code for the resulting image. If you would like to get a transparent background, don't include this parameter in the request. This parameter is optional.
shadow_color:
type: string
description: The shadow color hex code. This parameter is optional.
default: '#000000'
shadow_offset:
type: array
description: Controls the position of the shadow relative to the object, in pixels. Accepts a tuple-like list `[x, y]` where x and y can be positive or negative values. This parameter is optional.
items:
type: integer
default:
- 0
- 15
shadow_intensity:
type: integer
description: Adjusts the intensity of the shadow. This parameter is optional.
minimum: 0
maximum: 100
default: 60
shadow_blur:
type: integer
description: Controls the blur level of the shadow's edges. This parameter is optional. Default for 'shadow_type'=regular is 15, while for 'shadow_type'=float is 20.
shadow_width:
type: integer
description: (For floating shadows) Controls the width of the elliptical shadow, in pixels that could be positive and negative. As default the value is according to the width of the product. This parameter is optional.
shadow_height:
type: integer
description: (For floating shadows) Controls the height of the elliptical shadow, in pixels that could be positive and negative. This parameter is optional.
default: 70
force_rmbg:
type: boolean
default: false
description: Forces background removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels.
preserve_alpha:
type: boolean
default: true
description: 'Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.
- When true: The output image maintains the original transparency of fully and partially transparent pixels.
- When false: The transparency values from the input are not preserved, but the output may still include an alpha channel (e.g., around the cropped area).
- Has no effect if the input image does not include an alpha channel.
'
content_moderation:
type: boolean
default: false
description: 'When enabled, applies content moderation to both input visuals and modified outputs.
For input images:
- Processing stops if the image fails moderation
- Returns a 422 error with details about which parameter failed
For output images:
- If the modified image fails moderation, returns a 422 error
'
example:
image_url: https://i.ibb.co/p6VjyrfY/6901921e-8856-4fbd-b344-b5e88bcf90e6.png
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
result_url:
type: string
description: The URL of the processed product pack shot image. This is a temporary URL that expires after 1 hour.
example:
result_url: 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.'
'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.
'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.
output_violation:
value: The request could not be completed because the modified visual did not pass content moderation.
'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.
/product/lifestyle_shot_by_text:
post:
summary: Lifestyle Product Shot by Text
tags:
- Product Endpoints
description: "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/product-shot-editing/lifestyle-product-shot-by-text)\n\n**Description**\n\nCreates enriched product shots by placing them in various environments using textual descriptions.\n\n\nIn addition, you can adjust the background of the product by replacing it with a solid color. \n\nTo do this, specify a hex color code (e.g., #FF5733) in the `scene_description`. \n\n\nThis feature is only available when generating a single result (`num_results=1`).\n\n\nThis endpoint also allows adjusting the position of the product and the size of the final product shot.\n\n\nThis enables the creation of new and unique variations of your original product image while maintaining control over layout and format.\n\n\nTo control product positioning and shot dimensions, use the `placement_type` parameter, which offers several control modes:\n\n\n\n\n- `original`: preserves the original position and size of the product from the input image.\n\n\n\n\n- `automatic`: generates results with 7 recommended placements, while the shot_size is defined by the 'shot_size' parameter.\n\n\n\n\n- `manual_placement`: allows choosing from predefined positions using `manual_placement_selection`. The shot_size is defined by the 'shot_size' parameter.\n\n\n\n\n- `custom_coordinates`: provides full control over the product's size and location using `foreground_image_size` and `foreground_image_location`. The shot_size is defined by the 'shot_size' parameter.\n\n\n\n\n- `manual_padding`: lets you define padding in pixels around the product to control both size and placement.\n\n\n\n\n- `automatic_aspect_ratio`: centers the product and resizes the canvas automatically to match the specified `aspect_ratio`.\n\n\n\n\n\nThe parameters used for positioning and sizing depend on the selected `placement_type`. Refer to the documentation for each mode to understand the supported fields and behaviors.\n\n\nWe offer 3 different background generation modes when generating by text: base, high contol and fast.\n\n - **Base** - clean, high quality backgrounds.\n - **High_control** - Stronger prompt adherence and scene context, finer control over layout and details - **we recommend using this mode.**\n - **Fast** - same core capabilities as base, optimal speed and quality balace.\n\nThis API endpoint supports content moderation via an optional parameter that can prevent processing if input images contain inappropriate content, and filters out unsafe modified images - the first blocked input image will fail the entire request."
operationId: product-lifestyle-shot-by-text
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:
sku:
type: string
description: The Stock Keeping Unit identifier for the product. This parameter is optional.
sync:
type: boolean
default: false
description: 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.
mode:
type: string
enum:
- base
- high_control
- fast
default: fast
description: 'Selects the background-generation mode.
- **Base** - clean, high quality backgrounds.
- **High_control** - stronger prompt adherence and scene context, finer control over layout and details.
- **Fast** - same core capabilities as base, optimal speed and quality balace.
'
image_url:
type: string
description: The URL of the product shot to be placed in a lifestyle shot. If both image_url and file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.
file:
type: string
description: 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:
type: string
description: 'Text description of the new scene or background for the provided product shot. Bria currently supports prompts in English only, excluding special characters.
**Prompt length guidelines per mode:**
- base / fast: ~50–60 words
- high_control: ~90–110 words
'
optimize_description:
type: boolean
default: true
description: 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:
type: integer
default: 4
description: The number of lifestyle product shots you would like to generate. You will get num_results x 10 results when placement_type=automatic and according to the number of required placements x num_results if placement_type=manual_placement.
exclude_elements:
type: string
description: Elements or features that should be excluded from the generated scene. This parameter is optional and is available only when fast=false. Bria currently supports descriptions in English only, excluding special characters.
placement_type:
type: string
default: original
description: 'This parameter allows you to select the control mode for determining both the product''s positioning and the final shot size.
- "original" will preserve the original position of the product in the image. The parameters `original_quality`, `aspect_ratio`, `foreground_image_size`, `foreground_image_location`, `manual_placement_selection`, `padding_values`, and `shot_size` will be ignored when this mode is used.
- "automatic" will generate results with 7 of the recommended product positions. The shot_size is defined by the ''shot_size'' parameter.
- "manual_placement" will allow you to select predefined positions, using the parameter "manual_placement_selection". The shot_size is defined by the ''shot_size'' parameter.
- "custom_coordinates" Provides precise control over the size and position of the image using the parameters "foreground_image_size" and "foreground_image_location". This includes positions outside the canvas, which may result in cropping. The shot_size is defined by the ''shot_size'' parameter.
- "manual_padding" will allow you to control the position and size of the image by defining the desired padding (using ''padding_values'') in pixels around the product.
- "automatic_aspect_ratio" will automatically center the product within the canvas and resize the canvas to match the provided `aspect_ratio`. The parameters `original_quality`, `foreground_image_size`, `foreground_image_location`, `manual_placement_selection`, `padding_values`, and `shot_size` will be ignored when this mode is used.'
enum:
- original
- automatic
- manual_placement
- manual_padding
- custom_coordinates
- automatic_aspect_ratio
original_quality:
type: boolean
default: false
description: This flag is only relevant when placement_type=original. If true, the output image retains the original input image's size; otherwise, the image is scaled to 1 megapixel (1MP) while preserving its aspect ratio.
aspect_ratio:
type: string
enum:
- '1:1'
- '2:3'
- '3:2'
- '3:4'
- '4:3'
- '4:5'
- '5:4'
- '9:16'
- '16:9'
description: 'Defines the aspect ratio of the output product shot when `placement_type` is set to `automatic_aspect_ratio`.
The original image will be automatically positioned and scaled to fit this aspect ratio.
Ignored for all other placement types.
'
shot_size:
type: array
items:
type: integer
default:
- 1000
- 1000
description: 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 is automatic, manual_placement or custom_coordinates.
foreground_image_size:
type: array
items:
type: integer
description: Specifies the desired dimensions of the foreground image within the generated output. The size is defined as an array of integers representing [width, height] in pixels. This parameter is only relevant when placement_type is custom_coordinates.
foreground_image_location:
type: array
items:
type: integer
description: Specifies the desired [x, y] coordinates for positioning the foreground image within the full shot. The coordinates represent the upper-left corner of the foreground image. Values can extend outside the shot, in which case the input image will be cropped accordingly. This parameter is only relevant when placement_type is custom_coordinates.
manual_placement_selection:
type: array
items:
type: string
enum:
- upper_left
- upper_right
- bottom_left
- bottom_right
- right_center
- left_center
- upper_center
- bottom_center
- center_vertical
- center_horizontal
default:
- upper_left
description: 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.
padding_values:
type: array
items:
type: integer
default:
- 0
- 0
- 0
- 0
description: The desired padding in pixels around the product, when using placement_type=manual_padding. The order of the values is [left, right, top, bottom]. 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.
force_rmbg:
type: boolean
default: false
description: Forces background removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels.
content_moderation:
type: boolean
default: false
description: "When enabled, applies content moderation to both input visuals and modified outputs.\n\nFor input images:\n- Processing stops at the first imag
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bria/refs/heads/main/openapi/bria-product-endpoints-api-openapi.yml