Products

Product Holding

Changed on

Description

Put your product in someone's hands. Send person_image and one to three product_images, and the endpoint returns the person naturally holding or carrying the product.

No prompt needed. A person photo and a product photo are a complete request.

The person's identity, pose and background are preserved, along with the original aspect ratio, and the product keeps its exact geometry, colours, branding and label text. Several product references in one call compose packaging, a second angle or a companion item into a single shot.

Add an optional instruction to art-direct a specific shot. Commercially safe: built on Bria's fully licensed models, cleared for enterprise use without copyright exposure.

Example: "Replace the paper coffee cup in her right hand with the can, logo facing the camera."

<table> <tr> <th style="text-align: center;">Person</th> <th style="text-align: center;">Product</th> <th style="text-align: center;">Result</th> </tr> <tr> <td align="center" style="vertical-align: middle;"> <img src="https://labs-assets.bria.ai/api-examples/product-holding/person.jpg" width="250" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://labs-assets.bria.ai/api-examples/product-holding/product.jpg" width="250" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://labs-assets.bria.ai/api-examples/product-holding/result.jpg" width="250" style="border-radius: 8px;"> </td> </tr> </table>
post/image/edit/product/holding

Request

  • Base URL: https://engine.prod.bria-api.com/v2
  • URL: https://engine.prod.bria-api.com/v2/image/edit/product/holding
  • Auth: API key in header api_token

Request body

person_imagestring required

The photo of the person to edit. Publicly available URL or Base64-encoded. Accepted formats: JPEG, JPG, PNG, WEBP.

product_imagesstring[] required

One to three images of the product: packaging, a second angle, or a companion item. Each entry is a publicly available URL or Base64-encoded, same as person_image.

instructionstring

Extra direction for this shot. This parameter is optional. The endpoint produces the result without it, so send only the detail you want to steer, for example "Replace the paper coffee cup in her right hand with the can, logo facing the camera.", rather than a full prompt.

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

The aspect ratio of the output image. This parameter is optional. Default: the aspect ratio of person_image, so the shot keeps its original framing.

seedinteger

Seed for deterministic generation, so a shot can be reproduced exactly. Uses a random seed if omitted. This parameter is optional.

syncboolean

Specifies the response mode. This parameter is optional.

  • When false (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.
  • When true, the request is processed synchronously: the API holds the connection open until the process is complete and then returns the final image URL in the response.
webhook_urlstring uri

Optional URL for receiving the result via webhook when the async job completes. See webhooks.

output_type'png' | 'jpeg'

The desired output format.

visual_output_content_moderationboolean

If true, returns 422 on visual output moderation failure. This parameter is optional.

Response

Successful operation (Synchronous Success)

Changes