Growth Studio OpenAPI接入文档 · Template Creation

选择平台提供的模板,提交商品信息和模板参数,异步生成一条商品视频。模板目录提供展示信息、输入表单声明和计价规则;调用方可据此在自己的产品中展示模板、收集输入并展示价格。

新接入使用以下接口。所有请求均需 Authorization: Bearer <API_KEY>,API Key 绑定账号和工作空间;请求无需传账号或工作空间 ID。

方法 路径 用途
GET /openapi/v1/template/tags 获取筛选标签组及标签
GET /openapi/v1/template/list 筛选、分页查询模板及计价规则
POST /openapi/v1/template/generate 使用一个模板生成一条视频
GET /openapi/v1/videos/{video_id} 查询任务状态和生成结果
GET /openapi/v1/videos?kind=template 查询模板视频历史

接入顺序:查询标签与模板 → 展示模板并收集输入 → 按 pricing 计算价格 → 提交生成 → 使用 video_id 轮询结果。当前没有模板详情接口、报价接口或模板生成 webhook。

查询模板列表

GET /openapi/v1/template/list
Authorization: Bearer <API_KEY>
查询参数 类型 必填 默认值 说明
type string 否 不限制 单个模板类型编码,例如 bfcm_2026
category string 否 不限制 单个品类编码
video_style string 否 不限制 单个视频风格编码
tag_ids string 否 不限制 逗号分隔的正整数标签 ID,例如 11,12;同一标签组内 OR,不同标签组间 AND
keyword string 否 不限制 对模板展示配置全文做子串匹配,可能同时命中各语言文案、URL 和 JSON 字段名
page integer 否 1 页码,从 1 开始;传 0 使用默认值,负数无效
page_size integer 否 20 每页 1~100 条;传 0 使用默认值

未传筛选条件时返回全部启用模板的分页结果。类型、品类和风格是独立字段,不是标签组;以实时目录中的编码为准。当前不支持 template_id 查询参数。

当前支持的 type

type 编码 说明
daily 日常、常规商品视频模板
bfcm_2026 2026 年黑色星期五与网络星期一促销模板(Black Friday / Cyber Monday)

type 是列表筛选条件,一次传一个编码,例如 ?type=daily 或 ?type=bfcm_2026;省略时查询所有类型。模板类型随目录更新,请以当前环境分页查询得到的 templates[].type 为准。无匹配模板时返回 templates=[]、total=0。创建时传所选模板的 template_id,无需传 type。

export BASE_URL='https://growth-api.pixverse.ai'
export API_KEY='mh_live_REPLACE_WITH_PRODUCTION_API_KEY'

curl --get "$BASE_URL/openapi/v1/template/list" \
  --header "Authorization: Bearer $API_KEY" \
  --data-urlencode 'type=bfcm_2026' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'

成功返回 200 OK,响应带 Cache-Control: no-store 和 X-Request-Id。以下 ID、素材 URL 和价格均为格式示例,不代表实时可用模板或报价。

{
  "templates": [
    {
      "id": 202611090001,
      "type": "bfcm_2026",
      "category": "generic",
      "video_style": "ugc_style",
      "layout": {
        "default": "en",
        "name": {"en": "Black Friday Offer", "zh": "黑五优惠"},
        "description": {"en": "Present a limited-time product offer.", "zh": "展示商品限时优惠。"},
        "cover_url": {"en": "https://media.pixverse.ai/templates/example/cover.jpg", "zh": "https://media.pixverse.ai/templates/example/cover-zh.jpg"},
        "video_url": {"en": "https://media.pixverse.ai/templates/example/preview.mp4", "zh": "https://media.pixverse.ai/templates/example/preview-zh.mp4"},
        "duration": {"default": 15},
        "aspect_ratio": {"default": "9:16", "options": ["9:16", "4:5", "1:1", "16:9"]},
        "resolution": {"default": "720p", "options": ["720p", "1080p"]},
        "template_params": [
          {
            "key": "offer_details",
            "ui_type": "discount_text_input",
            "display_name": {"en": "Deal details", "zh": "优惠信息"},
            "required": true,
            "max_length": 300,
            "placeholder": {"en": "Price, promo code and end date", "zh": "填写价格、优惠码和截止日期"}
          }
        ]
      },
      "tag_ids": [11],
      "pricing": {
        "expression": {"if": [{"===": [{"var": "quality"}, "1080p"]}, 1260, 490]},
        "fixed_params": {}
      }
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "request_id": "list-templates-001"
}
响应字段 类型 说明
templates array 当前页的启用模板,按创建时间倒序、ID 倒序;无匹配结果时为 []
templates[].id integer 生成请求的 template_id;使用实际返回的数字,配置中存在的 0 也是合法 ID
templates[].type / category / video_style string 分类编码;品类和风格可能为空字符串
templates[].layout object 展示配置原文,见下文
templates[].tag_ids integer[] 模板绑定的可见标签 ID;无标签时为 []
templates[].pricing object / null 计价规则及固定参数;null 表示计价配置不可用,此时不要提供生成入口
total integer 当前筛选条件下的模板总数
page / page_size integer 实际页码和每页条数;需要全部模板时逐页读取
request_id string 请求追踪 ID

展示模板与收集输入

layout 是 JSON 对象,字段可随模板配置增减。服务端不会按部署语言拆分;调用方应兼容额外字段和可选字段。

配置 调用方处理方式
name、description 通常为 {en, zh},中文界面选择 zh,英文界面选择 en
cover_url、video_url 通常为 {en, zh},选取对应语言的封面、预览视频
duration、aspect_ratio、resolution {default, options?},不分语言;用于展示默认规格与可选值,并校验用户选择
template_params 按数组顺序展示该模板需要的额外输入;每项的 key 对应生成请求中的同名参数

template_params 声明字段:key、ui_type、可选的 display_name、placeholder、required、max_length。目前约定 text_input 为通用多行文本,discount_text_input 为优惠信息文本;display_name、placeholder 可以是字符串或多语言对象。required 缺省为 false;max_length 未配置时,前端约定使用 500 个 Unicode 码点。