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

    与可灵官方 API 结构一致:文生 / 图生视频分别调用对应端点,全能模型 kling-video-v3-omni / kling-video-o1 也用同一对端点(网关按模型自动路由到全能生成入口,查询 / 计费方式不变),动作控制模型 kling-video-motion-control-v3.0 / v2.6 同样走此入口(见动作控制)。image_tail / negative_prompt / resolution 等字段顶层或 metadata 内均可;可灵官方 API 独有的 cfg_scale / camera_control / static_mask / dynamic_masks 等字段上游不支持,传了会被忽略。

    端点

    • 文生视频:POST /kling/v1/videos/text2video
    • 图生视频:POST /kling/v1/videos/image2video

    除可灵格式外,也可使用通用端点 POST /v1/video/generations(OpenAI 风格,见创建视频生成任务)与 POST /v1/responses(Responses 格式,产物以 <video> 标签渲染)。

    请求体

    NOTE

    提交前网关会按模型预校验 resolution / duration / audio / multi_shot 等参数,非法值直接返回 400 并附合法取值提示,按提示修正即可。这是为保护你的余额:上游对这些参数并不报错,而是静默按默认值生成并照常扣费。

    字段类型必填说明
    modelstring是模型名,填模型广场在售的可灵模型,如 kling-video-v2.5-turbo、kling-video-v3、kling-video-v3-omni(旧写法 model_name 同样有效)
    promptstring是视频描述;negative_prompt 会拼接进本字段发送上游
    imagestring否图生视频首帧图片(URL 或 Base64);带此字段按图生视频处理。支持 jpg / jpeg / png,≤ 50MB,宽高均 ≥ 300px
    image_tailstring否图生视频尾帧图片,约束同 image;必须伴随 image(仅尾帧返回 400)。v2.5 / v2.6 系首尾帧自动强制 1080p
    negative_promptstring否反向提示词,拼接进 prompt 发送上游
    durationnumber | string否时长(秒),字符串数字亦可:v2.5-turbo / v2.6 为 5 / 10,v3 / v3-turbo / v3-omni 为 3 ~ 15 整数,o1 为 3 ~ 10(纯文生仅 5 / 10)
    resolutionstring否分辨率:720p / 1080p / 4k(4k 仅 v3 / v3-omni),不传按上游默认档。分辨率 / 音频 / 多镜头等参数改用本字段与 audio / multi_shot,不再依赖 mode
    aspect_ratiostring否画幅 16:9 / 9:16 / 1:1,仅文生视频有效(图生画幅跟随图片);size 尺寸写法(如 1920x1080)会自动换算
    audiostring否音频:native / original / off,支持范围见下方模型速查表;引用音色时不能为 off
    multi_shotboolean否多镜头,仅 v3 / v3-omni
    external_task_idstring否自定义任务 ID,查询时可回显
    metadataobject否上述字段也可放进 metadata(duration / resolution / audio / multi_shot / aspect_ratio / image_tail / negative_prompt);素材数组 contents 与 options 见元素与音色
    modestring否旧版写法兼容:std → 720p、pro → 1080p(仅在未显式传 resolution 时生效);mock / test_mode 会返回 400(无 mock 实现,为防真实扣费已拦截)
    settingsobject否旧版写法兼容:{resolution, aspect_ratio, duration} 对象透传,优先级低于顶层 / metadata 显式字段

    模型 × 参数速查

    模型durationresolutionaudiomulti_shot
    kling-video-v2.5-turbo5 / 10720p / 1080p——
    kling-video-v2.65 / 10720p / 1080pnative / off—
    kling-video-v3-turbo3 ~ 15720p / 1080p——
    kling-video-v33 ~ 15720p / 1080p / 4knative / original / off✅
    kling-video-v3-omni3 ~ 15720p / 1080p / 4knative / original / off✅
    kling-video-o13 ~ 10(纯文生 5/10)720p / 1080poriginal / off—

    补充约束(上游实测):v2.5 / v2.6 系首帧 + 尾帧仅支持 1080p(自动改档);元素素材 ≤ 3 个(v3 / v3-omni / o1)、音色素材 ≤ 2 个;元素 / 音色的创建与引用见元素与音色。

    请求示例

    cURL
    Python
    Node.js
    # 文生视频:分辨率用 resolution 字段
    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-v2.5-turbo",
        "prompt": "一只橘猫在草地上追蝴蝶,电影感镜头,缓慢推近",
        "duration": 5,
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "negative_prompt": "模糊,变形"
      }'
    # 图生视频 + 尾帧:image / image_tail 传图片 URL 或 Base64
    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.5-turbo",
        "image": "https://example.com/first-frame.jpg",
        "image_tail": "https://example.com/last-frame.jpg",
        "prompt": "让画面中的猫跑起来,镜头缓慢推近"
      }'
    NOTE

    旧版代码无需修改即可使用:旧站的 mode(std / pro)、原生 settings 对象、metadata 内 image_tail / negative_prompt 隧道等写法均兼容,行为不变。但有两点差异:mode: "mock" 不再可用(返回 400,零成本测试请用站内「自用模式」);非法参数组合从静默丢弃改为 400 拦截(防止上游静默按默认档扣费)。旧版写法细节见旧版使用指南(v2.5-turbo)。

    响应体

    提交成功返回任务对象,data.task_id(顶层 task_id 同值)用于查询,task_status 起始为 submitted。

    响应示例

    {
      "code": 0,
      "message": "SUCCEED",
      "data": {
        "task_id": "task_xxxxxxxx",
        "task_status": "submitted",
        "task_status_msg": "",
        "create_time": 1790573567856,
        "update_time": 1790573567856
      },
      "task_id": "task_xxxxxxxx"
    }

    查询状态与下载见查询与下载。