可灵 Omni API 文档

官方文档入口（仅参考）：

https://klingai.com/document-api/apiReference/model/OmniVideo

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	否	上游默认	推荐模型字段，目前支持`kling-video-o1` ， `kling-v3-omni`
`model`	string	否	无	兼容字段，会映射到 `model_name`
`multi_shot`	boolean	否	`false`	是否多镜头；`kling-video-o1` 不支持分镜
`shot_type`	string	条件必填	无	`multi_shot=true` 时生效
`prompt`	string	条件必填	无	提示词（单镜头或智能分镜必填）
`multi_prompt`	array	条件必填	无	`multi_shot=true` 且 `shot_type=customize` 时必填
`image_list`	array	否	空	参考图列表（可含首尾帧）
`element_list`	array	否	空	主体参考列表
`video_list`	array	否	空	参考视频列表（`refer_type=base/feature`）
`sound`	string	否	`off`	是否生成声音
`mode`	string	否	`pro`	模式（`std`/`pro`/`4k`）
`aspect_ratio`	string	否	无	画幅（`16:9`/`9:16`/`1:1`）
`seconds`	string	否	无	兼容时长字段
`duration`	string	否	无	时长字段
`watermark_info`	object	否	空	水印开关
`callback_url`	string	否	空	回调地址
`external_task_id`	string	否	空	自定义任务 ID

multi_shot

是否生成多镜头视频。

取值	说明
`false`	单镜头视频。此时 `shot_type` 和 `multi_prompt` 无效。
`true`	多镜头视频。此时 `prompt` 参数无效，需要通过 `shot_type` 指定分镜方式。

默认值为 false。

kling-video-o1 不支持分镜，请保持 multi_shot=false。

shot_type

分镜方式。当 multi_shot=true 时，当前参数必填。

取值	说明
`customize`	自定义分镜。需要传入 `multi_prompt`。
`intelligence`	智能分镜。需要传入 `prompt`。

当 multi_shot=false 时，当前参数无效。

prompt

文本提示词，可包含正向描述和负向描述。可将提示词模板化来满足不同的视频生成需求。

可选参数。
不能超过 2500 个字符。
当 multi_shot=false 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=intelligence 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=customize 时，当前参数无效，分镜提示词应填写在 multi_prompt 中。

Omni 模型可通过 Prompt 与主体、图片、视频等内容实现多种能力：

通过 <<<image_1>>> 引用 image_list 中的第 1 张图片。
通过 <<<element_1>>> 引用 element_list 中的第 1 个主体。
通过 <<<video_1>>> 引用 video_list 中的第 1 个视频。
例如：参考<<<video_1>>>的运镜方式，让<<<element_1>>>和<<<image_1>>>中的人物同框出现。

multi_prompt 元素

参数名	类型	必填	说明
`index`	int	是	分镜序号
`prompt`	string	是	分镜提示词
`duration`	string	是	分镜时长

各分镜信息，通过 index、prompt、duration 定义分镜序号、提示词和时长。

参数规则：

当 multi_shot=true 且 shot_type=customize 时，当前参数不得为空。
最多支持 6 个分镜，最少支持 1 个分镜。
每个分镜相关内容最大长度不超过 512 个字符。
每个分镜的时长不大于当前任务总时长，且不小于 1 秒。
所有分镜的时长之和需要等于当前任务的总时长。

格式如下：

json

"multi_prompt":[
  { "index": int, "prompt": "string", "duration": "5" },
  { "index": int, "prompt": "string", "duration": "5" }
]

参数名	类型	必填	默认值	说明
`video_list`	array	否	无	参考视频列表，通过 URL 获取。可作为特征参考视频，也可作为待编辑视频；默认由服务商按待编辑视频处理。当前最多支持 1 段视频。

子参数

参数名	类型	必填	默认值	说明
`video_url`	string	是	无	视频 URL。不能为空。
`refer_type`	string	否	`base`	视频参考类型。`base` 表示待编辑视频/指令变换；`feature` 表示特征参考视频。
`keep_original_sound`	string	否	服务商默认	是否保留原声。`yes` 表示保留，`no` 表示不保留；对 `feature` 类型也生效。

参数规则

refer_type=base 时表示待编辑视频，不能同时定义视频首尾帧。
有参考视频时，sound 只能为 off。
视频格式仅支持 .mp4 / .mov。
视频时长不少于 3 秒，上限与模型版本、视频类型有关。
视频分辨率需在 720px-2160px 范围内。
视频帧率需为 24-60fps，生成结果通常输出为 24fps。
当前最多支持 1 段视频，大小不超过 200MB。

请求示例

json

{
  "model_name": "kling-video-o1",
  "prompt": "参考<<<video_1>>>的运镜方式，生成下一个镜头",
  "video_list": [
    {
      "video_url": "https://example.com/source.mp4",
      "refer_type": "feature",
      "keep_original_sound": "yes"
    }
  ],
  "mode": "pro",
  "sound": "off"
}

image_list

参数名	类型	必填	默认值	说明
`image_list`	array	否	无	参考图列表，可用于主体、场景、风格参考，也可作为首帧或尾帧生成视频。

子参数

参数名	类型	必填	默认值	说明
`image_url`	string	是	无	图片 URL 或 Base64 字符串。不能为空。
`type`	string	否	无	帧类型。`first_frame` 表示首帧，`end_frame` 表示尾帧。非首尾帧参考图请不要配置该字段。

参数规则

type=first_frame 表示首帧图，type=end_frame 表示尾帧图。
暂不支持仅尾帧；如果传入尾帧图，必须同时传入首帧图。
首帧或首尾帧生视频时，不能同时使用视频编辑功能。
图片支持 URL 或 Base64；使用 Base64 时不要添加 data:image/...;base64, 前缀。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不超过 10MB。
图片宽和高都不能小于 300px。
图片宽高比需在 1:2.5 ~ 2.5:1 之间。
image_url 参数值不能为空。

数量限制

无参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 7。
无参考视频且有视频主体时，参考图片数量与多图主体数量之和不得超过 4。
有参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 4。
使用 kling-video-o1 模型时，如果 image_list 超过 2 张图片，不支持设置首尾帧。

请求示例

普通参考图：

json

{
  "model_name": "kling-video-o1",
  "prompt": "参考<<<image_1>>>中的人物，在城市街头行走",
  "image_list": [
    {
      "image_url": "https://example.com/person.png"
    }
  ],
  "mode": "pro",
  "aspect_ratio": "16:9",
  "duration": "5"
}

首尾帧：

json

{
  "model_name": "kling-video-o1",
  "prompt": "让人物从首帧动作自然过渡到尾帧姿态",
  "image_list": [
    {
      "image_url": "https://example.com/first.png",
      "type": "first_frame"
    },
    {
      "image_url": "https://example.com/end.png",
      "type": "end_frame"
    }
  ],
  "mode": "pro"
}

element_list

参数名	类型	必填	默认值	说明
`element_list`	array	否	无	主体参考列表，基于主体库中的主体 ID 配置。可在 Prompt 中通过 `<<<element_1>>>`、`<<<element_2>>>` 等方式引用。

子参数

参数名	类型	必填	默认值	说明
`element_id`	long	是	无	主体库中的主体 ID。不能为空。

请求格式

json

{
  "element_list": [
    {
      "element_id": 123456789
    },
    {
      "element_id": 987654321
    }
  ]
}

参数规则

主体分为视频定制主体（视频角色主体）和图片定制主体（多图主体），不同主体类型适用范围不同。
当使用首帧或首尾帧生成视频时，kling-v3-omni 最多支持 3 个主体。
当使用首尾帧生成视频时，kling-video-o1 不支持主体。
无参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 7。
无参考视频且仅有视频角色主体时，视频角色主体数量不得超过 3。
无参考视频且同时有视频角色主体和多图主体时，视频角色主体数量不得超过 3，参考图片数量与多图主体数量之和不得超过 4。
有参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 4。
有参考视频时，不支持使用视频角色主体。

watermark_info

参数名	类型	必填	默认值	说明
`watermark_info`	object	否	服务商默认	是否同时生成含水印的结果。通过 `enabled` 字段控制。暂不支持自定义水印。

子参数

参数名	类型	必填	默认值	说明
`enabled`	boolean	是	无	`true` 表示生成含水印结果，`false` 表示不生成含水印结果。

请求格式

json

{
  "watermark_info": {
    "enabled": false
  }
}

sound

生成视频时是否同时生成声音。

取值	说明
`on`	生成声音
`off`	不生成声音

默认值为 off。有参考视频时，sound 参数值只能为 off。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高，通常输出 720P。
`pro`	专家模式，高品质模式，通常输出 1080P。
`4k`	4K 模式，高表现模式，通常输出 4K。

默认值为 pro。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

aspect_ratio

生成视频的画面纵横比。

取值
`16:9`
`9:16`
`1:1`

未使用首帧参考或视频编辑功能时，当前参数必填。图生视频、首尾帧、视频编辑等场景下，画幅支持范围以服务商实际能力为准。

duration

生成视频时长，单位为秒。

默认值为 5。使用视频编辑功能时，即 video_list[].refer_type=base，输出结果与传入视频时长相同，此时当前参数无效，并按输入视频时长四舍五入取整计量计费。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。单用户下需保证唯一。

查询任务

查询单个

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video/{task_id}`	GET	application/json	application/json

查询列表

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video?pageNum=1&pageSize=30`	GET	application/json	application/json

关键约束

多镜头开启时，shot_type 与 multi_prompt 需满足组合规则。
有 video_list 且 refer_type=base 时，上游 Omni 会按“视频编辑/指令变换”场景处理；请求路径仍为 /v1/videos/kling/omni-video，但时长/比例等参数会受到视频编辑场景限制。
Kling-Video-O1、Kling-V3-Omni 应优先走本路径；若走 text2video/image2video 路径可能返回 422。

请求示例

json

{
  "model_name": "kling-v3-omni",
  "multi_shot": true,
  "shot_type": "customize",
  "prompt": "",
  "multi_prompt": [
    { "index": 1, "prompt": "镜头一：夜晚街灯下对话", "duration": "2" },
    { "index": 2, "prompt": "镜头二：森林中奔跑", "duration": "3" }
  ],
  "image_list": [
    { "image_url": "https://example.com/1.png" }
  ],
  "mode": "pro",
  "sound": "on",
  "aspect_ratio": "16:9",
  "duration": "5",
  "callback_url": "",
  "external_task_id": ""
}

返回结构示例

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

Vidu

创建视频任务

任务管理

其他任务

可灵 AI

MiniMax

可灵 Omni API 文档 ​

创建任务 ​

请求头 ​

请求体参数 ​

multi_shot ​

shot_type ​

prompt ​

multi_prompt 元素 ​

video_list 元素 ​

子参数 ​

参数规则 ​

请求示例 ​

image_list ​

子参数 ​

参数规则 ​

数量限制 ​

请求示例 ​

element_list ​

子参数 ​

请求格式 ​

参数规则 ​

watermark_info ​

子参数 ​

请求格式 ​

sound ​

mode ​

aspect_ratio ​

duration ​

callback_url ​

external_task_id ​

查询任务 ​

查询单个 ​

查询列表 ​

关键约束 ​

请求示例 ​

返回结构示例 ​

查询任务返回示例（单个） ​

查询任务返回示例（列表） ​

可灵 Omni API 文档

创建任务

请求头

请求体参数

multi_shot

shot_type

prompt

multi_prompt 元素

video_list 元素

子参数

参数规则

请求示例

image_list

子参数

参数规则

数量限制

请求示例

element_list

子参数

请求格式

参数规则

watermark_info

子参数

请求格式

sound

mode

aspect_ratio

duration

callback_url

external_task_id

查询任务

查询单个

查询列表

关键约束

请求示例

返回结构示例

查询任务返回示例（单个）

查询任务返回示例（列表）