# Kling 3.0 Motion Control API

快手 Kling 3.0 Motion Control 视频生成的完整 API 参考文档。

## 模型变体

此 API 支持一个模型变体：

| 模型 | ID | 描述 |
|-------|-----|-------------|
| **Kling 3.0 Motion Control** | `kling-3.0-motion-control` | 使用文本提示词、一张参考图片和一段参考视频生成视频 |

## Kling 3.0 Motion Control

### 接口端点

```
POST /api/v1/video/task
```

### 请求参数

#### 必填参数

| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `model_name` | string | 必须为 `"kling-3.0-motion-control"` |
| `prompt` | string | 视频生成提示词，最多 5000 个字符 |
| `images` | string[] | 必须且只能提供一个参考图片 URL。支持 `.jpg`、`.jpeg` 和 `.png`；文件大小不得超过 50 MB。宽度和高度均须至少为 300 px，图片宽高比须在 1:2.5 至 2.5:1 之间 |
| `videos` | string[] | 必须且只能提供一个参考视频 URL。支持 `.mp4` 和 `.mov`；文件大小不得超过 100 MB。宽度和高度均须在 340 至 3850 px 之间，包含边界值。时长须至少为 3 秒；最大时长取决于 `character_orientation` |
| `character_orientation` | string | 必填，无默认值。`"image"`：遵循参考图片中角色的朝向；参考视频时长须为 3-10 秒。`"video"`：遵循参考视频中角色的朝向；参考视频时长须为 3-30 秒。两个时长范围均包含边界值 |
| `resolution` | string | 输出分辨率：`"720p"` 或 `"1080p"`。必填，无默认值 |

#### 可选参数

| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `keep_original_sound` | boolean | 是否保留参考视频的原声。接受 `true` 或 `false`；默认为 `true` |

输出时长与源视频一致。不支持 `duration` 参数。输出宽高比由输入素材决定，不支持 `aspect_ratio` 参数。上游服务商尚未明确说明由哪种输入决定输出宽高比，也未说明具体的选择规则。

计费依据为源视频时长四舍五入到整数秒后的值，以及所选的输出分辨率。例如，5.4 秒按 5 秒计费，5.5 秒按 6 秒计费。

### 请求示例

请将示例素材 URL 替换为你自己的、符合上述要求的文件 URL。

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'kling-3.0-motion-control',
    prompt: 'Animate the character in the reference image using the dance movements from the reference video',
    images: ['https://example.com/character.jpg'],
    videos: ['https://example.com/dance-reference.mp4'],
    character_orientation: 'video',
    resolution: '720p',
    keep_original_sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## 响应格式

### 初始响应

返回用于轮询的 `task_id`：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "submitted"
  }
}
```

使用 `GET /api/v1/video/{task_id}` 轮询，以检查状态并获取生成的视频。

### 状态值

- `submitted`：任务已接受，等待处理
- `processing`：视频正在生成
- `succeed`：视频生成完成
- `failed`：视频生成失败

## 最佳实践

1. **参考素材**：必须且只能提供一张图片和一段视频，提交前请检查其格式、文件大小和宽高尺寸
2. **朝向**：切换 `character_orientation` 时，请重新检查参考视频的时长，尤其是在选择 `"image"` 时
3. **原声**：将 `keep_original_sound` 设为 `false` 可关闭参考视频原声保留；省略此参数则保留原声