# 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

### API 端點

```
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` 可關閉參考影片原始聲音保留；省略此參數則保留原始聲音