# Seedance 2.0 API Tài liệu tham chiếu API đầy đủ cho các mô hình tạo video Seedance 2.0 của ByteDance. ## Các biến thể mô hình API này hỗ trợ sáu biến thể mô hình: | Mô hình | ID | Mô tả | |-------|-----|-------------| | **Seedance 2.0 Text to Video** | `seedance-v2.0-text-to-video` | Tạo video chất lượng cao từ văn bản | | **Seedance 2.0 Image to Video** | `seedance-v2.0-image-to-video` | Tạo chuyển động cho ảnh với khả năng điều khiển chuyển động | | **Seedance 2.0 Reference to Video** | `seedance-v2.0-reference-to-video` | Tạo video theo hướng dẫn từ video tham chiếu | | **Seedance 2.0 Fast Text to Video** | `seedance-v2.0-fast-text-to-video` | Tạo video từ văn bản nhanh hơn | | **Seedance 2.0 Fast Image to Video** | `seedance-v2.0-fast-image-to-video` | Tạo video từ ảnh nhanh hơn | | **Seedance 2.0 Fast Reference to Video** | `seedance-v2.0-fast-reference-to-video` | Tạo video theo tham chiếu nhanh hơn | ## So sánh nhanh | Tính năng | Mô hình tiêu chuẩn | Mô hình Fast | |---------|-----------------|-------------| | Chất lượng | Chất lượng cao hơn | Tối ưu cho tốc độ | | Thời gian xử lý | 3-8 phút | 1-4 phút | | Khoảng thời lượng | 4-15 giây | 4-15 giây | | Tùy chọn độ phân giải | 480p, 720p, 1080p, 4k | 480p, 720p | | Nội dung tham chiếu | Ảnh, video và âm thanh cho Reference-to-Video | Ảnh, video và âm thanh cho Fast Reference-to-Video | ### 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, cân bằng chất lượng và tốc độ | | `1080p` | Full HD, có trên mọi mô hình Seedance 2.0 tiêu chuẩn | | `4k` | Ultra HD, có trên mọi mô hình Seedance 2.0 tiêu chuẩn | ## Seedance 2.0 Văn bản thành 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-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 nhảy 1 giây | | `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"`, `"1080p"` hoặc `"4k"` | | `aspect_ratio` | string | Tỷ lệ khung hình video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` hoặc `"3:4"` | #### Không bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `sound` | boolean | Có tạo âm thanh hay không. Mặc định là `true`; không ảnh hưởng đến giá | ### 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-text-to-video', prompt: 'A golden retriever running through a sunlit meadow', duration: 6, resolution: '720p', aspect_ratio: '16:9' }) }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Seedance 2.0 Ảnh thành 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-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 nhảy 1 giây | | `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"`, `"1080p"` hoặc `"4k"` | | `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 | #### Không bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `image_end_url` | string | URL ảnh khung hình cuối, không bắt buộc | | `sound` | boolean | Có tạo âm thanh hay không. Mặc định là `true`; không ảnh hưởng đến giá | ### Ví dụ yêu cầu ```javascript { model_name: 'seedance-v2.0-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' } ``` ## Seedance 2.0 Tham chiếu thành 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-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 `<<>>`, `<<>>` và `<<>>` để chỉ rõ phần tử trong các 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 nhảy 1 giây | | `resolution` | string | Độ phân giải đầu ra: `"480p"`, `"720p"`, `"1080p"` hoặc `"4k"` | | `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 Gửi 1-9 ảnh. Chỉ được bỏ ảnh khi cung cấp ít nhất một video tham chiếu. | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `images` | string[] | 1-9 URL ảnh tham chiếu, hoặc mảng rỗng khi `videos` không rỗ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 tối đa 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 tối đa 15 giây; WAV hoặc MP3, tối đa 15 MB mỗi đoạn; cần ít nhất một ả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 thông qua các ký hiệu `<<<...>>>` đượ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 | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `videos[0]` | | `<<>>` | `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 `<<>>` cho nhân vật và `<<>>` cho bối cảnh trong `prompt`. Mỗi ký hiệu phải trỏ đến một phần tử thực sự tồn tại trong mảng tương ứng. #### Không bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `sound` | boolean | Có tạo âm thanh đồng bộ hay không. Mặc định là `true` | ### Ví dụ yêu cầu ```javascript { model_name: 'seedance-v2.0-reference-to-video', prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere', duration: 8, resolution: '1080p', 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.0-reference-to-video', prompt: 'Place the explorer from <<>> in the environment from <<>>, following the camera movement in <<>> and speaking with the reference voice from <<>>', duration: 8, resolution: '1080p', 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'] } ``` ## Các biến thể Fast Các biến thể Fast ưu tiên tốc độ xử lý. Tất cả mô hình Fast chỉ hỗ trợ đầu ra `"480p"` và `"720p"`. Các phần khác trong cấu trúc yêu cầu Fast Văn bản thành video và Fast Ảnh thành video giống mô hình tiêu chuẩn tương ứng, còn Fast Tham chiếu thành video dùng cùng giới hạn nội dung tham chiếu với mô hình tham chiếu tiêu chuẩn. ### Ví dụ yêu cầu Fast ```javascript { model_name: 'seedance-v2.0-fast-reference-to-video', prompt: 'Use image one for the subject, follow the movement from video one, and use audio one for the atmosphere', duration: 8, resolution: '720p', aspect_ratio: '9:16', 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 Fast Tham chiếu thành video với @ (AT) ```javascript { model_name: 'seedance-v2.0-fast-reference-to-video', prompt: 'Have the dancer from <<>> perform the movement from <<>> on the stage in <<>>, using the rhythm from <<>>', duration: 8, resolution: '720p', aspect_ratio: '9:16', sound: true, images: [ 'https://example.com/dancer-reference.jpg', 'https://example.com/stage-reference.jpg' ], videos: ['https://example.com/dance-movement-reference.mp4'], audios: ['https://example.com/rhythm-reference.mp3'] } ``` ### Tham số Seedance 2.0 Fast Tham chiếu thành video #### Bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `model_name` | string | Phải là `"seedance-v2.0-fast-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 `<<>>`, `<<>>` và `<<>>` để chỉ rõ phần tử trong các 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 nhảy 1 giây | | `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 | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `images` | string[] | 1-9 URL ảnh tham chiếu, hoặc mảng rỗng khi `videos` không rỗ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 tối đa 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 tối đa 15 giây; WAV hoặc MP3, tối đa 15 MB mỗi đoạn; cần ít nhất một ảnh hoặc video | Quy tắc đánh số ký hiệu giữ chỗ từ 1 ở trên cũng áp dụng cho mô hình Fast Tham chiếu thành video. #### Không bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `sound` | boolean | Có tạo âm thanh đồng bộ hay không. Mặc định là `true` | ## Giới hạn nội dung Các giới hạn này áp dụng cho ảnh khung hình đầu, ả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 | |-------|---------|--------| | Ả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 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 tệp; chiều rộng và chiều cao đều từ 300-6000 px; tỷ lệ rộng/cao từ 0.4-2.5; tốc độ khung hình từ 24-60 FPS | | Âm thanh | WAV, MP3 | Tối đa 15 MB mỗi tệp | | Nội dung yêu cầu | — | Tối đa 64 MB | Âm thanh và video tham chiếu mỗi loại có giới hạn tổng thời lượng riêng là 15 giây. Số lượng độc lập: tối đa 9 ảnh, 3 video và 3 đ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`. 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á. Tham chiếu thành video cần ít nhất một ảnh hoặc video; không hỗ trợ yêu cầu chỉ có âm thanh. Tải video tham chiếu lên sẽ tăng gấp đôi phí tạo, bất kể số lượng hay 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 `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`: đã nhận tác vụ và đang chờ xử lý - `processing`: đang tạo video - `succeed`: đã tạo video thành công - `failed`: tạo video thất bại ## Thời gian xử lý **Mô hình tiêu chuẩn**: 3-8 phút tùy thời lượng và độ phân giải. **Mô hình Fast**: 1-4 phút với hầu hết cấu hình. Kiểm tra trạng thái mỗi 5-10 giây. ## Thực hành tốt nhất 1. **Chọn biến thể phù hợp**: dùng mô hình Fast để thử nghiệm và mô hình tiêu chuẩn cho đầu ra cuối cùng 2. **Mô tả rõ chuyển động**: đưa mô tả chuyển động cụ thể vào câu lệnh 3. **Chọn độ phân giải**: tất cả mô hình Seedance 2.0 tiêu chuẩn hỗ trợ `480p`, `720p`, `1080p` và `4k`; tất cả mô hình Fast chỉ hỗ trợ `480p` và `720p` 4. **Thứ tự tham chiếu**: sắp xếp `images`, `videos` và `audios` có chủ đích và tham chiếu nhất quán trong câu lệnh 5. **Yêu cầu chỉ có video**: chỉ dùng mảng `images` rỗng khi cung cấp ít nhất một video tham chiếu 6. **Thời lượng nội dung**: giữ mỗi đoạn âm thanh và video tham chiếu dài từ 2 đến 15 giây 7. **Sử dụng âm thanh**: bỏ `sound` để dùng giá trị mặc định `true`, hoặc đặt thành `false` để tắt âm thanh được tạo