# Seedance 2.5 API

Tài liệu tham khảo API đầy đủ cho các mô hình tạo video Seedance 2.5 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.5 Text to Video** | `seedance-v2.5-text-to-video` | Tạo video chất lượng cao từ văn bản |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | Tạo video từ khung hình đầu hoặc khung hình đầu và cuối |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | Tạo video dựa trên hình ảnh, video và âm thanh tham chiếu |

## So sánh nhanh

| Tính năng | Văn bản thành video | Hình ảnh thành video | Tham chiếu thành video |
|---------|---------------|----------------|--------------------|
| Phạm vi thời lượng | 4-30 giây | 4-30 giây | 4-30 giây |
| Tùy chọn độ phân giải | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Tỷ lệ khung hình | Bắt buộc | Không hỗ trợ | Bắt buộc |
| Tư liệu bắt buộc | Không có | Ảnh khung hình đầu | Không có |
| Tư liệu tùy chọn | Không có | Ảnh khung hình cuối | Hình ảnh, video và âm thanh |

### Tỷ lệ khung hình được hỗ trợ

Văn bản thành video và Tham chiếu thành video hỗ trợ:

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

Hình ảnh thành video không hỗ trợ tham số `aspect_ratio`.

### Tùy chọn độ phân giải

| Độ phân giải | Mô tả |
|------------|-------------|
| `480p` | Độ nét tiêu chuẩn |
| `720p` | Độ nét cao |
| `1080p` | Full HD |

## Seedance 2.5 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.5-text-to-video"` |
| `prompt` | string | Câu lệnh tạo video |
| `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"` hoặc `"1080p"` |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-30), bước tăng 1 |
| `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 hay không. Mặc định là `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.5-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    resolution: '720p',
    duration: 8,
    aspect_ratio: '16:9',
    sound: true
  })
});

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

## Seedance 2.5 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.5-image-to-video"` |
| `prompt` | string | Câu lệnh tạo video |
| `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"` hoặc `"1080p"` |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-30), bước tăng 1 |
| `image_url` | string | URL ảnh khung hình đầu |

#### Tùy chọn

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `image_end_url` | string | URL ảnh khung hình cuối tùy chọn |
| `sound` | boolean | Có tạo âm thanh hay không. Mặc định là `true` |

> Không đưa `aspect_ratio` vào yêu cầu Hình ảnh thành video. Mô hình này không hỗ trợ tham số đó.

### Ví dụ yêu cầu

```javascript
{
  model_name: 'seedance-v2.5-image-to-video',
  image_url: 'https://example.com/first-frame.jpg',
  image_end_url: 'https://example.com/last-frame.jpg',
  prompt: 'Camera slowly pulls back to reveal the full landscape',
  resolution: '720p',
  duration: 8,
  sound: true
}
```

## Seedance 2.5 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.5-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 tùy chọn dùng tính năng tham chiếu @ (AT) với `<<<image_N>>>`, `<<<video_N>>>` và `<<<audio_N>>>` để chỉ rõ các phần tử trong mảng tư liệu tương ứng |
| `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"` hoặc `"1080p"` |
| `duration` | integer | Thời lượng video tính bằng số giây nguyên (4-30), bước tăng 1 |
| `aspect_ratio` | string | Tỷ lệ khung hình video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` hoặc `"3:4"` |

#### Tư liệu tham chiếu

Tất cả tư liệu tham chiếu đều là tùy chọn. Hỗ trợ yêu cầu chỉ có hình ảnh, chỉ có video, chỉ có âm thanh và không có tư liệu tham chiếu. Khi tạo không có tham chiếu, nên dùng Văn bản thành video.

| Tham số | Kiểu | Mô tả |
|-----------|------|-------------|
| `images` | string[] | 0-30 URL hình ảnh tham chiếu; xem Giới hạn tư liệu bên dưới |
| `videos` | string[] | 0-10 URL video tham chiếu định dạng MP4 hoặc MOV; mỗi video phải dài 2-30 giây, tổng thời lượng tối đa 30 giây |
| `audios` | string[] | 0-10 URL âm thanh tham chiếu định dạng WAV hoặc MP3; mỗi đoạn phải dài 2-30 giây và không quá 15 MB, tổng thời lượng không được vượt quá 30 giây |

#### Ký hiệu giữ chỗ tham chiếu @ (AT)

Tính năng @ (AT) liên kết tư liệu tham chiếu với câu lệnh qua các ký hiệu giữ chỗ có đánh số `<<<...>>>`. Mỗi loại tư liệu được đánh số độc lập từ `1` theo thứ tự trong 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]` |

Ví dụ, nếu ảnh đầu tiên là tham chiếu nhân vật và ảnh thứ hai là tham chiếu bối cảnh, hãy dùng `<<<image_1>>>` cho nhân vật và `<<<image_2>>>` cho bối cảnh trong `prompt`. Mỗi ký hiệu giữ chỗ phải trỏ đến một phần tử thực sự 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 hay không. Mặc định là `true` |

### Ví dụ yêu cầu

```javascript
{
  model_name: 'seedance-v2.5-reference-to-video',
  prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere',
  resolution: '720p',
  duration: 8,
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/subject-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/atmosphere-reference.mp3']
}
```

### Ví dụ yêu cầu Tham chiếu thành video với @ (AT)

```javascript
{
  model_name: 'seedance-v2.5-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>>>',
  resolution: '720p',
  duration: 10,
  aspect_ratio: '16:9',
  sound: true,
  images: [
    'https://example.com/explorer-reference.jpg',
    'https://example.com/environment-reference.png'
  ],
  videos: ['https://example.com/camera-movement-reference.mp4'],
  audios: ['https://example.com/voice-reference.mp3']
}
```

## Giới hạn tư liệu

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

| Tư liệu | Định dạng | Giới hạn |
|-------|---------|--------|
| Hình ảnh | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Mỗi ảnh phải nhỏ hơn 30 MB; chiều rộng và chiều cao đều trong khoảng 300-6000 px; tỷ lệ rộng/cao là 0.4-2.5 |
| Video | MP4, MOV | Tối đa 200 MB mỗi video; chiều rộng và chiều cao đều trong khoảng 300-6000 px; tỷ lệ rộng/cao là 0.4-2.5; tốc độ khung hình là 24-60 FPS |
| Âm thanh | WAV, MP3 | Tối đa 15 MB mỗi đoạn |
| 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à 30 giây cho từng loại. Số lượng cũng độc lập: tối đa 30 ảnh, 10 video và 10 đoạn âm thanh. Thêm video không làm giảm số ả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`. Tùy chọn âm thanh mặc định là `true`; tùy chọn này và âm thanh tham chiếu đều không ảnh hưởng đến giá.

## Đị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 `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 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ý

Thời gian xử lý thay đổi theo thời lượng, độ phân giải và tình trạng hàng đợi hiện tạ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. **Tham số bắt buộc**: luôn cung cấp `resolution` và `duration`, đồng thời cung cấp `aspect_ratio` cho Văn bản thành video và Tham chiếu thành video
2. **Tỷ lệ Hình ảnh thành video**: không gửi `aspect_ratio` trong yêu cầu Hình ảnh thành video
3. **Video tham chiếu**: video là tùy chọn; thời lượng từng video và tổng thời lượng phải nằm trong giới hạn được nêu
4. **Hình ảnh tham chiếu**: hình ảnh là tùy chọn độc lập với video và âm thanh; gửi tối đa 30 URL ảnh thuộc định dạng được hỗ trợ
5. **Âm thanh tham chiếu**: mỗi đoạn phải dài 2-30 giây và không quá 15 MB, tổng thời lượng không quá 30 giây
6. **Thứ tự tham chiếu**: sắp xếp `images`, `videos` và `audios` theo thứ tự mong muốn và tham chiếu nhất quán trong câu lệnh
7. **Âm thanh**: bỏ qua `sound` để dùng mặc định `true`, hoặc đặt `false` để tắt tạo âm thanh