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

## 概述

Kling 3.0 Motion Control 通过 1 张参考图片和 1 个动作视频生成受控动作视频。参考图片用于指定主体，动作视频用于指定运动模式。

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

## 认证方式

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

## 创建任务

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

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 否 | 提示词，用于引导动画内容，0-2500字符 |
| inputUrls | string[] | 是 | 参考图片 URL，必须且仅 1 张。JPG/JPEG/PNG，最大10MB，图片尺寸需大于340px，比例 2:5 到 5:2 |
| videoUrls | string[] | 是 | 动作视频 URL，必须且仅 1 个。MP4/QuickTime，3-30秒，最大100MB，尺寸需大于340px，比例 2:5 到 5:2 |
| mode | string | 否 | 质量模式：`std`/`pro`，兼容 `720p`/`1080p`；默认 `std` |
| characterOrientation | string | 否 | 人物朝向参考：`video`(默认，推荐) / `image` |
| backgroundSource | string | 否 | 背景来源：`input_video`(默认) / `input_image` |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

### cURL 示例

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/kling-3.0-motion-control" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The cartoon character is dancing.",
    "inputUrls": [
      "https://example.com/reference.png"
    ],
    "videoUrls": [
      "https://example.com/motion.mp4"
    ],
    "mode": "std",
    "characterOrientation": "image",
    "backgroundSource": "input_video"
  }'
```

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509103000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-09 10:30:00"
  }
}
```

## 查询任务

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

成功时 `data.result` 返回生成视频 URL 列表；失败时 `data.errorMsg` 返回失败原因。

## 回调通知

创建任务时传入 `callbackUrl` 后，任务完成会向该地址 POST：

```json
{
  "event": "task.completed",
  "taskId": "task_20260509103000_abc12345",
  "status": "success",
  "result": ["https://example.com/output.mp4"],
  "timestamp": "2026-05-09T10:35:00+08:00",
  "signature": "..."
}
```