Kling 3.0

Kling 3.0 是快手 Kling 3.0 视频生成模型，支持文生视频与图生视频，原生音频，可生成 3-15 秒视频。

模型

模型名称	模式
`kling-3.0`	std（720P）、pro（1080P）

定价

按秒 × 模式 × 是否带音频计费：

模式	音频	分辨率	积分/秒
std	关闭	720P	28
std	开启	720P	40
pro	关闭	1080P	36
pro	开启	1080P	54

任务创建时按 duration × 单价 预扣积分；任务失败自动退还。

创建任务

POST https://api.aivideoapi.ai/v1/videos/generations

请求体

字段	类型	必填	说明
`model`	string	是	必须为 `kling-3.0`
`input`	object	是	生成参数，见下方
`callback_url`	string	否	接收任务完成/失败通知的 URL

Input 对象

字段	类型	必填	说明
`prompt`	string	否*	单镜头文本描述，最长 2500 字符。支持 `@element_name` 引用（见下方元素引用）
`image_urls`	string[]	否*	单镜头：1-2 张（起始/结束帧）；多镜头：1 张
`mode`	string	否	`std`（默认，720P）或 `pro`（1080P）
`aspect_ratio`	string	否	`16:9`（默认）、`9:16`、`1:1`。当 `image_urls` 提供时自动按图片比例适配
`duration`	integer	否	总视频时长 3-15 秒，默认 5
`sound`	boolean	否	是否生成原生音频。单镜头默认 `false`，多镜头默认 `true`
`multi_shots`	boolean	否	启用多镜头模式，默认 `false`
`multi_prompt`	object[]	否*	多镜头分镜列表，最多 5 个。`multi_shots: true` 时必填
`kling_elements`	object[]	否	元素引用定义，最多 3 个，可在 prompt 中通过 `@name` 引用

*prompt、image_urls、multi_prompt 至少传一个。

`multi_prompt[]` 子字段

字段	类型	必填	说明
`prompt`	string	是	该镜头描述，最长 500 字符
`duration`	integer	是	该镜头时长，1-12 秒

所有镜头时长之和应 ≤ 顶层 duration（≤ 15 秒）。

`kling_elements[]` 子字段

字段	类型	必填	说明
`name`	string	是	元素名，作为 `@name` 在 prompt 中引用
`description`	string	是	元素描述
`element_input_urls`	string[]	是	2-4 张参考图（JPG/PNG，单张 ≤ 10MB）

📌 元素引用注意事项

prompt 里的 @name 必须和 kling_elements[].name 完全一致（不带 @ 前缀）

单任务最多引用 3 个元素

每个 @element 在 prompt 字数计算中占 37 个字符，请预留空间避免触达 prompt 字数上限（单镜头 2500 / 单 shot 500）

示例：文生视频（标准模式）

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "无人机航拍日落时分的山脉，电影级光影效果",
      "mode": "std",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": true
    }
  }'

示例：图生视频（专业模式）

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "蝴蝶振翅起飞，慢动作微距镜头",
      "image_urls": ["https://example.com/butterfly.jpg"],
      "mode": "pro",
      "duration": 10
    }
  }'

示例：多镜头模式

将多个镜头串联生成一段叙事视频。每个镜头有独立的 prompt 和时长。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "mode": "pro",
      "duration": 12,
      "multi_shots": true,
      "multi_prompt": [
        { "prompt": "清晨的山顶云海，无人机俯拍", "duration": 4 },
        { "prompt": "镜头穿过云层下降，看到森林中的小屋", "duration": 4 },
        { "prompt": "屋内炉火旁，一只猫蜷缩着睡觉", "duration": 4 }
      ]
    }
  }'

示例：元素引用

通过 kling_elements 定义可复用角色/物体，再用 @name 在 prompt 中引用。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "@元素_柴犬 在樱花树下追蝴蝶，慢动作",
      "mode": "pro",
      "duration": 5,
      "kling_elements": [
        {
          "name": "元素_柴犬",
          "description": "一只棕色柴犬",
          "element_input_urls": [
            "https://example.com/dog1.jpg",
            "https://example.com/dog2.jpg"
          ]
        }
      ]
    }
  }'

⚠️ 元素引用要求每个元素至少 2 张参考图，最多 4 张；单任务最多 3 个元素。

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cbf6b69d-4f03-4817-8ed7-94c0292184a8"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态变化：pending -> processing -> completed 或 failed。

处理中

{
  "id": "e717a5ee-2ed4-47f4-8cc3-53394f1abb35",
  "status": "processing",
  "model": "kling-3.0",
  "created_at": 1774706165,
  "progress": null
}

完成

{
  "id": "7d89c51e-9430-410e-909e-df347131ebaa",
  "status": "completed",
  "model": "kling-3.0",
  "created_at": 1774790227,
  "completed_at": 1774796529,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/04/04/abc123.mp4"
    ],
    "metadata": {
      "model": "kling-3.0/video"
    }
  }
}

视频 URL 为永久链接。

失败

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "kling-3.0",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

任务失败时，预扣的积分会自动退还。

回调 (Callback)

创建任务时传入 callback_url，系统会在任务完成或失败时自动向你的 URL 发送 POST 请求。格式与查询任务响应一致。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。