• 简体中文
  • 元素与音色(可灵统一格式)

    元素(自定义主体形象)与音色(克隆音色)先通过资产管理接口创建、拿到 ID,再在视频生成的 metadata.contents 里引用(见提交任务 · 引用元素与音色)。鉴权与视频接口相同:请求头携带 Authorization: Bearer 你的令牌。

    资产模型与路由

    两套命名空间按模型系列对应,资产 ID 不互通:

    资产类型kling 系列(kling-* 模型)kling-v 系列(kling-v-* 模型)
    元素kling-elementkling-v-element
    音色kling-voicekling-v-voice

    路由前缀:kling 系列为 /kling-asset/v1/assets/(创建 / 查询 / 删除),kling-v 系列为 /kling-v-asset/v1/assets/(创建 / 查询,无删除)。以下均以 kling 系列路由书写,kling-v 系列替换前缀与伪模型即可(差异见表格备注)。

    创建元素

    POST /kling-asset/v1/assets/elements

    参数必填说明
    model是kling-element(kling-v 系列为 kling-v-element)
    name是元素名称,≤ 20 字
    frontal_image是正面图 URL
    refer_imageskling 系可选 / kling-v 系必填1 ~ 3 张补充参考图 URL(侧脸、不同角度等);kling 系缺省自动补正面图,kling-v 系缺省或越界返回 400
    description可选元素描述,≤ 100 字;缺省用 name 兜底
    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-element",
        "name": "我的主角",
        "description": "短发年轻男性",
        "frontal_image": "https://example.com/front.jpg",
        "refer_images": ["https://example.com/side.jpg"]
      }'

    创建音色

    POST /kling-asset/v1/assets/voices

    参数必填说明
    model是kling-voice(kling-v 系列为 kling-v-voice)
    name是音色名称,≤ 20 字
    voice_url是参考音频 URL:单人干净人声、约 5 秒以上(kling-v 系列限 .mp3 / .wav / .mp4 / .mov,5 ~ 30 秒)
    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/voices \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-voice",
        "name": "温柔女声",
        "voice_url": "https://example.com/sample.wav"
      }'

    查询与删除

    查询:GET /kling-asset/v1/assets/elements/{task_id}(音色把 elements 换成 voices)。

    删除(仅 kling 系列):POST /kling-asset/v1/assets/elements/delete,body 为 {"element_id": "…"};音色为 /voices/delete + {"voice_id": "…"}。删除后查询返回 deleted: true;删除后的 ID 不可再被视频生成引用。

    查询轮询示例(元素;音色把路径中 elements 换成 voices):

    cURL
    Python
    Node.js
    curl https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/task_xxxxxxxx \
      -H "Authorization: Bearer sk-你的令牌"

    删除示例(音色把路径中 elements 换成 voices、字段换成 voice_id):

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/delete \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{"element_id": "324465195791137"}'

    响应结构

    出参统一包络 {code, message, data},data 固定五字段,状态词表与视频查询路由一致(四值大写):

    字段说明
    data.task_id资产任务 id
    data.status四值:QUEUED → IN_PROGRESS → SUCCESS / FAILURE
    data.element_id元素 ID,仅元素任务 SUCCESS 时非空
    data.voice_id音色 ID,仅音色任务 SUCCESS 时非空
    data.fail_reason仅 FAILURE 非空

    deleted 仅删除任务终态附加 true。element_id / voice_id 即视频生成 contents 里引用的 ID;失败时 data.fail_reason 给出原因。

    // 创建中 / 排队
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "QUEUED",
        "element_id": "",
        "voice_id": "",
        "fail_reason": ""
      }
    }
    // 元素创建成功
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "SUCCESS",
        "element_id": "324465195791137",
        "voice_id": "",
        "fail_reason": ""
      }
    }
    // 删除终态(仅 kling 系列,附加 deleted: true)
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "SUCCESS",
        "element_id": "324465195791137",
        "voice_id": "",
        "fail_reason": "",
        "deleted": true
      }
    }

    在视频生成中引用

    引用分两步,缺一不可:第 1 步在视频提交的 metadata.contents 里声明素材(把 ID 带进任务),第 2 步在提示词里点名素材(告诉模型用哪个)。通用场景的完整示例见提交任务 · 引用元素与音色。

    第 1 步 · contents 声明:

    • 元素:{"type": "element", "id": "<元素ID>"},可另带 "name" 便于上游识别主体名称(不影响匹配);
    • 音色:{"type": "voice", "id": "<音色ID>"};
    • 动作控制任务的元素项额外要求:{"type": "element", "id": "<元素ID>", "element_id": "<元素ID>"}——id 与 element_id 必须同时携带且同值,缺任一键返回 400;
    • ID 填元素与音色创建任务终态返回的 element_id / voice_id(纯数字串,如 325057409061256)——不是资产名称,也不是资产任务的 task_id。

    第 2 步 · 提示词点名:两种写法按任务类型二选一,互不通用。

    写法 A:<<<element_N>>> / <<<voice_N>>> 占位写法 B:@<元素ID> 点名
    适用任务普通任务:全能系文生直引 / 其余模型图生配首帧动作控制任务(kling-motion-3.0 系)引用元素
    提示词形态占位符嵌在自然语言里:让 <<<element_1>>> 面向镜头,用 <<<voice_1>>> 说…直接写 @ 加元素 ID:让 @325057409061256 跟随动作跳舞
    contents 项要求element 带 id(可带 name);voice 带 idelement 须同时带 id 与 element_id(同值)
    可点名素材元素与音色均可,可多个仅元素(动作控制任务不支持音色引用)

    写法 A 的编号规则:

    • N 按 contents 中同类素材的出现顺序从 1 编号,元素、音色各自独立计数,与 ID 数值无关——声明 2 个元素 + 1 个音色时,分别用 <<<element_1>>>、<<<element_2>>>、<<<voice_1>>> 点名;
    • 同一占位符可在提示词中出现多次;不必每个素材都被点名,但点名是模型明确遵循该素材的方式,只传 id 也能提交,建议始终点名;
    • 占位符由上游按序号匹配,站点只透传提示词原文、不做字符串替换——务必原样书写:三个尖括号包裹、紧贴编号(<<<element_1>>>);写成 <<element_1>>、<<< element_1 >>> 等非规范形态不会报错,但可能不被识别为素材引用。

    写法 B 的使用边界:

    • @ 后写 contents 项 id 键的值(即元素 ID);提示词建议走 contents 的 {"type": "prompt", "text": "…"} 项、@ 点名写在该 text 中(写在顶层 prompt 也可,两处同时存在时顶层优先);
    • 普通任务不要用 @ 写法、动作控制任务不要用 <<<>>> 写法——两种写法对应上游两套素材注入机制,互不通用,跨场景书写行为未定义。

    动作控制任务引用元素(kling-motion-3.0 系,≤ 1 个)——元素项同时带 id 与 element_id(同值),用写法 B 的 @<元素ID> 在 contents 的提示词项中点名:

    cURL
    Python
    Node.js
    # 动作控制引用元素:element 项带 id + element_id(同值),@ 点名写在 contents 的 prompt 项里
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-motion-3.0",
        "metadata": {
          "character_orientation": "video",
          "audio": "original",
          "contents": [
            { "type": "image", "url": "https://example.com/character.webp" },
            { "type": "video", "url": "https://example.com/dance.mp4" },
            { "type": "element", "id": "324465195791137", "element_id": "324465195791137" },
            { "type": "prompt", "text": "让 @324465195791137 跟随参考视频的动作跳舞" }
          ]
        }
      }'

    引用约束清单(违反即提交 400):

    • 数量:元素普通任务 ≤ 3 个;动作控制任务仅 kling-motion-3.0 系且 ≤ 1 个(kling-motion-2.6 系不支持元素);音色 ≤ 2 个;
    • 音色必须配发声档:contents 含 voice 时必须显式 metadata.audio 为 native / original(缺省 off → 400)。因此不支持 audio 的模型(kling-2.5-turbo / kling-3.0-turbo 系)与仅支持 off 档的 kling-v-o1 实际不可用音色;动作控制任务不支持音色引用;
    • kling-2.6 系改档:指定音色的任务须 audio=native,自动按 1080p 生成并按 1080p 计费;
    • 文生带素材限制:非全能模型的文生任务(无 image、无首尾帧)不能携带 contents——配 image 走图生(见上),或改用全能系文生直引;
    • 命名空间对齐:kling-* 模型只能引用 /kling-asset 创建的 ID,kling-v-* 模型只能引用 /kling-v-asset 创建的 ID,跨系引用无效;
    • 可混用:元素与音色可同单混用,也可各自单独引用;
    • 勿引用已删除的资产:kling 系列资产可删除(见元素与音色),删除后的元素 / 音色不可再引用,引用已删 ID 的任务会失败。

    引用约束清单(违反即提交 400):

    • 数量:元素普通任务 ≤ 3 个;动作控制任务仅 kling-motion-3.0 系且 ≤ 1 个(kling-motion-2.6 系不支持元素);音色 ≤ 2 个;
    • 音色必须配发声档:contents 含 voice 时必须显式 metadata.audio 为 native / original(缺省 off → 400)。因此不支持 audio 的模型(kling-2.5-turbo / kling-3.0-turbo 系)与仅支持 off 档的 kling-v-o1 实际不可用音色;动作控制任务不支持音色引用;
    • kling-2.6 系改档:指定音色的任务须 audio=native,自动按 1080p 生成并按 1080p 计费;
    • 文生带素材限制:非全能模型的文生任务(无 image、无首尾帧)不能携带 contents——配 image 走图生,或改用全能系文生直引;
    • 命名空间对齐:kling-* 模型只能引用 /kling-asset 创建的 ID,kling-v-* 模型只能引用 /kling-v-asset 创建的 ID,跨系引用无效;
    • 可混用:元素与音色可同单混用,也可各自单独引用;
    • 勿引用已删除的资产:kling 系列资产可删除(见查询与删除),删除后的元素 / 音色不可再引用,引用已删 ID 的任务会失败。