教程
如何通过 hiapi API 使用 bria-product-shot：curl、Python 和一次可用的请求
2026年11月3日
bria-product-shot 接收一张产品照片，返回一张将产品置于不同场景中的新图像。你可以用英文描述场景，也可以提供一张参考图像，让它遵循该图像的背景风格。本指南展示一个在 hiapi 上端到端运行过的请求，以及决定请求是否被接受的参数规则。
你需要从仪表盘的 API Keys 页面 获取 hiapi API 密钥，以及一个可公开访问的产品照片 URL（JPEG、PNG 或 WEBP，最大 12 MB）。
最小可用示例（curl）
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": {
"image_url": "https://your-cdn.example.com/serum-bottle.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"
}
}'
创建调用会立即返回一个任务 ID：
{"code":200,"data":{"taskId":"tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW"},"message":"success"}
轮询 GET /v1/tasks/<taskId>，直到 data.status 为 success 或 fail。完成后的响应如下所示（输出主机名已缩短）：
{
"code": 200,
"data": {
"model": "bria-product-shot",
"status": "success",
"storage": "temp",
"taskId": "tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW",
"output": [{"artifactId": "287064", "type": "image", "expireAt": 1793325686,
"url": "https://temp.hiapi.ai/.../...-0.png"}]
},
"message": "success"
}
Python 版本
import os, time, requests
API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
def product_shot(image_url: str, scene: str, position: str = "bottom_center") -> bytes:
r = requests.post(API, headers=HEADERS, json={
"model": "bria-product-shot",
"input": {
"image_url": image_url,
"prompt": scene,
"placement_type": "manual_placement",
"manual_placement_selection": position,
},
}, timeout=30)
r.raise_for_status()
task_id = r.json()["data"]["taskId"]
for _ in range(60):
d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
if d["status"] == "success":
# output URLs expire (about 7 days): download immediately
return requests.get(d["output"][0]["url"], timeout=60).content
if d["status"] == "fail":
raise RuntimeError(d)
time.sleep(4)
raise TimeoutError(task_id)
open("shot.png", "wb").write(product_shot(
"https://your-cdn.example.com/serum-bottle.png",
"On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
))
关键参数
| 字段 | 说明 |
|---|---|
image_url |
必填。产品照片的公开 http(s) URL。 |
prompt |
英文场景描述，1–1000 个字符。 |
reference_image_url |
场景参考图像。使用此参数或 prompt，二者只能选其一，绝不能同时使用。 |
placement_type |
manual_placement（默认）将产品放置在预设位置；original 保持其在照片中的位置。 |
manual_placement_selection |
bottom_center（默认）、upper_left、upper_right、bottom_left、bottom_right、right_center、left_center、upper_center、center_vertical、center_horizontal。仅在使用 manual_placement 时有效。 |
original_quality |
仅在使用 original 时有效：保留输入尺寸，而不是缩放到约 1 MP。 |
fast |
默认 true。关闭以使用标准模型；价格相同。 |
optimize_description |
默认 true。扩展场景文本；仅在使用 prompt 时有效，不能与参考图像一起使用。 |
该 schema 是封闭的（additionalProperties: false），并且有跨字段规则，因此 prompt 加 reference_image_url，或 original 加预设位置等组合都是无效请求。
测试记录与注意事项
针对实时 API 运行的内容：
- 使用上述请求进行了一次真实生成，
fast保持默认值。任务经历了handling和archiving，从创建到完成约 26 秒后达到success。 - 对于方形输入，输出为 1024×1024 的 PNG（约 1 MB），这与模型页面的说明一致：对于方形输入，预设位置按 1024×1024 测量。
- 一个故意设置的错误值
"manual_placement_selection": "middle"在创建时被拒绝，返回 HTTP 400 和error_code: INVALID_REQUEST。错误消息列出了全部十个允许的位置，因此你可以直接将其展示给用户，而不必等待任务失败。
实用提示：
- 立即下载输出。 每个输出都带有一个
expireAt时间戳（完成后的 Unix 时间，约七天）；请将图像存储到你自己的存储中。 - 按图像固定计价。 根据模型页面，场景文本与参考图像、放置位置和快速模式都不会改变价格。请查看 定价页面 上的当前数字，而不是硬编码这些数字。
- 本指南只运行了一次生成，因此页面不对不同产品类别的质量作出任何声明。在批量使用前，请先测试你自己的商品目录图像。
生产环境建议
- 创建任务，存储
taskId，并在遇到临时网络错误时重试几次进行轮询。重新轮询已保存的 id，而不是创建新任务，因为新任务会再次计费。 - 对于队列，在客户端根据上述十个值验证
manual_placement_selection，这样错误输入永远不会到达 API。
相关页面
- Bria Product Shot 模型页面：实时定价、输入表单和演练场。
- Bria Eraser 模型页面：使用蒙版移除对象，这与将产品放入新场景是不同的任务。
- 浏览所有图像模型
- 851-labs 背景移除 API 指南：如果你的源照片背景杂乱，请先抠出产品。
- 如何使用 FLUX.2 图像到图像 API
常见问题
我可以使用参考图像代替文本提示吗？
可以。发送 reference_image_url 并省略 prompt。不要同时发送两者，也不要将 optimize_description 与参考图像一起发送。
一次调用返回多少张图像？ 一张。模型页面说明每次运行输出一张图像。
产品会保持在我的照片中的位置吗？
只有在 placement_type: "original" 时才会。默认的 manual_placement 会将其重新定位到所选的预设位置。
