• 简体中文
  • 元素与音色(Element / Voice)

    v3 系图生视频可引用元素(自定义主体),v2.6 / omni 系可引用音色(自定义配音)。元素与音色先通过两个管理模型创建(异步任务、免费),再在生成请求的 metadata.contents 里引用。

    创建并查询

    第一步:创建并查询——用 chat 格式调用管理模型,业务参数全部放在 metadata(messages 内容不参与业务),响应的 content 是上游原始 JSON 字符串:

    字段类型必填说明
    modelstring是管理模型名:kling-voice-manage(音色)或 kling-element-manage(元素)
    messagesarray是chat 消息数组,内容任意,不参与业务,传固定值即可
    metadata.opstring是操作类型:create(创建)/ query(查询)/ delete(删除)
    metadata.voice_namestring创建音色必填音色名称(≤20 字)
    metadata.voice_urlstring二选一参考音频公网直链,时长 ≥ 5 秒
    metadata.video_idstring二选一含音频的已生成视频 ID(与 voice_url 二选一)
    metadata.element_namestring创建元素必填元素名称(≤20 字),@元素名 在 prompt 中引用
    metadata.element_descriptionstring创建元素必填元素描述(≤100 字)
    metadata.frontal_imagestring创建元素条件必填元素正面照 URL(jpg/jpeg/png,上游会转存)
    metadata.refer_imagesstring[]否参考图 URL 数组,实测 1~3 张;缺省自动补为 [frontal_image]
    metadata.modelstring否元素适用的模型,默认 kling-video-v3
    metadata.reference_typestring否参考类型,默认 image_refer
    metadata.tag_liststring[]否标签列表
    metadata.external_task_idstring否自定义任务 ID(创建时传入,查询可回显)
    metadata.task_idstring查询必填创建返回的任务 ID
    metadata.voice_id / metadata.element_idstring删除必填要删除的音色/元素 ID

    管理操作免费(上游实测 quota 恒 "0")。

    cURL
    Python
    Node.js
    # 创建音色:voice_name 必填;voice_url(参考音频公网链接,时长 ≥ 5 秒)
    # 或 video_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": "create"}],
        "metadata": {
          "op": "create",
          "voice_name": "小美",
          "voice_url": "https://cos.example.com/reference.wav"
        }
      }'
    # 响应 content 里的 data.task_id 用于查询;创建免费
    # 创建元素:element_name(≤20 字)、element_description(≤100 字)、frontal_image(正面照 URL)必填
    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"
        }
      }'
    # 响应 content 里的 data.task_id 用于查询;创建免费
    # 轮询(音色/元素通用):op 换成 query(传 task_id),建议 2~3 秒一次
    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" }
      }'
    # task_status = succeed 后,voice_id 在 content 的 data.task_result.voices[0].voice_id
    # element_id 在 data.task_result.elements[0].element_id
    # 删除(同步返回):op 换成 delete(传 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

    管理操作免费;平台不提供元素 / 音色列表接口,请自行保存 element_id / voice_id;删除后不可再引用;试听地址为临时链接,请及时下载转存。

    在生成请求中引用

    第二步:在生成请求中引用——素材引用统一写在 metadata.contents 数组里,一项对应一个素材:

    contents 项对应素材prompt 里怎么引用
    {"type":"element","element_id":"…"}1 个元素@元素名(即创建时的 element_name)
    {"type":"voice","voice_id":"…","id":"narr"}1 个音色@索引(即 contents 项的 id,自取标签,如 narr、v1)

    规则:

    • 数量上限:元素 ≤ 3(仅 v3 / v3-omni / o1)、音色 ≤ 2(v2.6 / v3 / omni 系)。
    • 引用音色时必须带 audio(v2.6 / v3 用 native,omni / o1 可 native / original):音色要出声,无声视频不支持音色,不满足会在提交前返回 400 提示补上。
    • 元素 prompt 用 @元素名,音色 prompt 用 @索引,两套引用不要混用;多个元素名避免互为前缀(如 @Zhang 与 @ZhangSan)。

    单元素 / 单音色:

    cURL
    Python
    Node.js
    # v2.6 图生视频 + 音色:prompt 用 @索引 引用音色说话,audio 须带 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 图生视频 + 元素:prompt 用 @元素名 引用(即创建时的 element_name)
    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"}]
        }
      }'

    多元素 / 多音色

    多元素 / 多音色:contents 数组多写一项即可——一段双音色的 contents(v2.6 图生视频,两个人物对话):

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

    prompt 里用 @narr、@guest 分别指定谁说哪句台词:

    cURL
    Python
    Node.js
    # 双音色对话(v2.6 图生视频)
    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"}
          ]
        }
      }'
    # 双元素同框(v3 图生视频):contents 里多写一个元素项,prompt 用 @元素名 指定谁出场
    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"}
          ]
        }
      }'

    素材直通与视频编辑

    metadata.contents 除了元素 / 音色,也接受直通素材项,metadata.options 承接任务选项:

    位置说明
    contents {"type":"base_video","url":"…"}待编辑的底视频(omni 编辑场景),同类还支持 feature_video / refer_image
    metadata.options.external_task_id自定义任务 ID(等价顶层 external_task_id)
    metadata.options.watermark_info{"enabled": true} 开启「AI生成」水印(不传默认无水印)

    最常用场景——omni 编辑一段已有视频(底视频 + 保留原声):

    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

    编辑视频(base_video / feature_video)时请显式传 size 指定输出画幅(如 1280x720,与底视频一致):不传时输出画幅默认 16:9 而非跟随原视频。audio: "original"(保留原声)要求参考视频自带音轨;本站文生视频默认无声,做二次编辑时建议选用带音轨的源素材。

    WARNING

    素材 URL 必须是公网可直接下载的直链(图片 jpg/jpeg/png ≤ 50MB、宽高 ≥ 300px;音频 ≥ 5 秒;视频 mp4/mov ≤ 200MB)。实测正规站点直链一般可拉取(自有站点、主流对象存储等),但个别站点会被上游拉取失败(实测 w3school.com.cn、海外图床 wikimedia 等会失败,图片/音频素材失败不扣费),遇到「拉取素材失败」请更换素材源重试。特别注意:base_video 等视频素材拉取失败时任务不报错、仍按编辑价计费,但产出内容与底视频无关——编辑前请先自查链接可达(本站成片链接约 45 分钟失效,不能直接当底视频二次编辑)。推荐优先使用自有域名直链,或先经本站生成再引用产物链接(产物直链,最稳定),或 Base64 传入。