Kling 3 系列

通过 POST /v1/videos/generations 使用 Kling 3.0、Turbo、Omni 和动作控制。生成任务返回平台 taskId，通过统一任务接口查询，或通过完成回调接收结果。

本页的参数、价格和示例适用于上表六个模型 ID。所有模型默认 720p；除动作控制外，默认输出时长为 5 秒，可指定 3–15 的整数秒数。

计费规则

• 文生、图生、Turbo 和 Omni：按 input.settings.duration 指定的输出秒数收费；省略时按默认 5 秒收费。成片编码造成的细小时长差异不改变计费秒数。
• Omni 只有 feature_video、base_video 选择“有参考视频”单价；主体无论由图片还是视频创建，都不单独触发该单价。参考视频时长不加到计费秒数中。
• 动作控制：按实际输出视频时长收费，允许小数秒。character_orientation=image 按最多 10 秒预扣，video 按最多 30 秒预扣；成功后退还未使用的差额。
• 最终积分为 round2(round2(单价 × 计费秒数) × 账号倍率)。单价、扣款和退款最多保留两位小数，价格与账号倍率在创建任务时固定。

账号倍率为 1 时，3.0 无声、720p、默认 5 秒为 117.20 积分；3.0 有声、1080p、指定 10 秒为 468.70 积分，即使成片实际为 10.041 秒也按 10 秒结算。动作控制、1080p、朝向跟随视频时预扣 1406.10 积分；若实际输出 7.5 秒，最终扣 351.53 积分，退差额 1054.57 积分。

明确失败退还预扣。生成已成功但必要用量尚未确认时，任务继续核对，不按失败全额退款。最终扣费以 completed 任务的 credits_consumed 为准。

接口与认证

POST https://api.aivideoapi.ai/v1/videos/generations
Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

callback_url 放在最外层，与 model、input 同级。不要传 input.options.callback_url 或 external_task_id；保存返回的 taskId 关联业务记录。以下示例中的素材地址和主体 ID 需要替换为实际可用值。

文生视频

3.0 文生视频使用 input.prompt，必填且非空，最多 3072 个字符。

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-3.0-text-to-video",
    "input": {
      "prompt": "清晨的湖面，薄雾缓缓散开，镜头向前推进，伴随轻柔的鸟鸣。",
      "settings": { "resolution": "1080p", "duration": 10, "aspect_ratio": "16:9", "audio": "native", "multi_shot": false },
      "options": { "watermark_info": { "enabled": true } }
    },
    "callback_url": "https://app.example.com/webhooks/video"
  }'

Turbo 文生视频固定生成声音，不接受 audio 或 multi_shot 字段：

{
  "model": "kling-3.0-turbo-text-to-video",
  "input": {
    "prompt": "镜头 1, 2, 海浪拍打沙滩; 镜头 2, 3, 镜头抬起，海鸟掠过天空;",
    "settings": { "resolution": "720p", "duration": 5, "aspect_ratio": "16:9" }
  }
}

图生视频

图生视频使用 input.contents，必须有且仅有一个 first_frame；可选一个 prompt 项。3.0 图生还支持一个 last_frame 和最多 3 个主体；Turbo 图生只支持首帧和提示词。图生不接受 settings.aspect_ratio，输出比例由图片决定。

{
  "model": "kling-3.0-image-to-video",
  "input": {
    "contents": [
      { "type": "prompt", "text": "@hero 从画面左侧走入，向镜头微笑，最后停在尾帧的位置。" },
      { "type": "first_frame", "url": "https://media.example.com/start.jpg" },
      { "type": "last_frame", "url": "https://media.example.com/end.jpg" },
      { "type": "element", "element_id": "REPLACE_WITH_ELEMENT_ID", "id": "hero" }
    ],
    "settings": { "resolution": "1080p", "duration": 5, "audio": "off", "multi_shot": false }
  }
}

{
  "model": "kling-3.0-turbo-image-to-video",
  "input": {
    "contents": [
      { "type": "first_frame", "url": "https://media.example.com/start.jpg" },
      { "type": "prompt", "text": "人物转向镜头说：欢迎来到海边。背景传来海浪声。" }
    ],
    "settings": { "resolution": "1080p", "duration": 5 }
  }
}

3.0 图生提示词最多 3072 个字符，Turbo 图生最多 2500 个字符。首尾帧只需 type、url；主体需填写 element_id 和用于 @id 引用的 id。

Omni 参考与视频编辑

input.contents 为非空数组，可只包含一个提示词，也可混合支持的素材。最多一个 prompt，其文本最多 3072 个字符。

Omni 图片和视频可选 id，用于提示词中的 @id；主体的 id 必填，所有素材的 id 不得重复。feature_video 与 base_video 合计最多一个。audio=original 仅用于保留待编辑视频的原声。

{
  "model": "kling-3.0-omni-video",
  "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", "duration": 5, "audio": "original", "multi_shot": false }
  }
}

主体数量取决于其真实类型，由服务查询确认，不接受客户端自行声明类型：

• 有首帧时最多 3 个主体。
• 无参考视频时：图片与图片主体合计最多 7 个；存在视频角色主体时，该合计上限为 4，视频角色主体最多 3 个。
• 有参考视频时：图片与图片主体合计最多 4 个，或使用最多 1 个视频角色主体；视频角色主体不能再与图片、图片主体组合。
• 某个未知主体类型可能改变组合合法性时，先返回可重试错误，不预扣积分；请稍后重试。

此生成接口只引用已有主体，不提供主体或音色管理功能。

动作控制

使用一个 video 提供动作，使用一张 image 或一个 element 提供角色形象；最多一张图片、一个主体。character_orientation 必填：image 跟随图片人物朝向，参考视频为 3–10 秒；video 跟随视频人物朝向，参考视频为 3–30 秒。引用主体时只能选 video。

{
  "model": "kling-3.0-motion-control",
  "input": {
    "contents": [
      { "type": "prompt", "text": "保持人物面部和服装一致，完整呈现舞蹈动作。" },
      { "type": "image", "url": "https://media.example.com/character.jpg" },
      { "type": "video", "url": "https://media.example.com/dance.mp4" }
    ],
    "settings": { "character_orientation": "video", "resolution": "1080p", "audio": "original" }
  }
}

提示词可选，最多 2500 个字符。audio 为 original（默认，保留原声）或 off。不接受 duration、aspect_ratio、multi_shot。生成时提取有效连续动作，实际输出可能短于参考视频，按实际输出时长结算。

设置与素材要求

所有模型支持 input.options.watermark_info.enabled，布尔值，默认 false；true 请求额外水印版本。不得传未列出的设置字段。

分镜提示词采用 镜头 n, m, words;，使用半角逗号和分号，序号从 1 连续递增，最多 6 个分镜。每个分镜至少 1 秒，各分镜时长总和必须等于 settings.duration，每段描述最多 512 个字符。3.0 与 Omni 的 multi_shot=false 会关闭分镜生成。

• 图片：JPG/JPEG/PNG，HTTP(S) URL 或 Base64，单张不超过 50 MB；宽高至少 300 px，宽高比 0.4–2.5。
• Omni 视频：HTTP(S) URL，MP4/MOV，3–15.5 秒，最多 200 MB；宽高为 700–4553 px，总像素不超过 8,294,400，宽高比 0.4–2，帧率 24–60 fps。
• 动作控制视频：HTTP(S) URL，MP4/MOV，最多 100 MB；宽高为 340–3850 px，时长上限由朝向设置决定。
• 素材 URL 必须可直接下载，不能包含用户名或密码。尺寸、时长和实际内容在生成时继续校验。较大图片建议使用 URL。

创建响应、任务查询与回调

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

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

使用相同账号的 API Key 查询 GET /v1/tasks/{taskId}：

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

任务状态为 pending、processing、completed 或 failed。查询直接返回任务对象，成功示例为 3.0 文生、720p、无声、指定 5 秒、账号倍率 1：

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "completed",
  "model": "kling-3.0-text-to-video",
  "credits_consumed": 117.20,
  "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": 5.041 }
}

usage.output_seconds 保留实际成片时长。视频 URL 默认直接返回供应商原始 URL，主视频位于 output.urls；请求且生成了水印版本时，位于 output.metadata.watermark_urls。保留完整签名和查询参数并及时下载到自己的存储，URL 可能过期。

创建时填写顶层 callback_url 后，最终完成或明确失败会通过 JSON POST 通知。成功回调与任务查询使用相同结果结构；失败通知含 status=failed 和 error。处理中状态不会发送用户回调。

按事件 ID 或任务 ID 与终态幂等处理，并在 10 秒内返回 HTTP 2xx；投递失败可能重试。这些头不是签名，需要核实时可携带平台 API Key 查询任务。平台接收生成状态回调并定时补查，用户只需填写业务回调地址；回调丢失时也可继续查询原任务。

本页模型不支持取消。查询超时或任务仍处理中时，继续查询原 taskId；重复创建会生成独立任务并单独计费。用户回调投递失败不会重新生成视频，也不会改变成功任务的扣费。