# Kling 3.0 API

Tài liệu API đầy đủ cho các mô hình tạo video Kling 3.0 của Kuaishou.

## Các Phiên Bản Mô Hình

API này hỗ trợ bốn phiên bản mô hình:

| Mô Hình | ID | Cấp Độ | Mô Tả |
|---------|-----|--------|-------|
| **Kling 3.0 Std Text to Video** | `kling-v3.0-std-text-to-video` | Standard | Tạo video từ văn bản ở chất lượng tiêu chuẩn |
| **Kling 3.0 Std Image to Video** | `kling-v3.0-std-image-to-video` | Standard | Tạo video từ hình ảnh ở chất lượng tiêu chuẩn |
| **Kling 3.0 Pro Text to Video** | `kling-v3.0-pro-text-to-video` | Pro | Tạo video từ văn bản ở chất lượng pro |
| **Kling 3.0 Pro Image to Video** | `kling-v3.0-pro-image-to-video` | Pro | Tạo video từ hình ảnh ở chất lượng pro |

## So Sánh Nhanh

| Tính Năng | Std | Pro |
|-----------|-----|-----|
| Chất Lượng | Tiêu chuẩn | Cao nhất |
| Tốc Độ Tạo | Nhanh hơn | Chậm hơn |
| Tỷ Lệ Khung Hình | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 |
| Khoảng Thời Lượng | 3-15 giây | 3-15 giây |

| Tính Năng | Text to Video | Image to Video |
|-----------|---------------|----------------|
| Đầu Vào | Văn bản mô tả | Hình ảnh + Văn bản mô tả |
| Khung Hình Đầu | Không hỗ trợ | Bắt buộc |
| Khung Hình Cuối | Không hỗ trợ | Không hỗ trợ |
| Âm Thanh | Tùy chọn | Tùy chọn |

### Tỷ Lệ Khung Hình Được Hỗ Trợ

| Tỷ Lệ | Mô Tả |
|-------|-------|
| `16:9` | Ngang (màn hình rộng) |
| `9:16` | Dọc (chiều dọc) |
| `1:1` | Vuông |

## Kling 3.0 Text to Video (Std & Pro)

### Endpoint

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

### Tham Số Yêu Cầu

#### Bắt Buộc

| Tham Số | Kiểu | Mô Tả |
|---------|------|-------|
| `model_name` | string | `"kling-v3.0-std-text-to-video"` hoặc `"kling-v3.0-pro-text-to-video"` |
| `prompt` | string | Mô tả để tạo video |
| `duration` | number | Thời lượng video tính bằng giây (3-15) |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"16:9"`, `"9:16"`, hoặc `"1:1"` |

#### Tùy Chọn

| Tham Số | Kiểu | Mô Tả |
|---------|------|-------|
| `sound` | boolean | Tạo âm thanh môi trường cho video |
| `guidance_scale` | number | Mức độ tuân thủ mô tả, số thực từ 0 đến 1 |
| `negative_prompt` | string | Các yếu tố cần loại trừ khỏi video được tạo |

### Ví Dụ Yêu Cầu

**Phiên Bản Std:**

```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;
```

**Phiên Bản Pro:**

```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 Image to Video (Std & Pro)

### Tham Số Yêu Cầu

#### Bắt Buộc

| Tham Số | Kiểu | Mô Tả |
|---------|------|-------|
| `model_name` | string | `"kling-v3.0-std-image-to-video"` hoặc `"kling-v3.0-pro-image-to-video"` |
| `prompt` | string | Mô tả để tạo video |
| `duration` | number | Thời lượng video tính bằng giây (3-15) |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"16:9"`, `"9:16"`, hoặc `"1:1"` |
| `image_url` | string | Khung hình đầu tiên của video |

#### Tùy Chọn

| Tham Số | Kiểu | Mô Tả |
|---------|------|-------|
| `sound` | boolean | Tạo âm thanh môi trường cho video |
| `guidance_scale` | number | Mức độ tuân thủ mô tả, số thực từ 0 đến 1 |
| `negative_prompt` | string | Các yếu tố cần loại trừ khỏi video được tạo |

### Ví Dụ Yêu Cầu

**Phiên Bản Std:**

```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;
```

**Phiên Bản Pro:**

```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'
}
```

## Định Dạng Phản Hồi

### Phản Hồi Ban Đầu

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

### Phản Hồi Khi Kiểm Tra Trạng Thái

Gọi `GET /api/v1/video/{taskId}` để kiểm tra trạng thái:

```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"
        }
      ]
    }
  }
}
```

### Các Giá Trị Trạng Thái

- `submitted`: Tác vụ đã được chấp nhận và đang chờ xử lý
- `processing`: Đang tạo video
- `succeed`: Tạo video hoàn tất
- `failed`: Tạo video thất bại

## Thời Gian Xử Lý

- **Phiên Bản Std**: khoảng 2-4 phút tùy thuộc vào thời lượng
- **Phiên Bản Pro**: khoảng 3-6 phút tùy thuộc vào thời lượng

Kiểm tra mỗi 5-10 giây. Các video dài hơn (10-15 giây) có thể mất thêm thời gian.

## Các Thực Hành Tốt Nhất

1. **Mô Tả Chuyển Động Rõ Ràng**: Đưa vào mô tả các chuyển động camera và hành động của đối tượng để có kết quả năng động hơn
2. **Sử Dụng Negative Prompt**: Loại trừ các yếu tố không mong muốn (ví dụ: `"blurry, low quality, watermark"`) để cải thiện đầu ra
3. **Guidance Scale**: Giá trị thấp hơn (0.3-0.5) cho phép tự do sáng tạo hơn; giá trị cao hơn (0.7-1.0) tuân theo mô tả chặt chẽ hơn
4. **Chất Lượng Hình Ảnh**: Với image-to-video, sử dụng hình ảnh đầu vào sắc nét, có ánh sáng tốt để đạt chất lượng chuyển động tốt nhất
5. **Thời Lượng**: Bắt đầu với thời lượng ngắn hơn (3-5 giây) để lặp lại nhanh, sau đó tăng lên cho đầu ra cuối cùng
6. **Lựa Chọn Cấp Độ**: Sử dụng Std để lặp lại nhanh hơn và Pro cho các video chất lượng sản xuất cuối cùng