Sign in

v1

latestOpenAPI 3.0.02026-08-061612131.2 KB
Automotive Endpoints

Vehicle Shot by text

Try out this capability in Bria's Automobile Playground

Description Creates enriched automotive product shots by placing vehicles in realistic environments using textual descriptions.

This endpoint includes vehicle-specific enhancements that adapt the background scene to match automotive contexts, specifically - snow, sand, and grass. It embeds the vehicle into the environment for a natural, grounded appearance.

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.

post/product/vehicle/shot_by_text

Headers

api_tokenstring required

API token associated with the organization

Request body

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.

mode'base' | 'high_control' | 'fast'

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_urlstring

The URL of the vehicle to be placed in the 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 vehicle file to be placed in the 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 vehicle 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_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.

num_resultsinteger

The number of vehicle 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_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_type'original' | 'automatic' | 'manual_placement' | 'manual_padding' | 'custom_coordinates' | 'automatic_aspect_ratio'

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

aspect_ratio'1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9'

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_sizeinteger[]

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_sizeinteger[]

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_locationinteger[]

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_selectionstring[]

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_valuesinteger[]

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

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

Response

Successful operation