Growth Studio OpenAPI接入文档 · Batch Video Variations
基于一个源视频,逐条指定目标视频的人物、场景和语言,生成多条变体。videos[] 的一项代表一条目标配置;服务端不会额外展开人物、场景和语言的组合。
POST /openapi/v1/variation/videos/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json
源视频须属于当前 API Key 对应账号和工作空间,且未删除。允许使用网页端或开放平台创建的专业创作、爆款复刻视频,不限制创建入口;模板视频、裂变视频和上传成片不能作为来源。
来源须有有效脚本,源模型当前仍对 OpenAPI 开放、支持参考生视频,且支持继承的规格。来源无需已生成成功,因为裂变使用源脚本和参考素材,不依赖成片。
每条目标配置至少有一张候选图片,可以来自源视频或该条新增的人物/场景图片。源视频无参考图时,每条必须至少提供一个 image 模式选择。本接口仅指定人物、场景、目标语言,模型与其他生成规格沿用来源,不能自行覆盖。人物替换针对源脚本中第一个出镜人物。
网页来源 ID 需从网页端获取。视频状态与结果查询仍只返回当前账号和工作空间中由开放平台创建的视频;允许网页视频作为裂变来源不会扩大这些查询接口的范围。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
source_video_id |
string | 是 | 一个请求引用一个源视频 |
videos |
array | 是 | 1~20 项,数量在去重前检查 |
videos[].avatar |
object | 是 | 本条人物替换配置 |
videos[].scene |
object | 是 | 本条场景替换配置 |
videos[].language |
object | 是 | 目标语言对象 |
videos[].language.code |
string | 是 | 批量裂变(目标语言)列出的完整语言代码 |
avatar 与 scene 采用相同结构:
mode |
可以携带的其他字段 | 行为 |
|---|---|---|
keep |
无 | 保留来源设定 |
auto |
无 | 根据源脚本与目标语言设计替换内容 |
text |
必填非空 description |
按文字描述替换 |
image |
必填 image_url,可选 description |
按参考图片替换,描述作为补充要求 |
模式枚举使用小写。当前接口会校验字段冲突:keep / auto 携带非空图片或描述,或 text 携带非空图片,均返回 400 INVALID_REQUEST。
image_url 必须为合法平台 CDN URL,例如图片上传接口返回的 url;不接受外站图片链接或 object_key。text 与 auto 不要求提前生成对应的人物/场景图。描述会去掉首尾空白,text.description 不得为空;不设描述单独字符上限,但 JSON 请求体最多 1 MiB。
未知字段会被拒绝,不需要提交组合规则、生成脚本、模型、时长、分辨率、比例或目录版本。
以下三项中第 0、2 项相同。替换为合格源视频 ID;此示例要求源视频已有参考图。
curl --request POST \
"${BASE_URL}/openapi/v1/variation/videos/generations" \
--header "Authorization: Bearer ${API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
"source_video_id": "123456789",
"videos": [
{
"avatar": {"mode": "keep"},
"scene": {"mode": "text", "description": "A bright family kitchen"},
"language": {"code": "en-US"}
},
{
"avatar": {"mode": "keep"},
"scene": {"mode": "auto"},
"language": {"code": "ja-JP"}
},
{
"avatar": {"mode": "keep"},
"scene": {"mode": "text", "description": "A bright family kitchen"},
"language": {"code": "en-US"}
}
]
}'
成功返回 202 Accepted,实际只创建两条视频:
{
"ledger_source_id": "888888888",
"videos": [
{"video_id": "987654321", "status": "processing", "input_indices": [0, 2]},
{"video_id": "987654322", "status": "processing", "input_indices": [1]}
],
"request_id": "create-variation-001"
}