Kling 3.0 Omni 调用说明

本文着重介绍视频生成调用方式和官方的区别，具体细节可参考可灵AI 3.0系列模型API文档

本平台调用示例

创建任务

下面的示例包含了所有生视频类型（文生视频 / 多镜头分镜 / 图生视频-首帧 / 图生视频-首尾帧 / 多模态参考 / 视频编辑）和所有可选参数，实际使用时只需保留对应类型的媒体元素（image_list / video_list）、并按需调整参数即可。

⚠️ 各生视频类型的媒体元素及部分参数存在互斥关系（详见下方参数说明），下例仅作为完整字段参考，请勿原样提交。

curl https://api.token-hubs.com/video/kling \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_name": "kling-v3-omni",           // 必填，目前仅支持 kling-v3-omni
    "prompt": "",                            // 文本提示词，最长 2500 字符；multi_shot 为 false 或 shot_type 为 intelligence 时必填
    "multi_shot": true,                      // 是否生成多镜头视频；为 true 时 prompt 无效，为 false 时 shot_type/multi_prompt 无效
    "shot_type": "customize",                // 分镜方式，枚举：customize；multi_shot 为 true 时必填
    "multi_prompt": [                        // 各分镜信息；multi_shot 为 true 且 shot_type 为 customize 时必填，最多 6 个分镜
      {
        "index": 1,                          // 分镜序号
        "prompt": "<<<image_1>>>A person sitting on a park bench, sunlight filtering through trees. Simple composition, no dialogue.", // 分镜提示词，最长 512 字符
        "duration": "2"                      // 该分镜时长（秒），≥1 且所有分镜时长之和等于总时长
      },
      {
        "index": 2,
        "prompt": "A car speeding down a rainy street, headlights glowing. Dynamic angle, focus on motion.",
        "duration": "3"
      }
    ],
    "image_list": [                          // 参考图列表；通过 type 指定首尾帧
      {
        "image_url": "https://example.com/first.jpg", // 图片 URL 或 Base64，.jpg/.jpeg/.png，≤10MB，宽高≥300px，宽高比 1:2.5~2.5:1
        "type": "first_frame"                // first_frame 首帧 / end_frame 尾帧；有尾帧时必须有首帧
      },
      {
        "image_url": "https://example.com/last.jpg",
        "type": "end_frame"
      }
    ],
    "video_list": [                          // 参考视频，至多 1 段；refer_type 区分用途
      {
        "video_url": "https://example.com/ref.mp4", // MP4/MOV，≤200MB，时长≥3s，宽高 720px~2160px
        "refer_type": "feature",             // feature 特征参考视频 / base 待编辑视频（默认 base）
        "keep_original_sound": "no"          // 是否保留视频原声：yes / no
      }
    ],
    "mode": "pro",                           // 生成模式：std(720P) / pro(1080P) / 4k
    "aspect_ratio": "16:9",                  // 画面纵横比（宽:高），枚举：16:9 / 9:16 / 1:1；未使用首帧参考或视频编辑时必填
    "duration": "5",                         // 生成视频时长（秒），取值 3~15
    "sound": "on",                           // 是否同时生成声音：on / off；有参考视频时只能为 off
    "watermark_info": {                      // 暂不支持
      "enabled": false
    },
    "callback_url": "https://your-domain.com/callback", // 暂不支持
    "external_task_id": "" // 暂不支持
  }'

返回体（创建成功后返回任务 task_id，用于后续查询任务状态）：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "task_id": "qvideo-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxx",
    "task_info": {
      "external_task_id": null
    },
    "task_status": "submitted",
    "created_at": 1782460477000,
    "updated_at": 1782460477000
  }
}

查询任务

curl -X GET "https://api.token-hubs.com/video/kling/{task_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

返回体的内容随任务状态变化，主要有以下两种：

1. 任务进行中（data.task_status 为 submitted / processing）：尚未生成视频，data.task_result.videos 为空数组。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "task_id": "qvideo-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxx",
    "task_status": "submitted",
    "task_status_msg": "",
    "watermark_info": {
      "enabled": false
    },
    "task_result": {
      "videos": []
    },
    "task_info": {
      "external_task_id": null
    },
    "final_unit_deduction": null,
    "created_at": 1782460477000,
    "updated_at": 1782460477000
  }
}

2. 任务成功（data.task_status 为 succeed）：data.task_result.videos[].url 即为生成视频的下载地址。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "task_id": "qvideo-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxx",
    "task_status": "succeed",
    "task_status_msg": "",
    "watermark_info": {
      "enabled": false
    },
    "task_result": {
      "videos": [
        {
          "id": "qvideo-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxx-1",
          "url": "https://example.com/kling/xxxxxxxx/1.mp4?e=1783065575&token=xxxxxxxx:xxxxxxxx",
          "watermark_url": null,
          "duration": "5"
        }
      ]
    },
    "task_info": {
      "external_task_id": null
    },
    "final_unit_deduction": null,
    "created_at": 1782460477000,
    "updated_at": 1782460775000
  }
}

视频生成为异步任务，需轮询本接口直到 data.task_status 变为 succeed，再从 data.task_result.videos[].url 获取视频。url 含签名且有有效期（示例 e 参数为过期时间戳），请及时下载转存。

其他生成模式参考官方

注意事项

请求参数说明

  • 字段用法与官方一致：请求字段名（model_name、image_list[].image_url、aspect_ratio、duration 等）均与可灵官方文档保持一致。
  • 多镜头与提示词：multi_shot 为 true 时 prompt 无效，需通过 multi_prompt 定义各分镜；为 false 时 shot_type、multi_prompt 无效，直接使用 prompt。
  • 首尾帧规则：image_list[].type 用于定义首尾帧（first_frame / end_frame），有尾帧时必须有首帧；数组中超过 2 张图片时不支持设置尾帧。有参考视频时参考图≤4，无参考视频时≤7。
  • 参考视频规则：refer_type 为 base（待编辑视频）时 seconds 无效，输出时长与输入视频一致，且不能定义视频首尾帧；有参考视频时 sound 只能为 off。
  • 暂不支持的字段：watermark_info、callback_url、external_task_id。