Growth Studio OpenAPI接入文档 · Product Videos

根据商品信息创建视频。素材准备见图片与系统模特(上传图片),系统模特见图片与系统模特(查询系统模特);受理后使用返回的 video_id 视频状态与结果查询(查询视频详情),并按视频状态与结果查询(视频轮询建议)获取结果。

请求

POST /openapi/v1/videos
Content-Type: application/json
Authorization: Bearer <API_KEY>

创建视频是异步操作。返回 202 Accepted 表示任务已成功创建并进入处理流程,不表示视频已经生成完成。

cURL

请将 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 规则:

视频参数

字段 类型 必填 说明
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

自定义模特示例: