Skip to main content
POST
/
kling
/
v1
/
videos
/
omni-video
curl --request POST \
  --url https://api.deerapi.com/kling/v1/videos/omni-video \
  --header 'Authorization: Bearer <DEERAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "让 <<<image_1>>> 里的人物朝镜头挥手，然后转身看向远处的城市灯光。",
    "image_list": [
      {"image_url": "https://example.com/omni-reference.png"}
    ],
    "duration": "5",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "callback_url": "https://example.com/kling/callback"
  }'
{
  "code": 123,
  "message": "<string>",
  "request_id": "<string>",
  "data": {
    "task_id": "<string>",
    "task_status": "<string>",
    "task_info": {
      "external_task_id": "<string>"
    },
    "created_at": 123,
    "updated_at": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://apidoc.deerapi.com/llms.txt

Use this file to discover all available pages before exploring further.

/kling/v1/videos/omni-video 适合把文字、图片、元素和视频素材组合进同一个视频任务。需要多模态引用、首尾帧、参考视频或更复杂叙事时，用这页比普通文生/图生视频更合适。

​
推荐流程

1

先做一版最小任务

首个请求先保留 prompt。需要固定模型版本时，再补 model_name；需要明确时长和比例时，再加 duration、aspect_ratio。
2

引用素材时让 prompt 和列表一一对应

当你开始使用 image_list、element_list 或 video_list 时，在 prompt 里用 <<<image_1>>>、<<<element_1>>>、<<<video_1>>> 这类占位符去引用对应素材。
3

遵守素材组合限制

按当前 schema，有参考视频时，图片数与元素数之和不能超过 4；没有参考视频时不能超过 7。超过 2 张图片时，不支持再设置末帧；如果有末帧，必须同时提供首帧。
4

需要多镜头时切换到 v3-omni

设置 model_name: "kling-v3-omni" 并开启 multi_shot: true。customize 模式下用 multi_prompt 手动定义每个镜头；intelligence 模式下只需提供全局 prompt，系统自动分镜。
5

用专用查询页取结果

Omni 任务提交后优先走 Omni 查询，或者在创建时直接配置 Callback 协议。
kling_omni_video 是 DeerAPI capability，不是 model_name。另外，prompt 里的占位符顺序必须和素材列表顺序对得上。

​
模型版本

特性kling-video-o1（默认）kling-v3-omni
多镜头 (multi_shot)❌✅ 最多 6 镜头
最长时长10 s15 s
同步音效 (sound)✅✅
首尾帧✅❌（多镜头模式下）
参考视频✅❌（多镜头模式下）
不传 model_name 时默认使用 kling-video-o1。切换到 kling-v3-omni 后即可启用多镜头模式。

​
多镜头模式

使用 kling-v3-omni 并设置 multi_shot: true 可将一个任务拆分为多个镜头。

​
分镜类型

shot_type说明promptmulti_prompt
customize自定义分镜，手动描述每个镜头无效（被 multi_prompt 替代）必填，最多 6 个镜头
intelligence智能分镜，系统自动拆分必填（作为全局描述）不需要

​
核心参数

参数类型说明
multi_shotbooleantrue 开启多镜头
shot_typestringcustomize 或 intelligence，多镜头时必填
multi_promptarray镜头列表，每项含 index、prompt（≤512 字符）、duration
durationstring全局总时长（3–15 秒），各镜头 duration 之和必须等于此值
soundstringon / off，是否同步生成音效；存在 video_list 时只能为 off

​
多镜头避坑指南

  1. 多镜头不支持参考视频：multi_shot: true 时不能传 video_list，只能使用图片或纯文字。
  2. 各镜头时长之和 = 全局 duration：例如 3 个镜头分别 2+2+1=5，全局 duration 必须为 "5"。
  3. 不要在多镜头里设首末帧：multi_shot: true 时 image_list 中的 type: first_frame / end_frame 无效，图片只能通过 <<<image_N>>> 在 multi_prompt 中引用。
  4. customize 模式下全局 prompt 无效：每个镜头的描述完全由 multi_prompt 控制。只有 intelligence 模式才使用全局 prompt。

​
什么时候更适合改用别的页

​
相关页面

Omni 查询

Omni 任务提交后，优先使用专用查询页，而不是通用查询接口。

图生视频

只有一张首帧或只做首尾帧控制时更轻量。

多图参考生视频

主要目标是多图一致性，而不是多模态混合时改走这里。

Kling Omni 用户指南

需要了解更多多模态能力边界和引用方式时可继续查看。

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Use your DeerAPI key.

Headers

​
Content-Type
string

Body

application/json

请求体沿用官方 Kling 字段语义；其中 model_name 仍然是官方模型枚举，而不是 DeerAPI live capability ID。

​
prompt
string
default:Hello
required

文本提示词，可以包含正向和负向描述。

  • 提示词可以进行模板化，以满足不同的视频生成需求。

  • 不得超过 2,500 个字符。

💡

Omni 模型可以通过包含元素、图像、视频及其他内容的 Prompt 来实现多种能力。

  1. 以 <<<>>> 的格式指定一个元素、图像或视频，例如 <<<element_1>>>、<<<image_1>>>、<<<video_1>>>。

  2. 能力范围可在用户手册中查看：KLING Omni 模型用户指南。

  • 当 multi_shot 为 false 时，此字段为主提示词（必填）。
  • 当 multi_shot 为 true 且 shot_type 为 customize 时，此字段无效（各镜头内容由 multi_prompt 描述）。
  • 当 multi_shot 为 true 且 shot_type 为 intelligence 时，此字段为必填（系统自动分镜）。
​
model_name
string

官方模型枚举

  • kling-video-o1：Omni Video O1 模型（默认值）
  • kling-v3-omni：V3 Omni 模型，支持多镜头（multi_shot）、更长时长等能力

不同模型支持的能力范围不同，详见能力地图。

​
multi_shot
boolean

是否开启多镜头模式

  • true：开启多镜头，需同时提供 shot_type。当 shot_type 为 customize 时还需提供 multi_prompt。此时全局 prompt 无效（被 multi_prompt 替代），且不支持设置首末帧。
  • false 或不传：单镜头模式（默认行为），此时 shot_type 和 multi_prompt 无效。

⚠️ 开启多镜头时，不能传 video_list（参考视频），只能使用图片或纯文字。

​
shot_type
string

镜头类型（仅在 multi_shot: true 时生效，且为必填）

  • 枚举值：customize（自定义分镜）、intelligence（智能分镜）
  • customize 模式下需同时提供 multi_prompt。
  • intelligence 模式下需提供全局 prompt（不能为空），无需 multi_prompt。
​
multi_prompt
object[]

多镜头提示词列表（仅在 multi_shot: true 且 shot_type: customize 时生效，且为必填）

  • 每个元素描述一个镜头，包含序号、提示词和时长。
  • 最多 6 个镜头，最少 1 个。
  • 单个镜头 prompt 最大长度 512 字符。
  • 各镜头 prompt 可使用 <<<image_N>>>、<<<video_N>>> 引用 image_list / video_list 中对应位置的素材。
  • 每个镜头 duration 不得超过全局 duration，且必须 ≥ 1。
  • 所有镜头的 duration 之和必须等于全局 duration。
​
sound
string

是否在生成视频时同步生成音效

  • 枚举值：on、off
  • 默认值：off
  • on：为生成的视频自动配音效/音乐。
  • off：不生成音效。

⚠️ 当存在参考视频（video_list 非空）时，sound 只能为 off。

不同模型版本和视频模式的支持范围有所不同，详见能力地图。

​
image_list
object[]

参考图像列表

  • 包含元素、场景、风格等的参考图像，也可用作生成视频的首帧或末帧；当作为首帧或末帧生成视频时：

  • 使用 type 参数定义图像位于首帧还是末帧：first_frame 表示首帧，end_frame 表示末帧。

  • 目前不支持仅设置末帧，这意味着当存在末帧图像时，必须同时存在首帧图像。

  • 当正在生成视频的首帧或末帧时，无法使用视频编辑功能。

  • 通过 key:value 的方式加载，具体如下：

"image_list":[
  {
    "image_url":"image_url",
    "type":"first_frame"
  },
  {
    "image_url":"image_url",
    "type":"end_frame"
  }
]

  • 支持输入图像的 Base64 编码或图像 URL（需确保可访问）。

  • 支持的图像格式包括 .jpg / .jpeg / .png。

  • 图像文件大小不能超过 10MB，图像的宽高尺寸不得小于 300px，且图像的宽高比应在 1:2.5 ~ 2.5:1 之间。

  • 参考图像的数量与是否存在参考视频以及参考元素的数量有关：

  • 当存在参考视频时，参考图像数量与参考元素数量之和不得超过 4；

  • 当不存在参考视频时，参考图像数量与参考元素数量之和不得超过 7；

  • 当图像数量超过 2 张时，不支持设置末帧；

  • image_url 参数的值不能为空。

在多镜头模式下，image_list 中的图像通过 multi_prompt 中的 <<<image_N>>> 按顺序引用。

​
element_list
object[]

参考元素列表

  • 基于元素 ID 配置。以 key:value 方式加载，详情如下：
"element_list":[

{

"element_id":long

}

]

  • 参考元素的数量与是否存在参考视频以及参考图片的数量有关：

  • 当存在参考视频时，参考图片数量与参考元素数量之和不得超过 4；

  • 当不存在参考视频时，参考图片数量与参考元素数量之和不得超过 7；

​
mode
string

视频生成模式

  • 枚举值：std，pro

  • std：标准模式，具有较高的性价比

  • pro：专业模式，生成的视频时长更长，但视频输出质量更高

不同模型版本和视频模式的支持范围有所不同。更多详情请参阅当前文档的“3-0 能力地图”。

​
aspect_ratio
string

生成的视频帧的宽高比（宽：高）

  • 枚举值：16:9、9:16、1:1

  • 当未使用首帧参考或视频编辑功能时，此参数为必填项。

​
duration
string

视频长度，单位：秒（s）

  • 枚举值：3，4，5，6，7，8，9，10，11，12，13，14，15

  • 使用文本生成视频和首帧图片生成视频时（不含首末帧）：可选 3~10 秒。

  • 使用视频编辑功能（"refer_type": "base"）时，输出结果与输入视频的时长相同，当前参数无效。计费时将输入视频时长四舍五入到最接近的整数。

  • 在多镜头模式中，此字段为全局总时长，multi_prompt 中各镜头 duration 之和必须等于此值。

  • 不同模型版本和视频模式支持的时长范围不同，详见能力地图。

​
video_list
object[]

参考视频，获取已上传视频的链接。

  • 可作为功能参考视频或待编辑视频使用，默认作为待编辑视频；可选择性保留视频原声。

  • 根据 refer_type 参数区分参考视频类型：feature 为功能参考视频，base 为待编辑视频。

  • 当参考视频为待编辑视频时，无法定义视频的起始帧和结束帧。

  • 通过参数 keep_original_sound 选择是否保留视频原声，yes 表示保留，no 表示不保留；当前参数同样适用于功能参考视频。

  • 以 key:value 方式加载，详情如下：

"video_list":[
  {
    "video_url":"video_url",
    "refer_type":"base",
    "keep_original_sound":"yes"
  }
]

  • 仅支持 .mp4/.mov 格式。

  • 仅支持时长 ≥ 3 秒且 ≤ 10 秒的视频。

  • 视频分辨率的宽和高必须在 720px 到 2160px（含）之间。

  • 仅支持 24 ~ 60 fps 的视频，输出结果为 24fps。

  • 仅支持上传 1 个视频，且视频大小不超过 200MB。

  • video_url 参数的值不能为空。

⚠️ 多镜头模式（multi_shot: true）下不能传 video_list。

​
watermark_info
object

是否同时生成带水印的结果

  • 通过 enabled 参数控制：true 生成带水印结果，false 不生成。
  • 暂不支持自定义水印。
​
callback_url
string

该任务结果的回调通知地址。如果已配置，当任务状态发生变化时，服务器将主动进行通知

  • 通知的具体消息结构可参见《回调协议》
​
external_task_id
string

自定义任务 ID 用户可以提供一个自定义任务 ID，该 ID 不会覆盖系统生成的任务 ID，但可用于任务查询。请注意，自定义任务 ID 必须在单个用户账号内保持唯一。

Response

200 - application/json

任务已受理，返回 task_id。后续请通过 Omni 查询页或 callback 获取最终视频结果。

​
code
integer
required

返回码。

​
message
string
required

错误信息或成功说明。

​
request_id
string
required

请求唯一标识。

​
data
object
required