# Seedance 2.0 Mini API

Tài liệu tham chiếu API đầy đủ cho các mô hình tạo video Seedance 2.0 Mini của ByteDance.

## Các Biến Thể Mô Hình

API này hỗ trợ ba biến thể mô hình:

| Mô hình | ID | Mô tả |
|-------|-----|-------------|
| **Seedance 2.0 Mini Text to Video** | `seedance-v2.0-mini-text-to-video` | Tạo video từ văn bản với chi phí tối ưu |
| **Seedance 2.0 Mini Image to Video** | `seedance-v2.0-mini-image-to-video` | Tạo chuyển động cho hình ảnh với chi phí tối ưu và khả năng điều khiển chuyển động |
| **Seedance 2.0 Mini Reference to Video** | `seedance-v2.0-mini-reference-to-video` | Tạo video với chi phí tối ưu dựa trên hình ảnh, video và âm thanh tham chiếu |

## So Sánh Nhanh

| Tính năng | Giá trị |
|---------|-------|
| Phạm vi thời lượng | 4-15 giây |
| Tùy chọn độ phân giải | 480p, 720p |
| Tùy chọn tỷ lệ khung hình | 21:9, 16:9, 9:16, 1:1, 4:3, 3:4 |
| Hỗ trợ âm thanh | Có (mặc định: bật) |
| Nội dung tham chiếu | Hình ảnh, video và âm thanh cho tạo video từ tham chiếu |
| Điều khiển hạt giống | Không mô hình Seedance 2.0 Mini nào hỗ trợ |

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

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

### Tùy Chọn Độ Phân Giải

| Độ phân giải | Mô tả |
|------------|-------------|
| `480p` | Độ nét tiêu chuẩn, xử lý nhanh hơn |
| `720p` | Độ nét cao |

## Seedance 2.0 Mini Text to Video

### Điểm Cuối

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

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

#### Bắt Buộc

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `model_name` | string | Phải là `"seedance-v2.0-mini-text-to-video"` |
| `prompt` | string | Câu lệnh tạo video |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-15), bước tăng là 1 |
| `resolution` | string | Độ phân giải đầu ra: `"480p"` hoặc `"720p"` |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` hoặc `"3:4"` |

#### Tùy Chọn

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `sound` | boolean | Có tạo âm thanh môi trường hay không (mặc định: `true`) |

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

```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: 'seedance-v2.0-mini-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Image to Video

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

#### Bắt Buộc

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `model_name` | string | Phải là `"seedance-v2.0-mini-image-to-video"` |
| `prompt` | string | Câu lệnh tạo video |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-15), bước tăng là 1 |
| `resolution` | string | Độ phân giải đầu ra: `"480p"` hoặc `"720p"` |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` hoặc `"3:4"` |
| `image_url` | string | Khung hình đầu tiên của video |

#### Tùy Chọn

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `image_end_url` | string | URL hình ảnh khung hình cuối, không bắt buộc |
| `sound` | boolean | Có tạo âm thanh môi trường hay không (mặc định: `true`) |

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

```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: 'seedance-v2.0-mini-image-to-video',
    image_url: 'https://example.com/image.jpg',
    image_end_url: 'https://example.com/end-frame.jpg',
    prompt: 'Camera slowly pulls back to reveal the full landscape',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.0 Mini Reference to Video

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

#### Bắt Buộc

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `model_name` | string | Phải là `"seedance-v2.0-mini-reference-to-video"` |
| `prompt` | string | Câu lệnh tạo video. Viết câu lệnh thông thường không có ký hiệu giữ chỗ, hoặc dùng tính năng tham chiếu @ (AT) với `<<<image_N>>>`, `<<<video_N>>>` và `<<<audio_N>>>` để tham chiếu rõ ràng đến các phần tử trong mảng nội dung tương ứng |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-15), bước tăng là 1 |
| `resolution` | string | Độ phân giải đầu ra: `"480p"` hoặc `"720p"` |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` hoặc `"3:4"` |

#### Nội Dung Tham Chiếu

Mỗi yêu cầu phải chứa ít nhất một hình ảnh hoặc video. Gửi 1-9 hình ảnh khi dùng tham chiếu hình ảnh. Chỉ được bỏ qua hoặc để trống mảng `images` khi mảng `videos` chứa ít nhất một video tham chiếu. Không hỗ trợ yêu cầu chỉ có âm thanh.

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `images` | string[] | 1-9 URL hình ảnh tham chiếu, hoặc mảng trống khi `videos` không trống |
| `videos` | string[] | Tối đa 3 URL video tham chiếu; mỗi video phải dài 2-15 giây, tổng thời lượng không quá 15 giây |
| `audios` | string[] | Tối đa 3 URL âm thanh tham chiếu; mỗi đoạn phải dài 2-15 giây, tổng thời lượng không quá 15 giây; WAV hoặc MP3, tối đa 15 MB mỗi đoạn; yêu cầu ít nhất một hình ảnh hoặc video |

#### Ký Hiệu Giữ Chỗ Tham Chiếu @ (AT)

Tính năng tham chiếu @ (AT) liên kết nội dung tham chiếu với câu lệnh qua các ký hiệu giữ chỗ có đánh số `<<<...>>>`. Mỗi loại nội dung được đánh số riêng từ `1`, theo thứ tự của mảng tương ứng:

| Ký hiệu giữ chỗ | Giá trị được tham chiếu |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

Mỗi ký hiệu giữ chỗ phải trỏ đến một phần tử tồn tại trong mảng tương ứng.

#### Tùy Chọn

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `sound` | boolean | Có tạo âm thanh đồng bộ hay không. Mặc định là `true` |

### Tính Phí Video Tham Chiếu

Seedance V2.0 Mini Reference-to-Video áp dụng cùng cơ chế tính phí theo giây dựa trên độ phân giải như các biến thể tham chiếu Seedance 2.0 khác. Khi mảng `videos` chứa ít nhất một video tham chiếu, tổng phí tạo video được nhân với 2. Hệ số này chỉ áp dụng một lần, không phụ thuộc số lượng hoặc thời lượng video tham chiếu đã tải lên.

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

```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: 'seedance-v2.0-mini-reference-to-video',
    prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
    duration: 8,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true,
    images: [
      'https://example.com/explorer-reference.jpg',
      'https://example.com/environment-reference.jpg'
    ],
    videos: ['https://example.com/camera-movement-reference.mp4'],
    audios: ['https://example.com/voice-reference.mp3']
  })
});

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

## Giới Hạn Nội Dung Đa Phương Tiện

Các giới hạn này áp dụng cho hình ảnh khung hình đầu, hình ảnh khung hình cuối và nội dung tham chiếu của các mô hình trên trang này.

| Nội dung | Định dạng | Giới hạn |
|-------|---------|--------|
| Hình ảnh | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Mỗi hình ảnh phải nhỏ hơn 30 MB; chiều rộng và chiều cao đều phải từ 300-6000 px; tỷ lệ rộng/cao phải từ 0,4-2,5 |
| Video | MP4, MOV | Tối đa 200 MB mỗi video; chiều rộng và chiều cao đều phải từ 300-6000 px; tỷ lệ rộng/cao phải từ 0,4-2,5; tốc độ khung hình phải từ 24-60 FPS |
| Âm thanh | WAV, MP3 | Tối đa 15 MB mỗi tệp |
| Phần thân yêu cầu | — | Tối đa 64 MB |

Âm thanh tham chiếu và video tham chiếu có giới hạn tổng thời lượng riêng là 15 giây cho mỗi loại. Số lượng cũng độc lập: tối đa 9 hình ảnh, 3 video và 3 đoạn âm thanh. Thêm video không làm giảm số hình ảnh được phép.

Tất cả mô hình mặc định dùng `720p`, nhưng vẫn phải cung cấp `resolution`. Công tắc âm thanh mặc định là `true`; cả công tắc này lẫn âm thanh tham chiếu đều không thay đổi giá. Tạo video từ tham chiếu yêu cầu ít nhất một hình ảnh hoặc video; không hỗ trợ yêu cầu chỉ có âm thanh. Tải lên video tham chiếu làm phí tạo video tăng gấp đôi, bất kể số lượng hoặc thời lượng.

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

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

Tất cả mô hình trả về `task_id` để truy vấn định kỳ:

```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 Truy Vấn Định Kỳ

Truy vấn định kỳ `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"
        }
      ]
    }
  }
}
```

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

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

## Thời Gian Xử Lý

Thời gian xử lý thông thường là 2-6 phút, tùy theo thời lượng và độ phân giải.

Truy vấn mỗi 5-10 giây để kiểm tra trạng thái.

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

1. **Mô Tả Chuyển Động Rõ Ràng**: Đưa mô tả chuyển động cụ thể vào câu lệnh
2. **Chọn Độ Phân Giải**: Dùng `480p` để xử lý nhanh hơn, `720p` để có chất lượng cao hơn
3. **Tăng Cường Âm Thanh**: Bật `sound` để trải nghiệm video sống động hơn
4. **Hình Ảnh Thành Video**: Cung cấp khung hình đầu rõ nét qua `image_url`; dùng `image_end_url` khi cần kiểm soát khung hình đầu và cuối
5. **Nội Dung Tham Chiếu**: Dùng hình ảnh, video và âm thanh tham chiếu được hỗ trợ, bảo đảm có ít nhất một hình ảnh hoặc video
6. **Tính Phí Video Tham Chiếu**: Mọi yêu cầu tạo video từ tham chiếu chứa ít nhất một video tham chiếu đều bị tính phí gấp 2 lần, bất kể số lượng hoặc thời lượng video đã tải lên
7. **Tham Số Hạt Giống**: Không gửi `seed`; các mô hình Seedance 2.0 Mini không hỗ trợ tham số này