Kling 3.0 Omni

模型标识为 kling-3.0-omni，支持文生视频、首帧、首尾帧、参考生成和视频编辑。使用独立的 Kling 新版协议入口；现有 Kling 3.0 接口保持不变。

各场景的积分单价见积分说明。

创建任务

使用 POST https://api.aivideoapi.ai/omni-video/kling-3.0-omni，通过 Authorization: Bearer YOUR_PLATFORM_API_KEY 传入平台 API Key，请求正文为 JSON。

contents 中提示词使用 type="prompt" 和 text，每个任务最多一项提示词。媒体使用 type 和 url，可选 id；提示词中用 @id 引用对应素材。图片接受 HTTP(S) URL 或 PNG/JPEG Base64，视频接受 MP4/MOV 的 HTTP(S) URL。素材 URL 必须能由外部视频生成服务直接下载，不能要求登录。

下面的 example.com 素材、回调和结果地址均为占位示例。提交前请替换素材及回调地址：素材须满足上述下载要求，回调地址须可从平台 API 服务运行环境访问；HTTP(S) URL 中不得包含用户名或密码。结果地址以接口实际返回为准。除第一个完整 cURL 示例外，其余 JSON 示例均为同一创建接口的请求正文。

文生视频

生成一段 5 秒视频，并同步生成音频。watermark_info.enabled=true 表示同时提供普通视频和水印视频；callback_url 用于接收任务完成通知。

curl -X POST 'https://api.aivideoapi.ai/omni-video/kling-3.0-omni' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {"type": "prompt", "text": "一只小猫在月光下穿过花园，镜头缓慢跟随，伴随轻柔的脚步声和虫鸣。"}
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "aspect_ratio": "16:9",
      "audio": "native",
      "multi_shot": true
    },
    "options": {
      "external_task_id": "omni-text-001",
      "callback_url": "https://app.example.com/webhooks/kling",
      "watermark_info": {"enabled": true}
    }
  }'

首帧图生视频

使用一张图片作为起始画面。画幅跟随首帧素材，以下示例生成无音频的连续镜头。

{
  "contents": [
    {"type": "prompt", "text": "从 @start 的画面开始，人物轻轻转头看向窗外，窗帘随风摆动，镜头缓慢推进。"},
    {"type": "first_frame", "id": "start", "url": "https://media.example.com/window-start.jpg"}
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "audio": "off",
    "multi_shot": false
  },
  "options": {"external_task_id": "omni-first-frame-001"}
}

首尾帧图生视频

同时指定起始画面和结束画面，描述两张图片之间的动作或运镜。

{
  "contents": [
    {"type": "prompt", "text": "从 @start 平滑过渡到 @end，花苞逐渐绽放，保持花盆和背景位置一致。"},
    {"type": "first_frame", "id": "start", "url": "https://media.example.com/flower-start.jpg"},
    {"type": "last_frame", "id": "end", "url": "https://media.example.com/flower-end.jpg"}
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "off",
    "multi_shot": false
  },
  "options": {"external_task_id": "omni-first-last-001"}
}

图片参考生成

用不同图片提供角色、物体或场景参考。仅使用图片参考时，最多传入 7 张 refer_image；每个素材的 id 在本次请求内必须唯一。

{
  "contents": [
    {"type": "prompt", "text": "让 @cat 中的小猫在 @garden 的花园里奔跑，保持小猫的毛色和外形，阳光温暖自然。"},
    {"type": "refer_image", "id": "cat", "url": "https://media.example.com/cat.jpg"},
    {"type": "refer_image", "id": "garden", "url": "https://media.example.com/garden.jpg"}
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "aspect_ratio": "9:16",
    "audio": "off",
    "multi_shot": true
  },
  "options": {"external_task_id": "omni-image-reference-001"}
}

视频参考生成

使用 feature_video 参考动作或运镜，并可加入最多 4 张参考图片，或加入 1 张首帧。以下示例根据参考视频的动作生成一段新的 8 秒视频。

视频参考要求 audio="off"，输出时长为 3–10 秒，不支持显式分镜提示词。

{
  "contents": [
    {"type": "prompt", "text": "让 @character 中的人物参考 @motion 的动作节奏，在舞台上完成转身，保持人物外观一致。"},
    {"type": "feature_video", "id": "motion", "url": "https://media.example.com/dance-reference.mp4"},
    {"type": "refer_image", "id": "character", "url": "https://media.example.com/character.jpg"}
  ],
  "settings": {
    "resolution": "720p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": true
  },
  "options": {"external_task_id": "omni-video-reference-001"}
}

视频编辑

使用 base_video 指定待编辑视频，可加入最多 4 张参考图片。必须显式传入 multi_shot=false；audio="original" 保留原声，改为 off 可关闭原声。

输入视频应为 3–15.5 秒。输出时长和画幅跟随输入视频，以下示例省略 duration 和 aspect_ratio。

{
  "contents": [
    {"type": "prompt", "text": "将 @source 中人物的外套替换成 @coat 的红色外套，保持人物动作、面部和背景不变。"},
    {"type": "base_video", "id": "source", "url": "https://media.example.com/person-original.mp4"},
    {"type": "refer_image", "id": "coat", "url": "https://media.example.com/red-coat.jpg"}
  ],
  "settings": {
    "resolution": "1080p",
    "audio": "original",
    "multi_shot": false
  },
  "options": {
    "external_task_id": "omni-edit-001",
    "callback_url": "https://app.example.com/webhooks/kling"
  }
}

显式分镜生成

普通提示词配合 multi_shot=true 会使用智能分镜。需要明确安排镜头时，可使用 镜头序号, 秒数, 描述; 格式，最多 6 段，序号从 1 连续递增，总秒数必须等于 settings.duration。请保留示例中的英文逗号和分号。

下面的两个镜头分别为 2 秒和 3 秒，总时长为 5 秒。

{
  "contents": [
    {"type": "prompt", "text": "镜头 1, 2, 清晨的森林全景，薄雾穿过树木;镜头 2, 3, 镜头切近，一只小鹿抬头望向阳光;"}
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": true
  },
  "options": {"external_task_id": "omni-shots-001"}
}

创建响应

新任务创建成功后返回任务标识和当前状态。创建响应的 data 是单个对象；id 是平台任务 ID，external_id 对应请求中的 options.external_task_id，未提供时不返回该字段。create_time、update_time 均为毫秒时间戳。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "ad482f86-48ec-4e81-8392-a64351c695b9",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "submitted",
    "create_time": 1789005600000,
    "update_time": 1789005600000,
    "external_id": "omni-text-001"
  }
}

同一用户使用相同外部 ID 和相同参数重试时，返回已有任务及其当前状态，不重复扣费；不同参数复用同一个外部 ID 会报错。每次希望生成新视频时，应使用新的 external_task_id。

参数说明

字段	取值与默认值
`settings.resolution`	`720p`（默认）、`1080p`、`4k`
`settings.duration`	整数 3–15 秒，默认 5；视频参考为 3–10 秒；编辑按输入视频时长生成
`settings.aspect_ratio`	`16:9`（默认）、`9:16`、`1:1`；有首帧或编辑时跟随素材
`settings.audio`	`off`（默认）、`native` 生成音频、`original` 保留编辑视频原声
`settings.multi_shot`	默认 `true`；视频编辑必须显式设置 `false`
`options.watermark_info.enabled`	默认 `false`；开启后同时返回水印视频
`options.callback_url`	可选，可从平台 API 服务运行环境访问的 HTTP(S) 回调地址，推荐 HTTPS；URL 中不得包含用户名或密码
`options.external_task_id`	可选，用户内唯一的外部任务 ID

首帧不能同时混用参考图片，尾帧必须与首帧一起使用；feature_video 和 base_video 不能混用。首期不支持主体 ID 和主体库管理。

平台不前置检查图片大小和提示词长度，也不自动压缩、改写或截断。超限素材仍可能被拒绝，具体错误通过请求响应或任务状态返回。

查询任务

使用 GET https://api.aivideoapi.ai/tasks，携带与创建任务相同账号的平台 API Key。

按平台任务 ID 查询

curl 'https://api.aivideoapi.ai/tasks?task_ids=550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY'

按外部任务 ID 查询

curl 'https://api.aivideoapi.ai/tasks?external_task_ids=omni-text-001,omni-edit-001' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY'

task_ids 和 external_task_ids 必须且只能选一个，均支持英文逗号分隔批量查询。单个任务查询的响应 data 仍为数组。未找到或不属于当前用户的任务不返回；全部未匹配时 data 为 []。

成功返回示例

下面展示文生视频示例完成后的返回体，包含普通视频、水印视频及实际消耗积分。按 1080p、audio="native"、5 秒、默认 1.0 倍率计算，消耗 230.77 积分；实际消耗以任务返回的 billing 为准。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "0bf4d036-c6bd-44d6-9981-9d3efab76f23",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "succeeded",
      "create_time": 1789005600000,
      "update_time": 1789005660000,
      "external_id": "omni-text-001",
      "message": "",
      "outputs": [
        {
          "type": "video",
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "url": "https://media.example.com/results/video-001.mp4?signature=example-video-signature",
          "duration": "5",
          "watermark_url": "https://media.example.com/results/video-001-watermark.mp4?signature=example-watermark-signature"
        }
      ],
      "billing": [
        {"charge_type": "unit", "amount": "230.77", "package_type": "video"}
      ]
    }
  ]
}

处理中返回示例

尚未完成时，outputs 和 billing 均为空数组。billing=[] 不代表未预扣积分，只表示尚未返回最终消耗。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "209511df-a5f2-4681-bc72-ff796e65fef3",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "processing",
      "create_time": 1789005600000,
      "update_time": 1789005630000,
      "external_id": "omni-text-001",
      "message": "",
      "outputs": [],
      "billing": []
    }
  ]
}

失败返回示例

顶层 code=0 表示查询请求成功；生成是否成功应检查每个任务的 status。失败原因位于任务对象的 message 中。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "b3765591-713b-4c2f-bb02-9005388122ef",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "failed",
      "create_time": 1789005600000,
      "update_time": 1789005630000,
      "external_id": "omni-edit-001",
      "message": "The supplied contents or settings could not be processed. Check the text, media and generation settings.",
      "outputs": [],
      "billing": []
    }
  ]
}

状态	含义
`submitted`	已提交，等待处理
`processing`	正在生成或完成结果与积分结算
`succeeded`	生成成功且已完成积分结算，可读取 `outputs` 和 `billing`
`failed`	生成失败，可读取 `message`

outputs[].duration 是以秒为单位的字符串；未开启水印时，不返回 watermark_url。平台保存生成成功记录并完成积分结算后返回 succeeded。

普通视频 url 和可选的 watermark_url 均原样返回生成结果地址，包括签名查询参数；平台不转存结果视频或替换域名。请及时下载并自行保存，地址有效期以实际返回的 URL 为准。任务与积分记录的保留不代表媒体地址永久可下载。

任务回调

配置回调地址

在创建请求中设置 options.callback_url，使用可从平台 API 服务运行环境访问的 HTTP(S) 地址，URL 中不得包含用户名或密码。任务达到 succeeded 或 failed 时，平台向该地址发送 HTTP POST，Content-Type 为 application/json。submitted 和 processing 不发送状态通知。

{
  "options": {
    "external_task_id": "omni-text-001",
    "callback_url": "https://app.example.com/webhooks/kling"
  }
}

这是创建请求中的 options 片段，请与 contents、settings 一起提交。回调地址应直接接收 POST，请勿依赖 HTTP 重定向。

回调正文示例

回调正文直接是单个任务对象，与查询响应 data 数组中的一项结构相同，不包含顶层 code、request_id 或 data 包装。

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "create_time": 1789005600000,
  "update_time": 1789005660000,
  "external_id": "omni-text-001",
  "message": "",
  "outputs": [
    {
      "type": "video",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://media.example.com/results/video-001.mp4?signature=example-video-signature",
      "duration": "5",
      "watermark_url": "https://media.example.com/results/video-001-watermark.mp4?signature=example-watermark-signature"
    }
  ],
  "billing": [
    {"charge_type": "unit", "amount": "230.77", "package_type": "video"}
  ]
}

失败回调同样直接发送任务对象，status="failed"，message 为失败原因，outputs=[]、billing=[]；字段格式与上面的失败查询示例一致。

回调验签

为账号配置独立的 Webhook Secret 后，回调使用 Standard Webhooks 签名。该密钥由平台配置，需向平台获取，不是平台 API Key，也不放入创建请求中。未配置签名密钥时，不发送以下签名头。

请求头	说明
`webhook-id`	事件 ID，同一事件的重试保持不变
`webhook-timestamp`	本次投递的 Unix 秒级时间戳，每次重试重新生成
`webhook-signature`	签名，格式为 `v1,` 加 Base64 编码结果

验签步骤：

读取原始请求正文 rawBody，不要先解析 JSON 再重新序列化。
移除 Webhook Secret 的 whsec_ 前缀，将剩余部分按 Base64 解码为密钥字节。
将 webhook-id、webhook-timestamp 和原始正文用英文句点连接，得到 webhook-id.webhook-timestamp.rawBody。
使用密钥计算该字符串的 HMAC-SHA256，并将结果按 Base64 编码，与签名头中 v1, 后的值做恒定时间比较。
建议检查投递时间戳与服务器当前时间相差不超过 5 分钟，并对事件 ID 去重。

任务对象中的 create_time/update_time 为毫秒，签名头中的 webhook-timestamp 为秒。密钥更新仅影响之后创建的新任务，已有任务使用创建时配置的密钥。

接收与重试

接收端应在 10 秒内返回任意 2xx 状态码确认收到。建议先可靠保存事件，再返回 200 或 204，耗时业务处理放到后台。

非 2xx、网络错误或超时会被视为投递失败：首次失败后等待 3 分钟重试，第二次失败后等待 10 分钟再试，总计最多 3 次投递。

回调可能重复到达。已签名的事件可使用 webhook-id 去重；未配置签名时，可使用任务 id 和终态 status 进行幂等处理，必要时通过查询接口确认任务状态。重复通知也应返回 2xx。

回调失败不改变任务结果或积分结算，客户仍可通过查询接口获取结果。

积分说明

以下基础售价单位为 积分/秒，适用于默认 1.0 倍率。单价展示保留 1 位小数，实际结算使用未舍入的配置单价。

场景与音频模式	720p	1080p	4k
无视频输入，`audio="off"`	23.1	30.8	115.4
无视频输入，`audio="native"`	34.6	46.2	115.4
有视频输入，`audio="off"`	34.6	46.2	115.4
视频编辑保留原声，`audio="original"`	34.6	46.2	115.4

无视频输入包括文生视频、首帧、首尾帧和仅使用图片的参考生成。
有视频输入指传入 feature_video 或 base_video；视频参考仅支持 off，视频编辑支持 off/original。
积分按单价乘以计费秒数计算，四舍五入保留 2 位小数，再乘以账号倍率并四舍五入保留 2 位小数；未配置专属倍率时使用 1.0。
创建任务时预扣积分，生成成功后按实际用量结算；已有任务沿用创建时的单价和倍率。
视频编辑按输入视频时长四舍五入到整数秒预估积分。
视频参考生成只按输出时长预估积分，不额外累计参考视频时长。
最终消耗以成功任务的 billing 为准：该数组返回实际消耗的平台积分，charge_type="unit"、package_type="video"，amount 为小数字符串。
确认生成失败时退款；提交结果不明、结果交付失败或回调失败不会自动退款。
此模型不支持取消任务。

例如：无视频输入、1080p、audio="native"、5 秒、默认 1.0 倍率，按配置单价结算消耗 230.77 积分。