Kling 4.0

Kling 4.0 支持文生视频、多关键帧图生视频、混合素材参考和视频编辑，输出 720p 或 1080p、3–30 秒视频。通过统一接口创建异步任务，再使用任务 ID 查询或接收完成回调。

价格与预扣

输出计费时长 O 取值如下：显式传入 input.settings.duration 时，使用用户指定的时长；省略时，使用实际输出时长。I 始终为实际输入视频总时长（含视频角色主体）：

• 无视频输入：计费秒数为 O。
• 有视频输入：计费秒数为 O + max(I, O)。当 I ≤ O 时为 2 × O；当 I > O 时为 I + O。
• 最终积分为 round2(round2(单价 × 计费秒数) × 账号倍率)；实际时长可含小数，积分最多保留两位小数。

720p、账号倍率为 1、输出计费时长 O = 10 秒的示例：

例如，指定 duration: 10、1080p、无视频输入、账号倍率为 1 时，即使实际视频为 10.041 秒，仍按 10 秒结算 585.90 积分；实际时长保留在 usage.output_seconds 中。

创建任务时先预扣：显式时长按指定输出秒数预留，自动时长按最多 30 秒输出预留。有视频或主体时，还按最多 30 秒输入时长预留，并覆盖素材类型尚未确认的情况。成功后按上述时长规则和确认的素材类型结算，未使用的预扣差额只退还一次。

自动时长、账号倍率为 1 时，无视频和无主体输入的预扣为 720p 1171.80、1080p 1757.70 积分；有视频或主体时分别为 1406.40、2109.60 积分。图片主体最终按无视频输入计费，预扣可能高于最终金额。

价格与账号倍率在创建时固定。明确失败退还预扣；生成已成功但用量仍待核对时继续保留任务，不按失败全额退款。最终以 completed 任务的 credits_consumed 为准。

接口与认证

三个模型均使用 POST https://api.aivideoapi.ai/v1/videos/generations。请求头传入平台 API Key：

Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

callback_url 放在最外层，与 model、input 同级。不要放入 input.options；此接口不接受 external_task_id。请保存返回的 taskId，在自己的业务记录中建立关联。

以下 JSON 示例均为完整请求体，发送到同一个生成接口。示例素材和回调地址需替换为可公开访问的实际地址。

文生视频

input.prompt 必填且非空；此模型不接受 input.contents。下面的示例生成 10 秒、1080p 横屏视频，并请求额外的水印版本：

curl -X POST 'https://api.aivideoapi.ai/v1/videos/generations' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0-text-to-video",
    "input": {
      "prompt": "清晨的湖面，镜头缓慢推进，薄雾散开，伴随轻柔的水声。",
      "settings": { "resolution": "1080p", "duration": 10, "aspect_ratio": "16:9" },
      "options": { "watermark_info": { "enabled": true } }
    },
    "callback_url": "https://app.example.com/webhooks/video"
  }'

自动决定时长时，省略 settings.duration：

{
  "model": "kling-4.0-text-to-video",
  "input": {
    "prompt": "生成一段 15 秒的视频：日落时分，帆船缓缓驶过海湾。",
    "settings": { "resolution": "720p" }
  }
}

多关键帧图生视频

input.contents 至少包含一张图片，可选一个 prompt 项。支持 first_frame、middle_frame、last_frame，合计最多 10 张；首帧和尾帧各最多一张。输出比例由图片决定，不传 settings.aspect_ratio。

{
  "model": "kling-4.0-image-to-video",
  "input": {
    "contents": [
      { "type": "prompt", "text": "从 @start 平滑过渡到 @middle，最后停留在 @end，保持人物外观一致。" },
      { "type": "first_frame", "url": "https://media.example.com/start.jpg", "id": "start" },
      { "type": "middle_frame", "url": "https://media.example.com/middle.jpg", "id": "middle" },
      { "type": "last_frame", "url": "https://media.example.com/end.jpg", "id": "end" }
    ],
    "settings": { "resolution": "720p", "duration": 10 }
  }
}

只传一张 first_frame 也可以，不必填写提示词。图生模型不接受 input.prompt、refer_image、视频、主体或音色；需要这些参考类型时使用 Omni。

Omni 参考与视频编辑

input.contents 是非空数组，最多包含一个 prompt 项。素材的 id 用于提示词中的 @id 引用，同一请求内不能重复。

图片和视频的 id 通常可选；在 Omni 中传入多张 middle_frame 或多张 refer_image 时，对应的每张图片都必须填写 id。主体和音色始终要求 id；它是本次请求中的引用名称，与已有的 element_id、voice_id 不同。

视频与视频角色主体合计最多 5 个；所有图片、视频、主体和音色合计最多 15 个，不计提示词。视频角色主体同时占用主体和视频数量限额，在 15 个素材总数中只计一次。此生成接口只引用已有可用主体和音色，不提供创建或管理接口。

编辑已有视频

下面示例省略输出时长，使用待编辑视频和图片参考。提示词应说明修改内容和需要保留的内容：

{
  "model": "kling-4.0-omni",
  "input": {
    "contents": [
      { "type": "prompt", "text": "将 @clip 中外套的颜色改为 @reference 中的颜色，保留人物动作、背景和镜头运动。" },
      { "type": "base_video", "url": "https://media.example.com/clip.mp4", "id": "clip" },
      { "type": "refer_image", "url": "https://media.example.com/reference.jpg", "id": "reference" }
    ],
    "settings": { "resolution": "1080p", "aspect_ratio": "adaptive" }
  },
  "callback_url": "https://app.example.com/webhooks/video"
}

引用主体和音色

将示例中的主体和音色 ID 替换为实际可用的 ID。图片主体与视频角色主体均使用 element，不通过请求字段自行声明主体类型。

{
  "model": "kling-4.0-omni",
  "input": {
    "contents": [
      { "type": "prompt", "text": "@hero 站在海边，用 @narrator 的声音说：新的旅程开始了。参考 @motion 的镜头运动。" },
      { "type": "element", "element_id": "REPLACE_WITH_ELEMENT_ID", "id": "hero" },
      { "type": "voice", "voice_id": "REPLACE_WITH_VOICE_ID", "id": "narrator" },
      { "type": "feature_video", "url": "https://media.example.com/motion.mp4", "id": "motion" }
    ],
    "settings": { "resolution": "720p", "duration": 10, "aspect_ratio": "16:9" }
  }
}

通用设置与素材要求

显式时长优先于提示词。省略时长时保留模型自动决定时长的行为：先识别提示词中的时长意图；未识别到时，文生和图生默认 10 秒，Omni 有 base_video 时跟随其时长，否则默认 10 秒。自动时长仍按最多 30 秒预扣，不能将默认 10 秒当作预扣上限。

提示词不能为空。纯 ASCII 内容最多 26,000 个字符，非 ASCII 内容最多 11,000 个 Unicode 字符；混合输入需满足 ASCII 字符数 / 26000 + 非 ASCII 字符数 / 11000 ≤ 1。图片和视频模型将提示词写入 contents 的 text，不要同时传入 input.prompt。

• 图片支持 JPG/JPEG/PNG，可使用 HTTP(S) URL 或 Base64（可带图片 data URL 前缀），单张不超过 30 MB；宽高均至少 300 px，宽高比为 2:5 至 5:2。较大图片建议使用 URL，避免 Base64 导致整个请求体超限。
• 视频仅支持 HTTP(S) URL，格式为 MP4/MOV，单个不超过 300 MB。单个视频和输入视频总时长均为 3–30 秒，总时长包含视频角色主体。
• 输入视频宽高均为 700–4553 px，总像素不超过 8,294,400，宽高比为 2:5 至 5:2，帧率为 24–60 fps。
• 素材 URL 应允许无需登录直接下载，且不能包含用户名和密码。文件尺寸、格式和内容也会在生成时校验，URL 格式合法不代表素材一定有效。

不支持的生成字段会被拒绝。请按本页结构提交，不要套用其他模型的 image_urls、video_urls、negative_prompt 或音频开关。

创建响应与任务查询

创建成功仅代表任务已受理，返回平台任务 ID：

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "29bd04f8-3c15-4374-a364-4b484782d235" }
}

使用相同账号的平台 API Key 查询：

curl 'https://api.aivideoapi.ai/v1/tasks/29bd04f8-3c15-4374-a364-4b484782d235' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY'

成功响应示例，对应 720p、实际输出 10 秒、无输入视频、账号倍率为 1：

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "completed",
  "model": "kling-4.0-text-to-video",
  "credits_consumed": 390.60,
  "created_at": 1793404800,
  "completed_at": 1793404920,
  "output": {
    "urls": ["https://media.example.com/result.mp4?signature=example"],
    "metadata": {
      "watermark_urls": ["https://media.example.com/result-watermarked.mp4?signature=example"]
    }
  },
  "usage": { "output_seconds": 10 }
}

查询返回任务对象本身，不包含创建响应的 code、msg、data 包装。时间戳单位为 Unix 秒。credits_consumed 是最终实际消耗；处理中返回 0 不表示余额没有预扣。usage.output_seconds 始终保留实际输出时长，可能与显式指定的计费时长不同；有输入视频时，可返回 usage.input_seconds，包括视频角色主体时长。

视频 URL

默认直接返回供应商原始视频 URL，不转存视频。 主视频位于 output.urls；请求水印且生成了水印版本时，地址位于 output.metadata.watermark_urls，否则可不包含该字段。查询和成功回调使用相同的结果结构。

请完整保留 URL 的签名和查询参数，及时下载并保存到自己的存储。URL 可能过期或文件可能被清理；任务记录的保留时间不等于视频可下载时间，不保证固定有效期。

这三个模型不支持取消任务。已经拿到 taskId 时，应继续查询该任务，不要因处理中或查询超时重复创建任务；新的创建请求可能产生独立任务和扣款。

完成回调

在创建请求最外层设置 callback_url，任务完成或明确失败后会向该地址发送 JSON POST。成功回调正文与上面的成功任务对象结构一致，失败回调包含 status="failed" 和 error。回调不通知 pending、processing 等中间状态。

平台会接收模型服务的状态回调，并使用任务查询补偿遗漏通知或缺失用量。你只需提供接收业务通知的顶层 callback_url，无需自行配置模型服务的回调地址，也不要在 input.options 中传入回调地址。生成成功后先完成积分结算，再发送成功通知；必要用量尚未齐全时，任务会继续等待核对。

请按 X-Event-ID 或任务 ID 与终态组合幂等处理，并在 10 秒内返回 HTTP 2xx。投递失败最多重试两次，间隔依次为 3 分钟和 10 分钟，实际时间受调度影响。上述头不构成签名；需要确认真实性时，使用平台 API Key 查询对应任务，再更新业务状态。

回调失败不会重新生成视频或改变已完成任务的扣款。建议保留任务查询作为通知失败时的补充方式。