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 编码 | 说明 |
|---|---|
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 码点。