API reference · Bria

bria/product-shot

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

IMAGEAsyncOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

POSThttps://api.sandbase.ai/v1/run

Model IDbria/product-shot

Input Schema

11 parameters · 1 required · 10 optional

Parameter	Type	Required	Description
`image`	string	Required	The URL of the product shot to be placed in a lifestyle shot. 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.
`fast`	boolean	Optional	Whether to use the fast model · Default: true
`shot_size`	integer[]	Optional	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=automatic or placement_type=manual_placement. · Default: [1000,1000]
`num_results`	integer	Optional	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. · Min: 1 · Max: 4 · Default: 1
`ref_image_url`	string	Optional	The URL of the reference image to be used for generating the new scene or background for the product shot. Use "" to leave empty.Either ref_image_url or scene_description has to be provided but not both. If both ref_image_url and ref_image_file are provided, ref_image_url will be used. Accepted formats are jpeg, jpg, png, webp. · Default: ""
`padding_values`	integer[]	Optional	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.
`placement_type`	string	Optional	This parameter allows you to control the positioning of the product in the image. Choosing 'original' will preserve the original position of the product in the image. Choosing 'automatic' will generate results with the 10 recommended positions for the product. Choosing 'manual_placement' will allow you to select predefined positions (using the parameter 'manual_placement_selection'). Selecting 'manual_padding' will allow you to control the position and size of the image by defining the desired padding in pixels around the product. · Options: original, automatic, manual_placement, manual_padding · Default: "manual_placement" originalautomaticmanual_placementmanual_padding
`original_quality`	boolean	Optional	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
`scene_description`	string	Optional	Text description of the new scene or background for the provided product shot. Bria currently supports prompts in English only, excluding special characters.
`optimize_description`	boolean	Optional	Whether to optimize the scene description · Default: true
`manual_placement_selection`	string	Optional	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. · Options: upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, bottom_center, center_vertical, center_horizontal · Default: "bottom_center" upper_leftupper_rightbottom_leftbottom_rightright_centerleft_centerupper_centerbottom_centercenter_verticalcenter_horizontal

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Async Workflow

This model uses asynchronous execution. Submit a request and poll for the result.

Submit — POST to /v1/run, receive an id
Poll — GET /v1/run/{id} until status is completed, failed, or timeout
Retrieve — Read outputs from the completed response

Code Examples

Ready-to-run snippets

# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "model": "bria/product-shot",
  "fast": true,
  "image": "https://static.sandbase.ai/examples/bria/product-shot/input_image_1.jpg",
  "shot_size": [
    1000,
    1000
  ],
  "num_results": 1,
  "ref_image_url": "https://static.sandbase.ai/examples/bria/product-shot/input_ref_image_url_0.jpg",
  "placement_type": "manual_placement",
  "original_quality": false,
  "scene_description": "on a rock, next to the ocean, dark theme",
  "optimize_description": true,
  "manual_placement_selection": "bottom_center",
  "prompt": "a beautiful sunset over mountains"
}'

# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
  -H "Authorization: Bearer YOUR_API_KEY"

← Back to Bria Product Shot