Kling-v3-Omni/多模态视频生成

本文详细介绍 kling-v3-omni 多模态视频生成模型的核心 API（异步提交任务、查询任务状态），包含接口地址、输入输出参数、请求示例、响应示例及错误码说明，为接口调用提供规范指引。该模型支持文本、图像和视频作为多模态输入，可实现文生视频、图片辅助生成、视频编辑及多镜头生成等功能。

1. 认证方式

所有接口均采用 API Key 认证，需在请求头中携带 Authorization 字段，格式如下：

Authorization: <YOUR_API_KEY>

说明：将 \<YOUR\_API\_KEY\> 替换为您实际的 API Key，即可完成身份验证，获取接口调用权限。

2. 异步提交任务接口

该接口用于提交 kling-v3-omni 模型的视频生成异步任务，支持文本、图像、视频多模态输入，提交成功后返回任务唯一标识，用于后续查询任务状态及获取生成结果。

2.1 接口地址

https://api.modelverse.cn/v1/tasks/submit

2.2 输入参数

参数	类型	是否必选	描述
model	string	是	模型名称，固定填写：kling-v3-omni
input.prompt	string	否	提示词，最多 2500 字符；当 multi_shot 为 false 时不能为空。可通过 <<<image_1>>>、<<<video_1>>> 格式引用图片、视频
input.negative_prompt	string	否	反向提示词，最多 2500 字符；建议直接在正向 prompt 中通过否定句添加，无需单独设置
parameters.mode	string	否	生成模式，可选值：std（标准模式，720P）、pro（专业模式，1080P）；默认值：pro
parameters.aspect_ratio	string	条件必选	视频长宽比，可选值：16:9、9:16、1:1；仅在使用视频编辑功能（refer_type: base）时可省略，其他场景均必填
parameters.duration	int	否	视频时长（秒），可选值：3~15，默认 5；使用视频参考时仅支持 3~10 秒；使用视频编辑功能（refer_type: base）时，输出与传入视频时长一致，此参数无效
parameters.sound	string	否	是否生成声音，可选值：on、off；默认值：off；有参考视频时只能为 off
parameters.multi_shot	bool	否	是否启用多镜头模式，默认：false；为 true 时 prompt 无效；为 false 时 shot_type 和 multi_prompt 无效
parameters.shot_type	string	否	镜头类型，当 multi_shot 为 true 时必填，可选值：customize
parameters.multi_prompt	array	否	多镜头提示词列表，当 multi_shot 为 true 且 shot_type 为 customize 时不能为空；最少 1 个镜头，最多 6 个；每个镜头包含：index（镜头序号，从 1 开始）、prompt（提示词，≤512 字符）、duration（时长，≥1 秒且 ≤ 总时长，所有镜头时长之和 = 总时长）
parameters.image_list	array	否	参考图片列表，每个图片项包含：image_url（图片 URL 或 Base64 编码，无前缀）、type（图片类型，可选：first_frame、end_frame）
parameters.video_list	array	否	参考视频列表，最多 1 段；每个视频项包含：video_url（视频 URL）、refer_type（参考类型：feature/特征参考、base/待编辑）、keep_original_sound（是否保留原声：yes/no）；使用视频编辑功能时需设置 refer_type: base
parameters.watermark_enabled	bool	否	是否生成带水印结果，暂不支持自定义水印；默认值：未明确说明（按实际调用为准）
parameters.external_task_id	string	否	自定义任务 ID，单用户下需唯一，不覆盖系统生成 ID，支持通过该 ID 查询任务

2.3 图片格式要求

支持格式：.jpg、.jpeg、.png
文件大小：不超过 10MB
尺寸要求：宽高不小于 300px，宽高比介于 1:2.5 ~ 2.5:1 之间
Base64 编码要求：无需添加 data:image 前缀，直接使用编码字符串

2.4 视频格式要求

支持格式：MP4、MOV
视频时长：不少于 3 秒
宽高尺寸：720px ~ 2160px 之间
帧率：24fps ~ 60fps，生成视频输出为 24fps
文件大小：不超过 200MB

2.5 约束条件

有参考视频时，图片数量 ≤ 4；无参考视频时，图片数量 ≤ 7
图片数量超过 2 时，不支持设置尾帧
有尾帧时，必须同时设置首帧（不可单独设置尾帧）
有参考视频时，sound 参数只能为 off；使用视频编辑功能时，不可设置首尾帧

2.6 请求示例

如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具，避免命令行调用出现兼容问题。

2.6.1 文生视频示例

curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3-omni",
    "input": {
      "prompt": "A beautiful sunset over the ocean with waves gently crashing"
    },
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": "on"
    }
  }'

2.6.2 图片参考 + 首尾帧示例

curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3-omni",
    "input": {
      "prompt": "A girl walking through a garden"
    },
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "image_list": [
        {"image_url": "https://example.com/first_frame.jpg", "type": "first_frame"},
        {"image_url": "https://example.com/last_frame.jpg", "type": "end_frame"}
      ]
    }
  }'

2.6.3 视频编辑（待编辑视频）示例

curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3-omni",
    "input": {
      "prompt": "Add a cinematic color grading effect"
    },
    "parameters": {
      "mode": "pro",
      "video_list": [
        {
          "video_url": "https://example.com/input.mp4",
          "refer_type": "base",
          "keep_original_sound": "yes"
        }
      ]
    }
  }'

2.6.4 多镜头 + 图片引用示例

curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3-omni",
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "<<<image_1>>>A person sitting on a park bench, sunlight filtering through trees", "duration": "2"},
        {"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing", "duration": "3"}
      ],
      "image_list": [
        {"image_url": "https://example.com/person.jpg"}
      ],
      "sound": "on"
    }
  }'

2.7 输出参数

参数	类型	描述
output.task_id	string	异步任务的唯一标识，用于后续查询任务状态
request_id	string	本次请求的唯一标识，用于问题排查

2.8 响应示例

{
  "output": {
    "task_id": "task_id"
  },
  "request_id": "request_id"
}

3. 查询任务状态接口

该接口用于查询已提交异步任务的执行状态、生成结果、任务耗时等信息，需传入异步提交任务时返回的 task_id。

3.1 接口地址

https://api.modelverse.cn/v1/tasks/status?task_id=<task_id>

说明：将 \<task\_id\> 替换为异步提交任务接口返回的实际 task_id。

3.2 输入参数

参数	类型	是否必选	描述
task_id	string	是	异步任务的唯一标识，由异步提交任务接口返回

3.3 请求示例

curl --location 'https://api.modelverse.cn/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'

3.4 输出参数

参数	类型	描述
output.task_id	string	异步任务的唯一标识，与查询时传入的 task_id 一致
output.task_status	string	任务状态，可选值：Pending（待处理）、Running（执行中）、Success（成功）、Failure（失败）
output.urls	array	视频结果的 URL 列表，仅当 task_status 为 Success 时返回
output.submit_time	integer	任务提交时间戳（单位：秒）
output.finish_time	integer	任务完成时间戳（单位：秒），仅当 task_status 为 Success 或 Failure 时返回
output.error_message	string	任务失败时返回的错误信息，仅当 task_status 为 Failure 时返回
usage.duration	integer	视频时长（秒）
request_id	string	本次查询请求的唯一标识，用于问题排查

3.5 响应示例

3.5.1 成功响应示例

{
  "output": {
    "task_id": "task_id",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx.mp4"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}

3.5.2 失败响应示例

{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}

4. 错误码说明

错误码	描述
006001094	任务资源不足
006001095	任务响应错误
006001099	任务创建错误