Bria
BRIA Product Shot
bria-product-shot
An image editing model for e-commerce product photos that naturally places products into scene backgrounds generated from text or reference images, while preserving texture and brand details
Pricing
bria-product-shot per image
| Unit Price | $0.0575 |
|---|
Overview
bria-product-shot is an image editing model for e-commerce product visuals. It takes a product image and a scene description or scene reference image, automatically places the product into a new background while preserving textures, logos, and brand details, and outputs product images ready for commercial display. It is suited for developers and e-commerce teams that need to generate product scene images in batches and reduce physical shoots and manual compositing.
Key Highlights
- Trained for product placement, with natural lighting — optimized for consistency of lighting, shadows, and scale between the product and the scene, so results look closer to real photography.
- Preserves product details and brand elements — keeps key details such as product textures, logos, and brand marks during scene compositing.
- Two ways to guide the scene: text or reference image — specify the new background with an English scene description or a scene reference image, choosing one for flexible control over the output.
- Optional preset position and original size — manually specify a preset position for the product in the frame, or output with the original size and position preserved.
Capabilities
Generate a scene from a text description: provide an English scene description (up to 1000 characters), and the model automatically generates a background and places the product into it; automatic description expansion is supported to enrich scene details.
Guide scene style with a reference image: upload a scene reference image, and the model composites the product image following its background style, which is suited for batch output with a consistent visual style.
Product position and size control: manual placement mode lets you choose the product's landing spot from ten preset positions; original mode preserves the input size and position, and you can opt out of scaling to about 1MP.
Quick mode toggle: quick mode is on by default to speed up generation; turning it off uses the standard model, letting you trade off speed against quality as needed.
Use Cases
- E-commerce operations: batch scene generation for product hero images — input product images and scene descriptions to generate product images with multiple backgrounds in batches for product detail pages and advertising assets.
- Marketing teams: multi-style variant production — use reference images to guide different background styles and quickly produce multi-style marketing images of the same product for social media and campaign pages.
- Brands: rapid visual compositing for new releases — in the new product launch process, place product images into lifestyle scenes to reduce physical shoots and get visual assets online faster.
- Developers: automated workflow integration — call through the unified HiAPI.ai interface to embed product image scene compositing into content production pipelines for large-scale automated processing.
Limitations and Selection Advice
This model provides image-to-image editing: a product image is required as input, and pure text-to-image generation is not supported; the output is a static image, with no video or 3D content involved. Its focus is e-commerce product scene compositing, and general-purpose creative image generation is not its intended use. Commercial use is subject to the relevant licensing and compliance terms. If you need to generate creative images from scratch or perform non-product editing, choose a general-purpose image generation model.
What's new
View changelog →- New model New model: bria-product-shot
Frequently asked questions
View all FAQs →-
Can I use a scene description and a scene reference together?
No, pick one. Leave out the reference image when you write an English scene description (prompt), and leave out the prompt when you follow a reference image. Switching mode in the Playground clears the other one.
-
Does the scene description have to be in English?
Yes. Describe the new scene or background in English, up to 1,000 characters; the Playground asks you to rewrite non-English text.
-
What does optimize description do?
It expands your scene description automatically and is on by default. It applies only to scene-description mode and is not sent with a reference image.
-
How can the product be placed?
Preset position (manual_placement, the default) (with either a scene description or a scene reference) puts the product at a chosen spot, bottom center by default; measured 1024×1024 for square input. Keep original position (original) keeps the product where it is in the input photo.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.
Idempotency-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.
Body
modelstringRequiredCurrent fixed value: bria-product-shot
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for bria-product-shot and route default — see the parameter table below.
fastbooleanOptionalDefault: trueFaster generation; turn off for the standard model.
promptstringOptionalminLength 1maxLength 1000English description of the new scene or background. Use either prompt or reference_image_url, not both.
image_urlstringRequiredminLength 1pattern ^https?://Public URL of the product photo (JPEG, PNG or WEBP, up to 12 MB).
placement_typestringOptionalDefault: "manual_placement"manual_placement puts the product at a preset position (with a scene description or a scene reference; measured 1024×1024 for square input); original keeps its position and the input size.
manual_placementoriginaloriginal_qualitybooleanOptionalDefault: falseKeep the input size instead of scaling to about 1 MP. Applies to original only.
reference_image_urlstringOptionalminLength 1pattern ^https?://Image whose scene or background style to follow. Use either prompt or reference_image_url, not both.
optimize_descriptionbooleanOptionalDefault: trueExpand the scene description automatically. Applies to prompt only.
manual_placement_selectionstringOptionalDefault: "bottom_center"Preset product position. Applies to manual_placement only.
bottom_centerupper_leftupper_rightbottom_leftbottom_rightright_centerleft_centerupper_centerShow all (2)
center_verticalcenter_horizontalcallbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.
urlstringRequiredRequired when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.
whenstringOptionalDefault: "final"Only final is supported today — notified on both success and fail.
finalstoragestringOptionalDefault: "temp"Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.
temppersistentRequest examples
# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bria-product-shot",
"input": {
"fast": true,
"image_url": "…",
"placement_type": "manual_placement",
"original_quality": false,
"optimize_description": true,
"manual_placement_selection": "bottom_center"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "bria-product-shot",
input: {
"fast": true,
"image_url": "…",
"placement_type": "manual_placement",
"original_quality": false,
"optimize_description": true,
"manual_placement_selection": "bottom_center"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "bria-product-shot",
"input": {
"fast": True,
"image_url": "…",
"placement_type": "manual_placement",
"original_quality": False,
"optimize_description": True,
"manual_placement_selection": "bottom_center"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Get task detail
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
queued Queued, not started yet.
handling Being processed.
archiving Processing finished, artifacts being prepared.
success Terminal: completed, artifacts available (output returned).
fail Terminal: failed (error returned).
After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix seconds when the task reached a terminal state; fixed to 0 while not terminal.
outputarrayOptional
Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).
Array [ object ]
Array items
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError description.
Response examples
Success
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Processing (non-terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Failed
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Articles
View all articles →Related Models
View all models →Same Type
-
Muse Image 1.0 Meta $0.015 per task -
FASHN Tryon v1.6 FASHN $0.107 /image -
Nano Banana 2 Lite Google $0.033 /image -
Nano Banana 2 Google $0.036 /image -
Qwen Image 2.0 Alibaba $0.042 /image -
FLUX 3 Image Black Forest Labs $0.041 /image -
Wan 2.7 Image Alibaba $0.035 /image -
Recraft Creative Upscale Recraft $0.357 /image -
GPT Image 2 OpenAI $0.007 /image -
Grok Imagine xAI $0.011 /second -
FLUX.2 Klein 9B Black Forest Labs $0.0086 /image -
Recraft Crisp Upscale Recraft $0.004 /image