Growth Studio OpenAPI Integration Guide · 批量裂变

Generate variants of one source video by specifying an avatar, scene, and target language for each entry. Each item in videos describes one target configuration; the server does not expand combinations automatically.

Request and Source Requirements

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

The source must belong to the API key's account and workspace and must not be deleted. Professional creation and viral clone videos created through either the website or OpenAPI are supported. Template videos, variation videos, and imported finished videos are not valid sources.

The source must have a valid script. Its model must still be available to OpenAPI, support reference-video generation, and support the inherited specifications. The source need not have finished generating: variations use its script and reference assets, not its final video.

Every target configuration needs at least one candidate image from the source or a new avatar/scene image. When the source has no reference images, every entry must use image mode for at least one of avatar or scene. Model and output specifications are inherited and cannot be overridden. Avatar replacement applies to the first on-screen person in the source script.

Obtain website-created source IDs from the website. The Video Status and Results still return only OpenAPI-created videos for the current account and workspace; accepting website sources does not expand their scope.

Parameters and Modes

Field Type Required Description
source_video_id string Yes One source video per request
videos array Yes 1–20 entries, checked before deduplication
videos[].avatar object Yes Avatar configuration for this entry
videos[].scene object Yes Scene configuration for this entry
videos[].language object Yes Target language object
videos[].language.code string Yes A full code from Batch Video Variations (Target Languages)

Both avatar and scene use this structure:

mode Additional fields Behavior
keep None Retain the source setting
auto None Design replacement content from the source script and target language
text Required nonempty description Replace according to the description
image Required image_url; optional description Replace using the reference image and optional instructions

Mode values are lowercase. Nonempty image/description fields with keep or auto, or a nonempty image field with text, cause 400 INVALID_REQUEST.

image_url must be a valid platform CDN URL, such as the url returned by Images and System Avatars. External image URLs and object_key values are not accepted. text and auto do not require a separately generated avatar or scene image. Descriptions are trimmed; text.description must remain nonempty. There is no separate description length limit, but the JSON body must not exceed 1 MiB.

Unknown fields are rejected. Do not send combination rules, generated scripts, model, duration, resolution, aspect ratio, or catalog version.

cURL and Deduplication

Entries 0 and 2 below are identical. Replace the source ID with a valid source that already has reference images.

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"}
      }
    ]
  }'

HTTP 202 Accepted creates only two unique videos:

{
  "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"
}