Bria Product Shot API

POST Base URL: https://api.hiapi.ai /v1/tasks

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	bria-product-shot
Type	Image editing (product shots)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Bria Product Shot places a product photo into a new scene from an English scene description or a scene reference image (pick one), with preset or original placement — for e-commerce, ads and social assets.

Production guidance

Send exactly one of prompt or reference_image_url — both or neither returns a parameter error. optimize_description goes only with prompt; manual_placement_selection only with manual_placement and original_quality only with original.
For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
Result URLs expire — copy the output to your own storage once the task succeeds.

Best suited for

E-commerce hero images

Put a plain product photo into a styled scene, consistently placed at the bottom center of the canvas.

image_urlpromptmanual_placement_selection

Follow a reference style

Upload a mood image and let the product scene follow its background style.

reference_image_url

Keep the composition

Keep the product's position and scale from the photo and replace only the background.

placement_typeoriginal_quality

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546029235-98cf020f23ff79b2-p1-serum-src.png",
    "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
    "placement_type": "manual_placement",
    "manual_placement_selection": "bottom_center"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546029235-98cf020f23ff79b2-p1-serum-src.png",
    "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
    "placement_type": "manual_placement",
    "manual_placement_selection": "bottom_center"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546029235-98cf020f23ff79b2-p1-serum-src.png",
    "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
    "placement_type": "manual_placement",
    "manual_placement_selection": "bottom_center"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value bria-product-shot.

example bria-product-shot

input object required

Business parameters. Provide exactly one of prompt or reference_image_url.

image_url string required

Public URL (http/https) of the product photo. JPEG, PNG or WEBP, up to 12 MB.

example

https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546029235-98cf020f23ff79b2-p1-serum-src.png

prompt string optional

English description of the new scene or background, 1–1,000 characters. Required unless reference_image_url is set; do not send both.

example On a white marble countertop beside a window, soft morning light, a few green leaves in the background

reference_image_url string optional

Image whose scene or background style to follow. Required unless prompt is set; do not send both.

example

https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546031369-51ae5323f709b007-p3-scene-ref.png

optimize_description boolean optional

Expand the scene description automatically. Only with prompt; do not send it with reference_image_url.

default true

fast boolean optional

Faster generation; set false for the standard mode. The price is the same.

default true

placement_type enum optional

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.

default manual_placement enum: manual_placementoriginal

manual_placement_selection enum optional

Preset product position. Only with manual_placement; do not send it with original.

default bottom_center enum: bottom_centerupper_leftupper_rightbottom_leftbottom_rightright_centerleft_centerupper_centercenter_verticalcenter_horizontal

original_quality boolean optional

Keep the input size instead of scaling to about 1 MP. Only with placement_type original.

default false

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

English scene description + preset position

Golden task: one English sentence sets the surface, light and props; the product sits at the bottom center; measured 1024×1024 for square input.

Request body

{
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546029235-98cf020f23ff79b2-p1-serum-src.png",
    "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
    "placement_type": "manual_placement",
    "manual_placement_selection": "bottom_center"
  }
}

Scene reference + preset position

No prompt: the background follows the reference scene, and the headphones sit on its concrete pedestal at the bottom center; measured 1024×1024 for square input.

Request body

{
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546030593-1a0141656fd5be3e-p3-headphones-src.png",
    "reference_image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546031369-51ae5323f709b007-p3-scene-ref.png",
    "placement_type": "manual_placement",
    "manual_placement_selection": "bottom_center"
  }
}

Original position + original size

The product keeps its position and scale from the photo; with original_quality on, the output keeps the input size (measured 1168×880). manual_placement_selection is not sent.

Request body

{
  "model": "bria-product-shot",
  "input": {
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-product-shot/2026/10/21/1792546031810-bd2c7181e19c3cb3-p4-candle-src.png",
    "prompt": "On a wooden bedside table in a calm bedroom at dusk, soft warm lamp light, linen bedding blurred in the background",
    "placement_type": "original",
    "original_quality": true
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, read the image URL from output and download it.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

Can I send prompt and reference_image_url together?

No. Send exactly one; both or neither returns a parameter error.

Does the prompt have to be in English?

Yes. Describe the new scene or background in English, up to 1,000 characters.

When does optimize_description apply?

Only with prompt, and it is on by default. Do not send it with reference_image_url.

How can the product be placed?

manual_placement (default; works with a scene description or a scene reference) puts it at a preset position, bottom_center by default, measured 1024×1024 for square input; original keeps its position from the input photo.

When can I use original_quality?

Only when placement_type is original: true keeps the input size, false scales to about 1 MP.

What format and size is the output?

One PNG per request: preset position (with a scene description or a scene reference) measured 1024×1024 for square input; with placement_type original and original_quality true, the output keeps the input size (measured: 1168×880 in, 1168×880 out).

What does fast change?

It defaults to true for faster results; set false for the standard mode at the same price.

What product images work?

JPEG, PNG or WEBP up to 12 MB, as a publicly reachable http/https URL. A clear product with complete edges works best.

How is it billed?

Per output image, one image per request. See the live pricing page for the current rate.

Bria Product Shot API

Model summary

Production guidance

Best suited for

Request parameters

Example requests

Getting the result

FAQ

Can I send prompt and reference_image_url together?

Does the prompt have to be in English?

When does optimize_description apply?

How can the product be placed?

When can I use original_quality?

What format and size is the output?

What does fast change?

What product images work?

How is it billed?

Next steps