• 简体中文
  • 提交任务(可灵统一格式)

    可灵统一格式的视频生成为异步任务:POST /v1/videos 提交 → 查询与下载 拿成片直链。15 个模型共用本端点,选型见模型指南。鉴权与站点其他接口一致:请求头携带 Authorization: Bearer 你的令牌(见接入地址与鉴权)。

    NOTE

    参数缺省:duration 缺省 5 秒、resolution 缺省 720p、aspect_ratio 缺省 16:9、audio 缺省 off(静音,即该模型最低价档)——想要声音必须显式传 metadata.audio。提交前网关会按模型校验参数,非法组合直接返回 400 并附合法取值提示,按提示修正即可。

    端点

    POST /v1/videos

    请求体为 JSON;也接受 multipart 表单(图片文件走 input_reference 字段,metadata 以 JSON 字符串传入),见multipart 文件上传。

    请求体

    参数类型必填缺省说明
    modelstring是—模型 id,见模型指南
    promptstring文生必填—生成提示词;图生视频可省略(由素材表达)
    imagestring图生必填—首帧参考图,支持 URL / Base64;传了即图生视频。只能是字符串,传数组或对象返回 400
    input_referencestring / 文件可选—image 的别名:JSON 里传字符串,或 multipart 文件上传(全请求唯一文件字段);与 image 二选一
    durationinteger可选5成片秒数,3 ~ 15 整数;各模型支持集合见模型指南,越界返回 400
    secondsinteger可选—duration 的旧写法别名,两者都传时 seconds 生效
    resolutionstring可选720p720p / 1080p / 4k(4k 仅 kling-3.0 系 / kling-3.0-omni 系);按模型校验,越界返回 400
    aspect_ratiostring可选16:916:9 / 9:16 / 1:1 / 4:3 / 3:4;首尾帧任务画幅跟随素材(此值被忽略)
    metadataobject可选—扩展参数对象,见下

    以下两个参数为旧写法兼容,建议尽量使用新写法(分辨率用 resolution、画幅用 aspect_ratio):

    参数类型缺省说明
    modestring—旧写法档位别名:std = 720p、pro = 1080p;显式 resolution 优先
    sizestring—画幅的尺寸写法(如 1920x1080),仅用于推断画幅:1024x1024 / 512x512 → 1:1,1280x720 / 1920x1080 → 16:9,720x1280 / 1080x1920 → 9:16,其他值 → 16:9;分辨率数值本身不参与

    metadata 参数

    字段类型缺省说明
    audiostringoffoff 静音 / native 生成配音 / original 保留原声。不传即静音 = 该模型最低价档;模型不支持 audio 时传非 off 值返回 400
    contentsarray—素材通道,见metadata.contents 素材通道
    multi_shotboolean—多镜头分镜开关,仅 kling-3.0 系 / kling-3.0-omni 系
    shot_typestring—customize 按分镜脚本 / intelligence 智能分镜,仅 multi_shot=true 时有效
    multi_promptarray—各分镜内容 {"index": 1, "prompt": "…", "duration": 3},仅 multi_shot=true 时有效
    character_orientationstring—image / video,动作控制模型(kling-motion-*)必填,指明以形象图还是动作视频为主参考
    optionsobject—扩展选项透传(如自定义任务标识),以实际支持为准

    metadata 内也可传以下顶层参数的备选位置:顶层未传时生效,优先级不如顶层,建议在顶层传递。

    metadata 字段说明
    mode同顶层 mode:std = 720p、pro = 1080p 档位别名
    resolution / aspect_ratio / duration对应顶层同名参数的备选位置

    metadata.contents 素材通道

    contents 是数组,每项形如 {"type": "<类型>", …}:

    type携带键用途适用范围
    prompttext提示词素材项,可与顶层 prompt 并用全部模型
    first_frameurl首帧图(兼容写法,统一推荐顶层 image 承担首帧;与 image 同传时按本项生效)图生 / 全能系
    last_frameurl尾帧图,必须与首帧同时提供;v2.5 / v2.6 系尾帧任务自动按 1080p 生成图生 / 全能系
    refer_imageurl参考图(主体参考)图生 / 全能系
    base_videourl参考视频仅全能系(kling-3.0-omni 系 / kling-o1 系)
    feature_videourl参考视频(特征)仅全能系
    videourl参考视频旧写法,等同 base_video仅全能系
    imageurl形象参考图仅动作控制模型
    elementid(可带 name;动作控制任务另带 element_id)引用已创建的元素,见元素与音色普通任务 ≤ 3 个;动作控制仅 kling-motion-3.0 且 ≤ 1
    voiceid引用已创建的音色,见元素与音色≤ 2 个;指定音色时 audio 不能为 off

    约束:

    • 文生视频(无 image、无首尾帧)携带其余素材项 → 400(全能系 kling-3.0-omni / kling-o1 除外,可只带素材直引,见引用元素与音色);
    • 动作控制任务的素材必须恰好一张形象图(image)+ 一段动作参考视频(video),动作视频须包含清晰的人物动作(人物过小、缺少上半身会被拒绝,任务失败并回显原因);
    • 素材 URL 均须公网可访问(http / https)。

    参数优先级

    同一参数多处传值时,按以下优先级取值:

    • duration:顶层(含 seconds)> metadata.duration > 缺省 5;
    • resolution:顶层 > metadata.resolution > mode 别名 > 缺省 720p;
    • aspect_ratio:顶层 > metadata.aspect_ratio > size 推断 > 缺省 16:9。

    请求示例

    以下场景按需取用,完整参数说明见上文请求体。

    文生视频

    只传 model + prompt,三档全缺省(720p / 5 秒 / 静音):

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-3.0",
        "prompt": "一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近"
      }'

    图生视频

    传 image 即图生视频,prompt 可省略;resolution 按需指定:

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-2.5-turbo",
        "prompt": "镜头缓缓推进,猫转头看向镜头",
        "resolution": "1080p",
        "image": "https://example.com/first-frame.jpg"
      }'

    首尾帧生视频

    统一推荐写法:顶层 image 承担首帧,contents.last_frame 承担尾帧。 尾帧必须与首帧同时提供;首尾帧任务画幅跟随素材(aspect_ratio 被忽略),v2.5 / v2.6 系自动按 1080p 生成,成片从首帧画面平滑过渡到尾帧画面:

    cURL
    Python
    Node.js
    # 场景一:推荐写法(顶层 image 首帧 + contents.last_frame 尾帧)
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-2.6",
        "prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
        "image": "https://example.com/first.jpg",
        "metadata": {
          "contents": [
            { "type": "last_frame", "url": "https://example.com/last.jpg" }
          ]
        }
      }'
    
    # 场景二:兼容写法(仍须传 image;首帧按 contents.first_frame 生效,image 不参与)
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-2.6",
        "prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
        "image": "https://example.com/first.jpg",
        "metadata": {
          "contents": [
            { "type": "first_frame", "url": "https://example.com/first.jpg" },
            { "type": "last_frame", "url": "https://example.com/last.jpg" }
          ]
        }
      }'

    兼容写法同样必须传顶层 image(首尾帧是图生任务,无 image 的纯 contents 帧写法两渠道均返回 400);image 与 contents.first_frame 同时提供时按 first_frame 生效,image 不参与首帧——不要依赖双传,首帧在两处二选一表达即可。

    多镜头分镜

    multi_shot 开启分镜:intelligence 智能分镜,或 customize 按 multi_prompt 脚本出片。仅 kling-3.0 系 / kling-3.0-omni 系支持:

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-3.0",
        "prompt": "一只猫的一天",
        "metadata": {
          "multi_shot": true,
          "shot_type": "customize",
          "multi_prompt": [
            { "index": 1, "prompt": "清晨,猫在窗台伸懒腰", "duration": 3 },
            { "index": 2, "prompt": "午后,猫在草地上追蝴蝶", "duration": 4 }
          ]
        }
      }'

    动作控制

    形象图 + 动作参考视频(恰好一图一视频),character_orientation 必填;成片时长跟随动作视频,请求 duration 不生效:

    cURL
    Python
    Node.js
    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": "prompt", "text": "跟随视频中的舞蹈动作" }
          ]
        }
      }'

    引用元素与音色

    引用分两步:第 1 步在 metadata.contents 里声明素材,第 2 步在提示词里点名——完整规则(写法 A / 写法 B、编号规则、约束清单、动作控制引用元素示例)见元素与音色 · 在视频生成中引用。最小写法:

    • 声明:元素 {"type": "element", "id": "<元素ID>"}、音色 {"type": "voice", "id": "<音色ID>"},ID 填创建终态返回的 element_id / voice_id;
    • 点名:普通任务用 <<<element_N>>> / <<<voice_N>>> 占位(N 按 contents 中同类素材顺序从 1 编号),动作控制任务用 @<元素ID>(元素项另带 element_id 同值);

    全能模型文生直引(kling-3.0-omni 系 / kling-o1 系)——文生任务可直接携带素材,无需首帧:

    cURL
    Python
    Node.js
    # 全能系文生直引:只带 contents 素材、无需首帧
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-3.0-omni",
        "prompt": "让 <<<element_1>>> 面向镜头,用 <<<voice_1>>> 的声音说:大家好",
        "duration": 5,
        "metadata": {
          "audio": "native",
          "contents": [
            { "type": "element", "id": "324465195791137" },
            { "type": "voice", "id": "941405858536758877" }
          ]
        }
      }'

    其余模型须配首帧(图生 + 素材引用)——非全能模型的文生任务不能携带素材,传 image 走图生即可,contents 里只声明元素 / 音色,首帧由 image 自动承担:

    cURL
    Python
    Node.js
    # 普通模型引用素材:必须配首帧(image 承担首帧,contents 只声明元素 / 音色)
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-3.0",
        "prompt": "<<<element_1>>> 在咖啡店落座,<<<voice_1>>> 轻声说:今天天气不错",
        "image": "https://example.com/scene.jpg",
        "duration": 5,
        "metadata": {
          "audio": "native",
          "contents": [
            { "type": "element", "id": "324465195791137" },
            { "type": "voice", "id": "941405858536758877" }
          ]
        }
      }'

    动作控制任务引用元素(写法 B:@<元素ID> 点名,元素项带 id + element_id 同值)的完整写法与示例见元素与音色 · 在视频生成中引用。

    引用相关的提交 400 速查(error_code 均为 invalid_contents / motion_contents_invalid,包络形态见错误处理):

    触发message 文案
    元素 > 3 个元素素材最多 3 个(收到 N 个)
    音色 > 2 个音色素材最多 2 个(收到 N 个)
    element 项缺 idelement 项须带 id(prompt 中用 <<<element_N>>> 引用)
    voice 项缺 idvoice 项须带 id(prompt 中用 <<<voice_N>>> 引用)
    指定音色但 audio 缺省 / off指定音色时 audio 不能为空/off
    非全能模型文生带 contents文生视频不支持 contents 素材;素材引用请配合图生视频或全能模型(kling-3.0-omni / kling-o1)
    动作控制元素缺 element_id 或 idmotion-control 的 element 项须同时带 element_id 与 id(prompt 中用 @id 引用)

    multipart 文件上传

    表单字段与 JSON 参数同名;图片文件放 input_reference,metadata 以 JSON 字符串传入:

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
      -H "Authorization: Bearer sk-你的令牌" \
      -F model=kling-2.5-turbo \
      -F prompt=镜头缓缓推进 \
      -F duration=5 \
      -F input_reference=@first-frame.jpg

    响应体

    字段说明
    id任务 id,用于查询与下载
    object恒为 "video"
    model提交的模型 id
    status初始 queued(小写;与查询接口的四值状态不是同一套词表)
    progress初始 0
    created_at创建时间戳(秒)
    WARNING

    提交响应的 status 是提交通道的统一词表(queued / in_progress / completed / failed),与查询接口的 QUEUED / IN_PROGRESS / SUCCESS / FAILURE 不是同一套;任务是否完成一律以查询接口为准。提交响应不含成片地址。

    响应示例

    {
      "id": "task_xxxxxxxx",
      "object": "video",
      "model": "kling-3.0",
      "status": "queued",
      "progress": 0,
      "created_at": 1792992894
    }

    错误处理

    提交期参数错误返回 HTTP 400 与统一包络;message 内嵌 JSON,解析后 error_code 可用于程序判断:

    {
      "code": "fail_to_fetch_task",
      "message": "{\"error_code\":\"audio_not_supported\",\"message\":\"kling-3.0-turbo 不支持 audio 参数\"}",
      "data": null
    }
    error_code含义
    model_not_found模型 id 不存在
    invalid_duration / invalid_resolution / invalid_aspect_ratio参数超出该模型支持集合(message 会列出合法值)
    audio_not_supported该模型不支持 audio(收到非 off 值)
    invalid_audioaudio 值不在该模型合法集合内
    invalid_contents / motion_contents_invalid素材组合不合法(如文生带素材、动作控制缺图或缺视频)
    image_required / image_invalid / prompt_required必填素材缺失或形态非法
    upstream_rejected / upstream_unavailable生成服务拒绝 / 暂不可用,可稍后重试
    plugin_usage_invalid档位超出该模型计费枚举(如 kling-2.5-turbo 传 4k),提交时即被拦截

    计费说明

    • 按实际生成档位计费(模型 × 时长 × 分辨率 × 音频档 × 素材档 × 音色),单价见模型广场;
    • audio 不传 = 静音档 = 该模型最低价;自动改档(首尾帧、audio=native、指定音色等)按实际生成档计费;
    • 非 16:9 画幅(1:1 方幅等)可能按更高分辨率档计费;
    • 动作控制任务成片时长跟随动作参考视频,按成片实际时长计费;
    • 失败任务不计费。