Omni 视频

创建 Kling 兼容多模态 Omni 视频任务。

Create Task

Request

POST /v1/videos/omni-video

字段	类型	必填	支持值与限制	说明
model_name	string	是	kling-v3-omni	Omni 视频生成模型。当前只支持这一模型值。
multi_shot	boolean	否	true、false	是否生成多镜头视频，默认 false。当 multi_shot=true 时，prompt 无效；当 multi_shot=false 时，shot_type 和 multi_prompt 无效。
shot_type	string	否	仅支持 customize	当 multi_shot=true 时必填；当 multi_shot=false 时该字段无效。当前仅支持自定义分镜，intelligence 不支持。
prompt	string	否	最长 2500 字符	当 multi_shot=false 时必填；当 multi_shot=true 时该字段无效。可在提示词中通过 <<<image_1>>>、<<<element_1>>>、<<<video_1>>> 引用输入内容。
multi_prompt	array	否	1 到 6 项	当 multi_shot=true 且 shot_type=customize 时必填；当 multi_shot=false 时该字段无效，用于逐镜头定义提示词和时长。
multi_prompt[].index	integer	是	从 1 开始递增	分镜序号。
multi_prompt[].prompt	string	是	最长 512 字符	当前分镜的提示词。
multi_prompt[].duration	string	是	每段至少 1 秒	当前分镜时长，所有分镜时长之和必须等于总 duration。
image_list	array	否	支持图片 URL 或原始 Base64	参考图列表，可用于主体、场景、风格参考，也可作为首帧/尾帧。使用尾帧时必须同时有首帧；使用首帧或首尾帧生成视频时，不能使用视频编辑功能。
image_list[].image_url	string	是	.jpg、.jpeg、.png；不超过 10MB	图片 URL 或原始 Base64。图片宽高不小于 300px，宽高比需在 1:2.5 到 2.5:1 之间。
image_list[].type	string	否	first_frame、end_frame	图片帧类型。若使用尾帧，必须同时有首帧，不支持只传尾帧。参考图片超过 2 张时，不支持设置尾帧。
element_list	array	否	按场景限制使用	参考主体列表，适合在视频中保持角色或主体一致性。使用首帧或首尾帧时最多支持 3 个主体；有参考视频时，参考图片数量和参考主体数量之和不得超过 4，且不支持视频角色主体；无参考视频时，参考图片数量和参考主体数量之和不得超过 7。
element_list[].element_id	integer	是	已存在的主体 ID	主体库中的主体 ID。
video_list	array	否	最多 1 段视频	参考视频列表，可做视频参考或视频编辑输入。使用 refer_type=base 时不能定义视频首尾帧；有参考视频时，sound 只能为 off。
video_list[].video_url	string	是	MP4、MOV	视频 URL。视频时长不少于 3 秒，大小不超过 200MB，宽高需在 720px 到 2160px 之间，帧率需在 24fps 到 60fps 之间。使用视频参考能力时，仅支持 3 到 10 秒。
video_list[].refer_type	string	否	feature、base	feature 表示参考视频；base 表示以该视频作为编辑输入。默认 base。
video_list[].keep_original_sound	string	否	yes、no	是否保留输入视频原声。该参数对 feature 参考视频同样生效。
sound	string	否	on、off	是否同时生成音频，默认 off。当传入 video_list 时，只能使用 off。
mode	string	否	std、pro	生成模式。std 为标准模式；pro 为高质量模式，默认 pro。4k 不支持。
aspect_ratio	string	否	16:9、9:16、1:1	未使用首帧参考、也未使用视频编辑时，建议必传。
duration	string	否	3 到 15	视频总时长，单位秒。若 video_list[].refer_type=base，输出时长跟随输入视频，此字段不生效。
watermark_info	object	否	{"enabled": boolean}	是否同时返回带水印结果。
external_task_id	string	否	自定义字符串	自定义任务 ID，可用于后续查询；同一账号下应保持唯一。

当请求包含 video_list 时，应将 sound 设为 off。

Response

{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123",
  "data": {
    "task_id": "sg_vid_xxxxxxxx",
    "task_status": "submitted",
    "created_at": 1776209922,
    "updated_at": 1776209922
  }
}

Example

基础示例

curl -sS "https://api.exchangetoken.ai/v1/videos/omni-video" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-omni",
    "prompt": "让 <<<image_1>>> 走过霓虹展厅，整体氛围参考 <<<video_1>>>",
    "image_list": [
      {"image_url": "https://example.com/character.png"}
    ],
    "video_list": [
      {"video_url": "https://example.com/reference.mp4", "refer_type": "feature", "keep_original_sound": "no"}
    ],
    "mode": "pro",
    "sound": "off",
    "aspect_ratio": "16:9",
    "duration": "7"
  }'

首尾帧示例

curl -sS "https://api.exchangetoken.ai/v1/videos/omni-video" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-omni",
    "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",
    "sound": "off",
    "duration": "5"
  }'

Query Task

Request

GET /v1/videos/omni-video/{task_id}

后续轮询使用 data.task_id。

Response

{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123",
  "data": {
    "task_id": "sg_vid_xxxxxxxx",
    "task_status": "succeed",
    "watermark_info": {
      "enabled": false
    },
    "task_result": {
      "videos": [
        {
          "url": "https://example.com/output.mp4"
        }
      ]
    },
    "created_at": 1776209922,
    "updated_at": 1776210072
  }
}

状态枚举

task_status	含义
submitted	任务已接受，尚未开始执行。
processing	任务排队中或执行中。
succeed	任务完成，可能包含 task_result.videos。
failed	任务失败或已取消。若存在 task_status_msg，可查看失败原因。

Example

curl -sS "https://api.exchangetoken.ai/v1/videos/omni-video/sg_vid_xxxxxxxx" \
  -H "Authorization: Bearer sk-xxxxxx"