# Kling 3.0 API

快手 Kling 3.0 影片生成模型的完整 API 參考文件。

## 模型變體

此 API 支援四種模型變體：

| 模型 | ID | 版本 | 說明 |
|-------|-----|------|-------------|
| **Kling 3.0 Std Text to Video** | `kling-v3.0-std-text-to-video` | 標準版 | 標準品質的文字生成影片 |
| **Kling 3.0 Std Image to Video** | `kling-v3.0-std-image-to-video` | 標準版 | 標準品質的圖像轉影片動畫 |
| **Kling 3.0 Pro Text to Video** | `kling-v3.0-pro-text-to-video` | 專業版 | 專業品質的文字生成影片 |
| **Kling 3.0 Pro Image to Video** | `kling-v3.0-pro-image-to-video` | 專業版 | 專業品質的圖像轉影片動畫 |

## 快速對比

| 功能 | 標準版 | 專業版 |
|---------|-----|-----|
| 品質 | 標準 | 最高 |
| 生成速度 | 較快 | 較慢 |
| 長寬比 | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 |
| 時長範圍 | 3-15 秒 | 3-15 秒 |

| 功能 | 文字生成影片 | 圖像轉影片 |
|---------|---------------|----------------|
| 輸入 | 文字提示詞 | 圖像 + 文字提示詞 |
| 起始幀 | 不支援 | 必填 |
| 結束幀 | 不支援 | 不支援 |
| 音訊 | 可選 | 可選 |

### 支援的長寬比

| 比例 | 說明 |
|-------|-------------|
| `16:9` | 横向（寬屏） |
| `9:16` | 纵向（竖屏） |
| `1:1` | 正方形 |

## Kling 3.0 文字生成影片（標準版 & 專業版）

### API 位址

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

### 請求參數

#### 必填

| 參數 | 類型 | 說明 |
|-----------|------|-------------|
| `model_name` | string | `"kling-v3.0-std-text-to-video"` 或 `"kling-v3.0-pro-text-to-video"` |
| `prompt` | string | 影片生成提示詞 |
| `duration` | number | 影片時長，單位秒（3-15） |
| `aspect_ratio` | string | 影片長寬比：`"16:9"`、`"9:16"` 或 `"1:1"` |

#### 可選

| 參數 | 類型 | 說明 |
|-----------|------|-------------|
| `sound` | boolean | 為影片生成環境音效 |
| `guidance_scale` | number | 提示詞遵循強度，0 到 1 之间的浮点数 |
| `negative_prompt` | string | 需要从生成影片中排除的元素 |

### 請求示例

**標準版：**

```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-v3.0-std-text-to-video',
    prompt: 'A fox running through a snowy forest at dusk',
    duration: 5,
    aspect_ratio: '16:9'
  })
});

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

**專業版：**

```javascript
{
  model_name: 'kling-v3.0-pro-text-to-video',
  prompt: 'A fox running through a snowy forest at dusk',
  duration: 5,
  aspect_ratio: '16:9'
}
```

## Kling 3.0 圖像轉影片（標準版 & 專業版）

### 請求參數

#### 必填

| 參數 | 類型 | 說明 |
|-----------|------|-------------|
| `model_name` | string | `"kling-v3.0-std-image-to-video"` 或 `"kling-v3.0-pro-image-to-video"` |
| `prompt` | string | 影片生成提示詞 |
| `duration` | number | 影片時長，單位秒（3-15） |
| `aspect_ratio` | string | 影片長寬比：`"16:9"`、`"9:16"` 或 `"1:1"` |
| `image_url` | string | 影片的第一幀圖像 |

#### 可選

| 參數 | 類型 | 說明 |
|-----------|------|-------------|
| `sound` | boolean | 為影片生成環境音效 |
| `guidance_scale` | number | 提示詞遵循強度，0 到 1 之间的浮点数 |
| `negative_prompt` | string | 需要从生成影片中排除的元素 |

### 請求示例

**標準版：**

```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-v3.0-std-image-to-video',
    image_url: 'https://example.com/image.jpg',
    prompt: 'Gentle breeze, leaves rustling, slow camera pull back',
    duration: 5,
    aspect_ratio: '16:9'
  })
});

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

**專業版：**

```javascript
{
  model_name: 'kling-v3.0-pro-image-to-video',
  image_url: 'https://example.com/image.jpg',
  prompt: 'Gentle breeze, leaves rustling, slow camera pull back',
  duration: 5,
  aspect_ratio: '16:9'
}
```

## 回應格式

### 初始回應

```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/{taskId}` 以查詢狀態：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "{task_id}",
    "response_url": "https://api.flaq.ai/api/v1/video/{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "task_result": {
      "credit": 0.2,
      "videos": [
        {
          "url": "https://example.com/generated-video.mp4"
        }
      ]
    }
  }
}
```

### 狀態值

- `submitted`：任務已接受，等待處理
- `processing`：影片生成中
- `succeed`：影片生成完成
- `failed`：影片生成失敗

## 處理時間

- **標準版**：约 2-4 分鐘，具體取决于時長
- **專業版**：约 3-6 分鐘，具體取决于時長

每 5-10 秒輪詢一次。较長的影片（10-15 秒）可能需要额外時間。

## 最佳實踐

1. **清晰說明动作**：在提示詞中加入鏡頭運動和主體动作，以獲得更具动感的效果
2. **使用负向提示詞**：排除不需要的元素（例如 `"blurry, low quality, watermark"`）以提升輸出品質
3. **引導強度**：较低的值（0.3-0.5）允许更多創意自由度；较高的值（0.7-1.0）会更严格地遵循提示詞
4. **圖像品質**：圖像轉影片時，使用清晰、光线良好的輸入圖像以獲得最佳动态效果
5. **時長選擇**：先用较短時長（3-5 秒）快速迭代，确认效果后再增加時長用於最終輸出
6. **版本選擇**：標準版適合快速迭代，專業版適合最終生产級品質的影片