Bria Product Shot API
POST Base URL:
https://api.hiapi.ai /v1/tasks 图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。
模型概览
| 模型名称 | bria-product-shot |
|---|---|
| 类型 | 图像编辑（商品场景图） |
| 接口 | POST /v1/tasks |
| 价格 | 见 HiAPI 定价 |
Bria Product Shot：上传商品图，用英文场景描述或一张场景参考图（二选一）生成新背景，可选预设位置或保持原位，适合电商主图、广告图与社媒素材。
生产建议
生产环境建议
- prompt 与 reference_image_url 二选一：同时传或都不传都会返回参数错误；optimize_description 只配合 prompt，manual_placement_selection 与 original_quality 分别只配合 manual_placement 与 original。
- 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
- 产物 URL 有有效期，拿到结果后请及时转存到自己的存储。
适用场景
电商主图
把白底商品图放进有质感的场景，统一放在画布底部居中。
image_urlpromptmanual_placement_selection按参考风格出图
上传一张氛围图，让商品场景跟随它的背景风格。
reference_image_url保留构图换背景
商品位置和比例沿用原图，只替换背景。
placement_typeoriginal_quality请求参数
model string 必填 固定填 bria-product-shot。
input object 必填 业务参数对象；prompt 与 reference_image_url 必须且只能传一个。
image_url string 必填 商品图公网 URL（http/https），支持 JPEG、PNG、WEBP，最大 12 MB。
prompt string 可选 用英文描述新场景或背景，1–1000 个字符；未传 reference_image_url 时必填，两者不能同时传。
reference_image_url string 可选 场景参考图 URL，按它的场景或背景风格生成；未传 prompt 时必填，两者不能同时传。
optimize_description boolean 可选 自动扩写场景描述；只配合 prompt 使用，传 reference_image_url 时不要传。
fast boolean 可选 快速模式；设为 false 使用标准模式，价格相同。
placement_type enum 可选 manual_placement：放在预设位置（场景描述或参考图均可；方图输入实测输出 1024×1024）；original：保持商品在原图中的位置并沿用原图尺寸。
manual_placement_selection enum 可选 预设位置；只配合 manual_placement 使用，original 时不要传。
original_quality boolean 可选 按原图尺寸输出，关闭时缩放到约 100 万像素；只在 placement_type 为 original 时可传。
callback object 可选 可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务。
url string 必填 传入 callback 时必填；接收任务终态通知的 HTTPS 地址。
when enum 可选 回调触发时机；当前建议固定为 final。
用例示例
英文场景描述 + 预设位置
黄金任务：用一句英文描述台面、光线和陪衬，商品放在底部居中，方图输入实测输出 1024×1024。
请求体
{
"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"
}
}场景参考图 + 预设位置
不写 prompt，按参考图的场景生成背景：耳机被放到参考图里的水泥展台上，底部居中，方图输入实测输出 1024×1024。
请求体
{
"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_quality 后沿用原图尺寸（实测 1168×880）；此时不传 manual_placement_selection。
请求体
{
"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
}
}获取结果
- 提交成功后立即返回 taskId，不等待生成完成。
- 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
- status=success 后，从返回的 output 中取图片地址并下载。
- 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。
常见问题
prompt 和 reference_image_url 能一起传吗？
不能，必须且只能传一个；同时传或都不传都会返回参数错误。
prompt 要用英文吗？
是。用英文描述新场景或背景，最多 1000 个字符。
optimize_description 什么时候生效？
只在传 prompt 时生效，默认开启；传 reference_image_url 时不要带这个参数。
商品摆放有哪几种方式？
manual_placement（默认；场景描述或参考图均可）放在预设位置，默认 bottom_center，方图输入实测输出 1024×1024；original 保持商品在原图中的位置。
original_quality 什么时候能用？
只在 placement_type 为 original 时可传：true 按原图尺寸输出，false 缩放到约 100 万像素。
输出是什么格式和尺寸？
每次输出 1 张 PNG：预设位置（场景描述或参考图均可）方图输入实测 1024×1024；placement_type 为 original 且 original_quality 为 true 时沿用原图尺寸（实测输入 1168×880，输出也是 1168×880）。
fast 有什么影响？
默认 true，出图更快；设为 false 使用标准模式，价格相同。
商品图有什么要求？
JPEG、PNG、WEBP，最大 12 MB，通过公网可访问的 http/https 地址传入；主体清晰、边缘完整效果更好。
怎么计费？
按输出图片张数计费，每次请求返回 1 张；当前单价见实时价格页。