# Kling 3.0 视频生成 API 对接文档

## 概述

Kling 3.0（可灵）视频生成接口，支持单镜头、首尾帧图生视频、多镜头和元素引用。相比 Kling 2.6，Kling 3.0 提供了更灵活的时长控制（3-15秒）、三种质量模式（std/pro/4K）、音效以及 `@element_name` 元素引用。

**Base URL**: `https://api.apiverse.ai`

---

## 认证方式

所有接口均需要在请求头中携带 Token 进行认证：

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

## 快速开始

### cURL 示例

**创建文生视频任务（Pro模式，5秒）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/kling-3.0" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只猫在阳光下慵懒地伸展身体",
    "genType": "t2v",
    "mode": "pro",
    "duration": 5,
    "aspectRatio": "16:9",
    "sound": false
  }'
```

**创建图生视频任务（4K模式，10秒，带音频）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/kling-3.0" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "让图片中的人物挥手致意",
    "genType": "i2v",
    "imageUrls": ["https://example.com/reference.jpg"],
    "mode": "4K",
    "duration": 10,
    "sound": true
  }'
```

**创建多镜头任务（带元素引用）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/kling-3.0" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "genType": "t2v",
    "multiShots": true,
    "duration": 6,
    "aspectRatio": "16:9",
    "mode": "pro",
    "sound": true,
    "multiPrompt": [
      {"prompt": "a happy dog running @element_dog", "duration": 3},
      {"prompt": "the dog jumps through sunlight @element_dog", "duration": 3}
    ],
    "klingElements": [
      {
        "name": "element_dog",
        "description": "dog",
        "elementInputUrls": [
          "https://example.com/dog-1.jpg",
          "https://example.com/dog-2.jpg"
        ]
      }
    ]
  }'
```

**查询任务状态**
```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"
```

**查询账户余额**
```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/balance" \
  -H "Authorization: Bearer your_auth_token_here"
```

---

## 接口列表

### 1. 创建 Kling 3.0 视频生成任务

**POST** `/api/v2/open/aigc/kling-3.0`

创建一个 Kling 3.0 视频生成任务。

**Content-Type**: `application/json`

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 条件 | 单镜头视频描述提示词，最多500字符；`multiShots=true` 时可不传 |
| genType | string | 否 | 生成类型：`t2v`(文生视频,默认) / `i2v`(图生视频) |
| imageUrls | string[] | 条件 | 首尾帧图片 URL。单镜头支持1-2张；`multiShots=true` 时仅支持1张首帧图 |
| sound | boolean | 否 | 是否生成音频，默认 false |
| duration | int | 否 | 视频时长：3-15秒，默认 5 |
| aspectRatio | string | 否 | 宽高比：`16:9`(默认) / `9:16` / `1:1` |
| mode | string | 否 | 质量模式：`std`(720p) / `pro`(1080p,默认) / `4K`(2160p) |
| multiShots | boolean | 否 | 是否启用多镜头，默认 false |
| multiPrompt | object[] | 条件 | 多镜头提示词，`multiShots=true` 时必填，最多5段 |
| multiPrompt[].prompt | string | 条件 | 单段镜头提示词，最多500字符；可使用 `@element_name` 引用元素 |
| multiPrompt[].duration | int | 条件 | 单段镜头时长，1-12秒 |
| klingElements | object[] | 否 | 元素引用，最多3个 |
| klingElements[].name | string | 条件 | 元素名称，不带 `@`；prompt 中用 `@name` 引用 |
| klingElements[].description | string | 条件 | 元素描述 |
| klingElements[].elementInputUrls | string[] | 条件 | 元素图片 URL，2-4张，JPG/PNG，单张最大10MB |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

> **说明**：
> - 图生视频(i2v)时可提供 1-2 张图片，分别作为首帧和尾帧参考；多镜头仅支持首帧图
> - 质量模式影响输出分辨率：std(720p) < pro(1080p) < 4K(2160p)
> - 时长支持 3-15 秒的任意整数值
> - 元素引用需要在提示词中写 `@element_name`，并在 `klingElements` 中提供同名元素
> - 创建任务时会预扣费，余额不足将返回错误

#### 请求示例

**文生视频（Pro模式，5秒，无音频）：**
```json
{
  "prompt": "一只猫在阳光下慵懒地伸展身体",
  "genType": "t2v",
  "mode": "pro",
  "duration": 5,
  "aspectRatio": "16:9",
  "sound": false
}
```

**文生视频（4K模式，10秒，有音频）：**
```json
{
  "prompt": "海浪拍打沙滩的场景，带有海鸥的叫声",
  "genType": "t2v",
  "mode": "4K",
  "duration": 10,
  "aspectRatio": "9:16",
  "sound": true
}
```

**图生视频（单张图片，Pro模式，8秒）：**
```json
{
  "prompt": "让图片中的花朵随风摇曳",
  "genType": "i2v",
  "imageUrls": ["https://example.com/flower.jpg"],
  "mode": "pro",
  "duration": 8,
  "sound": false
}
```

**图生视频（首尾帧，4K模式，12秒，有音频）：**
```json
{
  "prompt": "从第一张图片平滑过渡到第二张图片",
  "genType": "i2v",
  "imageUrls": [
    "https://example.com/start_frame.jpg",
    "https://example.com/end_frame.jpg"
  ],
  "mode": "4K",
  "duration": 12,
  "sound": true
}
```

**多镜头 + 元素引用：**
```json
{
  "genType": "t2v",
  "multiShots": true,
  "duration": 6,
  "aspectRatio": "16:9",
  "mode": "pro",
  "sound": true,
  "multiPrompt": [
    {
      "prompt": "a happy dog running @element_dog",
      "duration": 3
    },
    {
      "prompt": "the dog jumps through sunlight @element_dog",
      "duration": 3
    }
  ],
  "klingElements": [
    {
      "name": "element_dog",
      "description": "dog",
      "elementInputUrls": [
        "https://example.com/dog-1.jpg",
        "https://example.com/dog-2.jpg"
      ]
    }
  ]
}
```

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID，用于查询任务状态 |
| data.status | string | 任务状态，创建时固定为 `processing` |
| data.createdAt | string | 创建时间 |

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508103000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 10:30:00"
  }
}
```

**余额不足**
```json
{
  "code": 40001,
  "msg": "余额不足: 当前余额 0.5000, 需要 0.7500",
  "data": null
}
```

**参数错误**
```json
{
  "code": 10002,
  "msg": "duration 必须在 3-15 之间",
  "data": null
}
```

---

### 2. 查询任务状态

**GET** `/api/v2/open/aigc/{taskId}`

查询单个任务的执行状态。

#### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskId | string | 是 | 任务 ID |

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID |
| data.status | string | 任务状态：`processing` / `success` / `failed` |
| data.result | string[] | 生成的视频 URL 列表（成功时返回） |
| data.errorMsg | string | 错误信息（失败时返回） |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 更新时间 |

#### 响应示例

**处理中**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508103000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-08 10:30:00",
    "updatedAt": "2026-05-08 10:30:05"
  }
}
```

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508103000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/08/output_001.mp4"
    ],
    "createdAt": "2026-05-08 10:30:00",
    "updatedAt": "2026-05-08 10:33:45"
  }
}
```

**失败**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260508103000_abc12345",
    "status": "failed",
    "errorMsg": "生成失败：内容不符合规范",
    "createdAt": "2026-05-08 10:30:00",
    "updatedAt": "2026-05-08 10:30:45"
  }
}
```

---

### 3. 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

批量查询多个任务的执行状态（最多 100 个）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| taskIds | string[] | 是 | 任务 ID 列表，最多 100 个 |

#### 请求示例

```json
{
  "taskIds": ["task_20260508103000_abc12345", "task_20260508103200_def67890"]
}
```

---

### 4. 查询账户余额

**GET** `/api/v2/open/balance`

查询当前用户的账户余额。

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "userId": "user@example.com",
    "balance": "19.9250",
    "frozenBalance": "1.5000",
    "currency": "USD"
  }
}
```

---

## 回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。

### 回调请求

**Headers**
```
Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}
```

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260508103000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-08T10:33:45+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

### 回调响应

接收方应返回 HTTP 2xx 状态码表示成功接收：

```json
{
  "code": 0,
  "msg": "ok"
}
```

---

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 30003 | 任务不存在 |
| 40001 | 余额不足 |
| 90003 | 服务器内部错误 |

---

## 最佳实践

### 1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 3 分钟：每 5 秒查询一次
- 3 分钟后：每 10 秒查询一次

### 2. 使用回调

对于生产环境，建议使用回调通知而非轮询，可以：
- 减少 API 调用次数
- 更快获得结果通知
- 降低服务器压力

### 3. 处理时间参考

- std 模式(5s)：通常 1 ~ 2 分钟
- pro 模式(5s)：通常 2 ~ 3 分钟
- 4K 模式(5s)：通常 3 ~ 5 分钟
- 时长越长，处理时间越长（大约按比例增加）
- 有音频的任务会比无音频稍慢

### 4. 余额管理

- 创建任务前建议先查询余额，避免因余额不足导致任务失败
- 任务成功后会从冻结余额中扣费
- 任务失败后冻结金额会自动退还到可用余额

### 5. 质量模式选择

- **std (720p)**: 适合快速预览、社交媒体分享
- **pro (1080p)**: 适合大多数场景，性价比高
- **4K (2160p)**: 适合高质量输出、专业制作

### 6. 图片参考使用

- 单张图片：作为视频的起始参考
- 两张图片：分别作为首帧和尾帧，视频会在两者之间平滑过渡
- 多镜头模式：仅支持 1 张首帧图，镜头内容由 `multiPrompt` 控制
- 图片建议分辨率：至少 1024×1024，最佳 2048×2048

### 7. 元素引用

- `klingElements` 最多 3 个元素
- 每个元素需要 2-4 张 JPG/PNG 图片
- 在 `prompt` 或 `multiPrompt[].prompt` 中使用 `@element_name` 引用元素