Elements & Voices (Element / Voice)

The v3 series supports elements (custom subjects) in image-to-video; the v2.6 / omni series supports voices (custom dubbing). Create elements and voices first via two management models (async tasks, free of charge), then reference them in generation requests through metadata.contents.

Create and Query

Step 1: create and query — call the management model with the chat format; business parameters all live in metadata (the messages content plays no business role), and the response content is the raw upstream JSON string:

FieldTypeRequiredDescription
modelstringYesManagement model: kling-voice-manage (voice) or kling-element-manage (element)
messagesarrayYesChat message array; content is arbitrary, not used for business
metadata.opstringYesOperation: create / query / delete
metadata.voice_namestringRequired for createVoice name (≤ 20 chars)
metadata.voice_urlstringEitherPublic direct link of the reference audio, ≥ 5 seconds
metadata.video_idstringEitherID of a generated video containing audio (alternative to voice_url)
metadata.element_namestringRequired for createElement name (≤ 20 chars), referenced in prompt as @element_name
metadata.element_descriptionstringRequired for createElement description (≤ 100 chars)
metadata.frontal_imagestringCond. requiredFrontal photo URL (jpg/jpeg/png; re-hosted upstream)
metadata.refer_imagesstring[]NoReference image URLs, 1~3 in practice; defaults to [frontal_image]
metadata.modelstringNoModel the element applies to, default kling-video-v3
metadata.reference_typestringNoReference type, default image_refer
metadata.tag_liststring[]NoTag list
metadata.external_task_idstringNoCustom task ID (sent on create, echoed on query)
metadata.task_idstringRequired for queryTask ID returned by create
metadata.voice_id / metadata.element_idstringRequired for deleteVoice / element ID to delete

Management operations are free (upstream quota is constantly "0").

cURL
Python
Node.js
# Create a voice: voice_name required; voice_url (public link, >= 5 seconds)
# or video_id (a generated video containing audio), either one
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-voice-manage",
    "messages": [{"role": "user", "content": "create"}],
    "metadata": {
      "op": "create",
      "voice_name": "小美",
      "voice_url": "https://cos.example.com/reference.wav"
    }
  }'
# data.task_id inside the response content is used for polling; creation is free
# Create an element: element_name (<= 20 chars), element_description (<= 100 chars),
# frontal_image (frontal photo URL) required
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-element-manage",
    "messages": [{"role": "user", "content": "create"}],
    "metadata": {
      "op": "create",
      "element_name": "小美",
      "element_description": "一位年轻女性的正面肖像",
      "frontal_image": "https://cos.example.com/portrait.jpg"
    }
  }'
# data.task_id inside the response content is used for polling; creation is free
# Poll (same for voice/element): op=query with task_id, every 2~3 seconds
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-voice-manage",
    "messages": [{"role": "user", "content": "query"}],
    "metadata": { "op": "query", "task_id": "929463831049801748" }
  }'
# Once task_status = succeed: voice_id at content's data.task_result.voices[0].voice_id
# element_id at data.task_result.elements[0].element_id
# Delete (synchronous): op=delete with voice_id / element_id
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-voice-manage",
    "messages": [{"role": "user", "content": "delete"}],
    "metadata": { "op": "delete", "voice_id": "929463831049801748" }
  }'
NOTE

Management operations are free; the platform offers no element / voice listing API, so keep element_id / voice_id safe. Deleted assets can no longer be referenced. Preview links are temporary — download promptly.

Reference in Generation Requests

Step 2: reference in generation requests — asset references live in the metadata.contents array, one item per asset:

contents itemAssetHow to reference in prompt
{"type":"element","element_id":"…"}1 element@element_name (the element_name set at creation)
{"type":"voice","voice_id":"…","id":"narr"}1 voice@index (the id of the contents item, a label you pick, e.g. narr, v1)

Rules:

  • Limits: at most 3 elements (v3 / v3-omni / o1 only) and 2 voices (v2.6 / v3 / omni series).
  • Requests referencing a voice must carry audio (native for v2.6 / v3, native / original for omni / o1): a voice needs sound; silent videos do not support voices — violations get a 400 before submission.
  • Use @element_name for elements and @index for voices; do not mix the two. Avoid element names that are prefixes of one another (e.g. @Zhang vs @ZhangSan).

Single element / voice:

cURL
Python
Node.js
# v2.6 image-to-video + voice: reference via @index in prompt, audio must be native
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v2.6",
    "prompt": "@narr 对着镜头微笑着说:你好,欢迎体验。",
    "image": "https://example.com/face.png",
    "audio": "native",
    "metadata": {
      "contents": [{"type": "voice", "voice_id": "929463831049801748", "id": "narr"}]
    }
  }'
# v3 image-to-video + element: reference via @element_name (the element_name set at creation)
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v3",
    "prompt": "@小美 自然转头并对镜头微笑,镜头缓慢推近",
    "image": "https://example.com/face.png",
    "duration": 3,
    "metadata": {
      "contents": [{"type": "element", "element_id": "321601259306151"}]
    }
  }'

Multiple Elements / Voices

Multiple elements / voices: add more items to the contents array — a two-voice contents (v2.6 image-to-video, two characters talking):

"contents": [
  {"type": "voice", "voice_id": "929463831049801748", "id": "narr"},
  {"type": "voice", "voice_id": "929477316815110196", "id": "guest"}
]

Use @narr and @guest in the prompt to assign lines:

cURL
Python
Node.js
# Two-voice dialogue (v2.6 image-to-video)
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v2.6",
    "prompt": "@narr 开场说:大家好。随后 @guest 回答:很高兴见到你。",
    "image": "https://example.com/two-people.png",
    "audio": "native",
    "metadata": {
      "contents": [
        {"type": "voice", "voice_id": "929463831049801748", "id": "narr"},
        {"type": "voice", "voice_id": "929477316815110196", "id": "guest"}
      ]
    }
  }'
# Two elements in one scene (v3 image-to-video): one element item each in contents
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v3",
    "prompt": "@小美 和 @小明 面对面握手,镜头环绕",
    "image": "https://example.com/scene.png",
    "duration": 5,
    "metadata": {
      "contents": [
        {"type": "element", "element_id": "321601259306151"},
        {"type": "element", "element_id": "321667483392215"}
      ]
    }
  }'

Direct Assets & Video Editing

Besides elements / voices, metadata.contents accepts direct asset items, and metadata.options carries task options:

PositionDescription
contents {"type":"base_video","url":"…"}Base video to edit (omni editing scenario); feature_video / refer_image also supported
metadata.options.external_task_idCustom task ID (equivalent to top-level external_task_id)
metadata.options.watermark_info{"enabled": true} turns on the "AI-generated" watermark (off by default)

Most common scenario — omni editing of an existing video (base video + keep original audio):

cURL
Python
Node.js
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/text2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-v3-omni",
    "prompt": "把画面整体色调调成黄昏暖色,其他内容保持不变",
    "size": "1280x720",
    "audio": "original",
    "duration": 5,
    "metadata": {
      "contents": [{"type": "base_video", "url": "https://cos.example.com/input.mp4"}]
    }
  }'
NOTE

When editing videos (base_video / feature_video), pass size explicitly (e.g. 1280x720, matching the base video): without it the output defaults to 16:9 instead of following the source. audio: "original" requires the reference video to carry an audio track; text-to-video output on this platform is silent, so prefer source material with an audio track for editing.

WARNING

Asset URLs must be publicly downloadable direct links (images jpg/jpeg/png ≤ 50MB, both dimensions ≥ 300px; audio ≥ 5 seconds; video mp4/mov ≤ 200MB). Direct links from reputable sites generally work (your own domains, mainstream object storage, etc.), but some sites fail upstream fetches (w3school.com.cn and the overseas image host wikimedia are known to fail; failed image/audio fetches are not charged). If you see a "fetch failed" error, switch to another source. Note in particular: when video assets such as base_video fail to fetch, the task does not error and still bills at the editing price, but the output has nothing to do with the base video — verify the link is reachable before editing (output links on this platform expire in about 45 minutes and cannot be reused as base videos). Prefer direct links on your own domain, links produced by this platform (most stable), or Base64 input.