Growth Studio OpenAPI接入文档 · Product Videos
根据商品信息创建视频。素材准备见图片与系统模特(上传图片),系统模特见图片与系统模特(查询系统模特);受理后使用返回的 video_id 视频状态与结果查询(查询视频详情),并按视频状态与结果查询(视频轮询建议)获取结果。
POST /openapi/v1/videos
Content-Type: application/json
Authorization: Bearer <API_KEY>
创建视频是异步操作。返回 202 Accepted 表示任务已成功创建并进入处理流程,不表示视频已经生成完成。
请将 product.images[].url 替换为图片上传接口实际返回的 URL:
curl --request POST \
"${BASE_URL}/openapi/v1/videos" \
--header "Authorization: Bearer ${API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
"product": {
"title": "Lightweight Running Shoes",
"description": "Breathable running shoes suitable for daily training.",
"brand": "Example Brand",
"price": {
"amount": "89.99",
"currency": "USD"
},
"images": [
{
"url": "https://media.pixverse.ai/marketing_hub_website/openapi_video_inputs/uploads/22/11/product.webp"
}
]
},
"video": {
"aspect_ratio": "9:16",
"duration_seconds": 30,
"resolution": "1080p",
"language": "en-US",
"voiceover": true,
"captions": true,
"background_music": true,
"avatar": {
"mode": "auto"
}
},
"metadata": {
"order_id": "order_123456",
"campaign_id": "campaign_001"
}
}'
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
product |
object | 是 | 商品信息 |
product.title |
string | 是 | 商品标题,最长 255 个字符 |
product.description |
string | 否 | 商品描述,最长 5120 个字符 |
product.brand |
string | 否 | 品牌,最长 255 个字符 |
product.price |
object | 否 | 商品展示价格,不是视频生成费用 |
product.price.amount |
string | 条件必填 | 传入 price 时必填,例如 89.99 |
product.price.currency |
string | 条件必填 | 传入 price 时必填,三位币种代码,例如 USD |
product.images |
array | 否 | 商品图片,没有source_url时最少 1 张、最多 6 张;第一张作为主图 |
product.images[].url |
string | 否 | 图片上传接口返回的完整内部 CDN URL |
product.source_url |
string | 否 | 用来抓取商品信息和图片的商品页面URL |
图片 URL 规则:
POST /openapi/v1/image/upload 返回的 URL。INVALID_REQUEST。| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
video |
object | 是 | 视频生成配置 |
video.aspect_ratio |
string | 是 | 视频画幅,例如 9:16 |
video.duration_seconds |
integer | 是 | 只支持 15、30、45、60 |
video.resolution |
string | 是 | 只支持 480p、720p、1080p,大小写不敏感 |
video.language |
string | 是 | 语言代码,推荐使用 en-US 格式 |
video.voiceover |
boolean | 是 | 是否启用旁白 |
video.captions |
boolean | 是 | 是否启用字幕 |
video.background_music |
boolean | 是 | 是否启用背景音乐 |
video.avatar |
object | 是 | 模特配置 |
video.avatar.mode |
string | 是 | auto、custom 或 disabled |
video.avatar.url |
string | 条件必填 | mode=custom 时必填,必须是图片上传接口返回的 URL 或 系统模特列表返回的合法平台 CDN URL |
video.creative_ad_clone |
string | 否 | 用户提供创意脚本 |
video.subtitles_size_mode |
string | 否 | 用于设置生成视频中的字幕字号模式;使用较大的字幕字号:large |
video.folder_id |
string | 否 | 调用 GET /openapi/v1/folders 获取;必须是当前 API Key 绑定的 workspace 中存在且未删除的文件夹,否则返回 FOLDER_NOT_FOUND。 |
Avatar 模式:
| mode | 说明 |
|---|---|
auto |
系统自动选择模特,不传 avatar.url |
custom |
使用指定模特,必须传 avatar.url |
disabled |
不使用模特,不传 avatar.url |
自定义模特示例: