Product Shot Editing

Product Packshot

Overview

Bria’s Product Shot Editing APIs gives builders powerful tools to streamline visual content creation — enabling developers to automate and enhance product shots with more control, flexibility, and realism.

Core capabilities include product cutouts, customizable backgrounds for professional packshots, consistent shadow rendering, and AI-powered lifestyle shots using both text and reference images.

Automotive Product Shot Editing

As a first step, we’ve introduced dedicated support for automotive workflows — adding vehicle-specific features such as realistic reflection generation, tire and wheel refinement, environmental effects (e.g., fog, dust, snow), and harmonization presets.

These capabilities are designed to reduce manual work and help teams create high-quality vehicle visuals faster, with more creative control. Support for additional product categories is coming soon.

Download OpenAPI description

product-shot-editing.json

product-shot-editing.yaml

Servers

https://engine.prod.bria-api.com/v1/

Product Endpoints

Operations

Product Cutout

Request

This 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.

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.

Headers

api_tokenstringrequired

API token associated with the organization

Bodyapplication/json

skustring

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

image_urlstring

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.

filestring

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_rmbgboolean

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.

Default false

preserve_alphaboolean

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.

Default true

content_moderationboolean

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

Default false

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/cutout \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "sku": "12345",
    "image_url": "URL"
  }'

Responses

Successful operation.

Bodyapplication/json

result_urlstring

The URL of the processed product cutout image. This is a temporary URL that expires after 1 hour.

Response

application/json

{
  "result_url": "URL"
}

Product Packshot

Request

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.

Headers

api_tokenstringrequired

API token associated with the organization.

Bodyapplication/json

skustring

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

image_urlstring

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.

filestring

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_colorstring

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

Default "#FFFFFF"

force_rmbgboolean

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.

Default false

content_moderationboolean

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

Default false

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/packshot \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "sku": "12345",
    "image_url": "URL",
    "background_color": "#FFFFFF"
  }'

Responses

Successful operation.

Bodyapplication/json

result_urlstring

The URL of the processed product pack shot image. This is a temporary URL that expires after 1 hour.

Response

application/json

{
  "result_url": "URL"
}

Product Shadow

Request

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.

Headers

api_tokenstringrequired

API token associated with the organization.

Bodyapplication/json

skustring

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

image_urlstring

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.

filestring

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.

typestring

Specifies the type of shadow. It can be 'regular' or 'float'. This parameter is optional.

Default "regular"

background_colorstring

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_colorstring

The shadow color hex code. This parameter is optional.

Default "#000000"

shadow_offsetArray of integers

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.

Default [0,15]

shadow_intensityinteger[ 0 .. 100 ]

Adjusts the intensity of the shadow. This parameter is optional.

Default 60

shadow_blurinteger

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_widthinteger

(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_heightinteger

(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_rmbgboolean

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.

Default false

preserve_alphaboolean

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.

Default true

content_moderationboolean

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

Default false

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/shadow \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "sku": "12345",
    "image_url": "URL"
  }'

Responses

Successful operation.

Bodyapplication/json

result_urlstring

The URL of the processed product pack shot image. This is a temporary URL that expires after 1 hour.

Response

application/json

{
  "result_url": "URL"
}

Lifestyle Product Shot by Text

Request

Creates enriched product shots by placing them in various environments using textual descriptions.

In addition, you can adjust the background of the product by replacing it with a solid color. To do this, specify a hex color code (e.g., #FF5733) in the scene_description.

This feature is only available when generating a single result (num_results=1).

This endpoint also allows adjusting the position of the product and the size of the final product shot.

This enables the creation of new and unique variations of your original product image while maintaining control over layout and format.

To control product positioning and shot dimensions, use the placement_type parameter, which offers several control modes:

original: preserves the original position and size of the product from the input image.
automatic: generates results with 7 recommended placements, while the shot_size is defined by the 'shot_size' parameter.
manual_placement: allows choosing from predefined positions using manual_placement_selection. The shot_size is defined by the 'shot_size' parameter.
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.
manual_padding: lets you define padding in pixels around the product to control both size and placement.
automatic_aspect_ratio: centers the product and resizes the canvas automatically to match the specified aspect_ratio.

The 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.

This 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.

Headers

api_tokenstringrequired

API token associated with the organization.

Bodyapplication/json

skustring

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

syncboolean

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.

Default false

fastboolean

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.

Default true

image_urlstring

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.

filestring

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_descriptionstring

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

optimize_descriptionboolean

When true, an additional logic takes the scene_description that was included and adjusts it to achieve optimal results. Built with Meta Llama 3.

Default true

num_resultsinteger

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.

Default 4

exclude_elementsstring

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_typestring

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.

Default "original"

Enum"original""automatic""manual_placement""manual_padding""custom_coordinates""automatic_aspect_ratio"

original_qualityboolean

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.

Default false

aspect_ratiostring

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.

Enum"1:1""2:3""3:2""3:4""4:3""4:5""5:4""9:16""16:9"

shot_sizeArray of integers

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.

Default [1000,1000]

foreground_image_sizeArray of integers

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_locationArray of integers

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_selectionArray of strings

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.

Default ["upper_left"]

Items Enum"upper_left""upper_right""bottom_left""bottom_right""right_center""left_center""upper_center""bottom_center""center_vertical""center_horizontal"

padding_valuesArray of integers

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.

Default [0,0,0,0]

force_rmbgboolean

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.

Default false

content_moderationboolean

When enabled, applies content moderation to both input visuals and modified outputs.

For input images:

Processing stops at the first image that fails moderation
Returns a 422 error with details about which parameter failed

For synchronous requests (sync=true):

If all modified images fail moderation, returns a 422 error
If some images pass and others fail, returns a 200 response with successful outputs and "blocked" objects for failed ones

For asynchronous requests (sync=false):

Failed images are replaced with zero-byte files at their placeholder URLs
Successful images are stored at their original placeholder URLs

Default false

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/lifestyle_shot_by_text \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image_url": "URL",
    "scene_description": "In a living room interior, on a kitchen counter",
    "placement_type": "original",
    "num_results": 2,
    "original_quality": true,
    "optimize_description": true,
    "sync": true
  }'

Responses

Successful operation

Bodyapplication/json

resultArray of strings

The array contains the results created in the request. In each result, the first value represents the URL of the result, the second value represents the seed, and the third value represents the session id of the result. It will take a few seconds for the image to become available via the URL if sync=false. You can recreate the same result in the future by using the seed as part of the request.

When content_moderation is true:

For synchronous requests (sync=true): Results array will contain both successful generations and "blocked" objects for images that failed moderation
For asynchronous requests (sync=false): Failed images will be replaced with zero-byte files at their placeholder URLs

Response

application/json

{
  "result": [
    [ … ],
    [ … ]
  ]
}

Lifestyle Product Shot by Image

Request

Generates enriched product shots by placing them in visually compelling environments, guided by a reference image.

This endpoint also allows adjusting the position of the product and the size of the final product shot. This enables the creation of new and unique variations of your original product image while maintaining control over layout and format.

To control product positioning and shot dimensions, use the placement_type parameter, which offers several control modes:

original: preserves the original position and size of the product from the input image.
automatic: generates results with 7 recommended placements, while the shot_size is defined by the 'shot_size' parameter.
manual_placement: allows choosing from predefined positions using manual_placement_selection. The shot_size is defined by the 'shot_size' parameter.
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.
manual_padding: lets you define padding in pixels around the product to control both size and placement.
automatic_aspect_ratio: centers the product and resizes the canvas automatically to match the specified aspect_ratio.

The 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.

Headers

api_tokenstringrequired

API token associated with the organization.

Bodyapplication/json

skustring

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

syncboolean

Default false

image_urlstring

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.

filestring

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.

ref_image_urlsArray of strings

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

ref_image_fileArray of strings

The reference image file to be used for generating the lifestyle shot, in base64 format. Only a single refernce image is supported at the moment. Used if ref_image_urls is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

enhance_ref_imageboolean

When set to True, enhances the reference image by applying adjustments, such as lighting, shadows, and texture refinements, to produce more realistic and visually cohesive results. When enabled, this may also incorporate subtle elements from the reference image into the generated background for added authenticity.

Default true

ref_image_influencenumber(float)[ 0 .. 1 ]

Controls the degree of similarity between the generated background and the reference image, where 0.0 produces minimal resemblance and 1.0 creates a highly similar output.

Default 1

num_resultsinteger

The number of lifestyle product shots you would like to generate.

Default 4

placement_typestring

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_qualityboolean

This flag is only relevant when placement_type=original. If true, the output image retains the original input image's size (and not the reference image size); otherwise, the image is scaled to 1 megapixel (1MP) while preserving its aspect ratio.

Default false

aspect_ratiostring

Enum"1:1""2:3""3:2""3:4""4:3""4:5""5:4""9:16""16:9"

shot_sizeArray of integers

Default [1000,1000]

foreground_image_sizeArray of integers

foreground_image_locationArray of integers

manual_placement_selectionArray of strings

Default ["upper_left"]

Items Enum"upper_left""upper_right""bottom_left""bottom_right""right_center""left_center""upper_center""bottom_center""center_vertical""center_horizontal"

padding_valuesArray of integers

Default [0,0,0,0]

force_rmbgboolean

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.

Default false

content_moderationboolean

When enabled, applies content moderation to both input visuals and modified outputs.

For input images:

Processing stops at the first image that fails moderation
Returns a 422 error with details about which parameter failed

For synchronous requests (sync=true):

If all modified images fail moderation, returns a 422 error
If some images pass and others fail, returns a 200 response with successful outputs and "blocked" objects for failed ones

For asynchronous requests (sync=false):

Failed images are replaced with zero-byte files at their placeholder URLs
Successful images are stored at their original placeholder URLs

Default false

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/lifestyle_shot_by_image \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image_url": "URL",
    "ref_image_urls": "URL",
    "placement_type": "original",
    "num_results": 2,
    "original_quality": true,
    "sync": true
  }'

Responses

Successful operation

Bodyapplication/json

resultArray of strings

When content_moderation is true:

For synchronous requests (sync=true): Results array will contain both successful generations and "blocked" objects for images that failed moderation
For asynchronous requests (sync=false): Failed images will be replaced with zero-byte files at their placeholder URLs

Response

application/json

{
  "result": [
    [ … ],
    [ … ]
  ]
}

Consistent Product Shots (Coming Soon)

Request

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, eCommerce websites, product catalogs, and other marketing materials, ensuring a uniform and professional appearance across all platforms.

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/products/consistent_shots

Responses

Successful operation.

Contextual Keyword Extraction (Coming Soon)

Request

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 eCommerce by ensuring that the keywords accurately represent the product being sold. It can be particularly useful for improving product searchability on eCommerce websites, enhancing SEO for product listings, automating content management, and optimizing social media marketing efforts.

curl -i -X POST \
  https://engine.prod.bria-api.com/v1/product/contextual_keyword_extraction

Responses

Successful operation.

Automotive Endpoints

Operations

Overview

Product Endpoints

Product Cutout

Request

Responses

Was this helpful?

Product Packshot

Request

Responses

Was this helpful?

Product Shadow

Request

Responses

Was this helpful?

Lifestyle Product Shot by Text

Request

Responses

Was this helpful?

Lifestyle Product Shot by Image

Request

Responses

Was this helpful?

Consistent Product Shots (Coming Soon)

Request

Responses

Was this helpful?

Contextual Keyword Extraction (Coming Soon)

Request

Responses

Was this helpful?

Automotive Endpoints