Bria Product Shot

Usage-based pricing
ae_bria_product_shot

Create lifestyle product photos by placing your product image in a new scene or background, with control over its position.

Image
Usage-based pricing

Pricing

The charge per call is (max(48 × number of successfully generated results, 0)) AE credits. All applicable conditions are combined to calculate the total.

Charges are based on the number of successfully generated results; server errors and queue time are not charged.

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
request_bodyobjectYesNo parameter description.—
request_body.fastbooleanNoWhether to use the fast modeltrue
request_body.image_urlstringYesThe 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.—
request_body.shot_sizearrayNoThe 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.—
request_body.sync_modebooleanNoIf `True`, the media will be returned as a data URI and the output data won't be available in the request history.false
request_body.num_resultsintegerNoThe 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.1
request_body.ref_image_urlstringNoThe 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.""
request_body.padding_valuesarrayNoThe 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.—
request_body.placement_typeenum (original | automatic | manual_placement | manual_padding)NoThis 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.manual_placement
request_body.original_qualitybooleanNoThis 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.false
request_body.scene_descriptionstring | unknownNoText description of the new scene or background for the provided product shot. Bria currently supports prompts in English only, excluding special characters.—
request_body.optimize_descriptionbooleanNoWhether to optimize the scene descriptiontrue
request_body.manual_placement_selectionenum (upper_left | upper_right | bottom_left | bottom_right | right_center | left_center | upper_center | bottom_center | center_vertical | center_horizontal)NoIf 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.bottom_center

Invocation example

Copy the request and explore its response example.

POST/agent-api/v1/tool/executeX-Api-Key

Submit first, then query with the returned task_id until the task completes.

Request coderequest.sh
curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_bria_product_shot' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "request_body": {
      "image_url": "https://file.gw.xnetwk.net/file/80da3009-c33d-4220-a6dc-f0996f494285.jpg",
      "manual_placement_selection": "bottom_center",
      "num_results": 1,
      "optimize_description": true,
      "placement_type": "manual_placement",
      "scene_description": "on a sandy beach with gentle ocean waves and clear blue sky in the background, warm summer sunlight, natural shadows, premium vacation lifestyle photography"
    }
  }
}'
Response exampleresponse.json
JSON
{
  "description": "task accepted; poll the result via query_tool with this task_id",
  "query_tool": "ae_get_result",
  "status": "created",
  "task_id": "4723d869-7dfc-4bc1-8e1f-7a968d968566"
}