
Seedance 2.5 Flash API là bản nhanh hơn, chi phí thấp hơn của Seedance 2.5 API, và trên PoYo nó chỉ là một model ID: seedance-2.5-flash. ByteDance phát hành mô hình này vào ngày 12 tháng 11 năm 2026; trang mô hình Seedance 2.5 Flash có playground và giá hiện hành. Hướng dẫn này đưa bạn từ yêu cầu cURL đầu tiên đến một vòng lặp production bằng Python, dựa trên schema trong tài liệu Seedance 2.5 Flash API, được kiểm tra vào ngày 16 tháng 11 năm 2026.
Tổng quan nhanh về Seedance 2.5 Flash API
| Mục | Giá trị |
|---|---|
| Endpoint gửi | POST https://api.poyo.ai/api/generate/submit |
| Endpoint trạng thái | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Header xác thực | Authorization: Bearer $POYO_API_KEY |
| Model ID | seedance-2.5-flash (slug trang seedance-2-5-flash không phải model ID) |
| Trường bắt buộc | prompt, duration |
| Thời lượng | Số giây nguyên, 4–30 |
| Độ phân giải | 480p hoặc 720p, mặc định 720p |
| Tỷ lệ khung hình | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, mặc định auto |
| Âm thanh | generate_audio, mặc định true |
| Trả kết quả | Tác vụ bất đồng bộ: polling trạng thái hoặc đặt callback_url |
Yêu cầu Seedance 2.5 API đầu tiên bằng cURL
Export khóa của bạn thành POYO_API_KEY và giữ nó trên máy chủ, không bao giờ đưa vào mã trình duyệt. Đây là yêu cầu tạo video từ văn bản 5 giây ở 480p, một bài thử đầu tiên chi phí thấp với 92,5 credit:
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
Gửi thành công sẽ trả về code: 200 và một object data gồm task_id, status (luôn là not_started ngay sau khi gửi) và created_time. Đây là biên nhận, chưa phải video. Hãy lưu task_id, rồi truy vấn nó:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Trạng thái lần lượt đi qua not_started, running, finished và failed. Khi tác vụ ở trạng thái finished, URL video nằm trong data.files[].file_url với file_type: "video"; khi failed, hãy đọc data.error_message. File được tạo chỉ truy cập được trong 3 ngày, nên hãy sao chép chúng sang kho lưu trữ của bạn.
Python: gửi và polling với hạn chót cứng
Tài liệu trạng thái khuyến nghị polling mỗi 2–5 giây, giãn thời gian chờ (backoff) khi gặp 429 và 5xx, và luôn đặt timeout. Vòng lặp dưới đây làm cả ba việc đó và không bao giờ gửi lại khi hết thời gian, vì lần gửi thứ hai là một tác vụ thứ hai bị tính phí.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
Để tham khảo, trong thử nghiệm của PoYo ngày 16 tháng 11 năm 2026, một clip 4 giây ở 480p hoàn tất trong khoảng hai phút và một clip 30 giây ở 720p trong chưa đầy ba phút, tính từ đầu đến cuối. Thời gian thay đổi theo tải, nên hạn chót 15 phút là giới hạn an toàn, không phải ước tính.
Bỏ qua polling: dùng callback_url
Thêm callback_url ở cấp cao nhất, cạnh model. Khi tác vụ chuyển sang finished hoặc failed, PoYo gửi một POST có body là object dữ liệu tác vụ (task_id, status, files, created_time, error_message), không có lớp bọc code/data. Theo tài liệu video webhook:
- URL phải là HTTPS công khai, tối đa 2048 ký tự, không dùng IP nội bộ.
- Phản hồi bằng mã 2xx trong vòng 30 giây; các lần gửi thất bại được thử lại tối đa 5 lần với exponential backoff.
- Xác minh
X-Webhook-Signaturetheo công thứcbase64(HMAC-SHA256(task_id + "." + timestamp, key)), vớitimestamplấy từX-Webhook-Timestampvà khóa lấy từGET /api/api-keys/webhook-secret. - Viết handler theo kiểu idempotent. Nếu mọi lần thử lại đều thất bại, endpoint trạng thái vẫn giữ kết quả.
Ba chế độ đầu vào, kèm body JSON
API chọn chế độ dựa trên media bạn gửi. Không có trường mode.
| Chế độ | Được chọn khi | Tỷ lệ khung hình |
|---|---|---|
| Tham chiếu sang video | Bất kỳ trường nào trong reference_image_urls, reference_video_urls, reference_audio_urls không rỗng | Bất kỳ giá trị được hỗ trợ nào |
| Ảnh sang video (khung hình đầu/cuối) | image_urls không rỗng | auto hoặc bỏ trống; đầu ra theo khung hình đầu |
| Văn bản sang video | Không có media | Bất kỳ giá trị được hỗ trợ nào |
image_urls và các trường tham chiếu phải gửi trong các yêu cầu riêng. Các body dưới đây là ví dụ có trong tài liệu.
Văn bản sang video (30 giây ở 720p, với danh sách cảnh quay theo mốc thời gian trong prompt):
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
Khung hình đầu và cuối (một URL cố định cảnh mở đầu; URL thứ hai cố định cảnh kết):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
Tham chiếu sang video (gọi các file theo thứ tự tải lên là @Image1, @Video1, @Audio1):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
Quy tắc kiểm tra cần áp dụng trước khi gửi
Kiểm tra các quy tắc này ở phía client giúp tiết kiệm một lượt gọi và cho người dùng thông báo rõ ràng hơn một lỗi 400 chung chung.
| Trường | Quy tắc |
|---|---|
prompt | Bắt buộc, chuỗi không rỗng |
duration | Số nguyên bắt buộc, 4–30 |
resolution | Chỉ 480p hoặc 720p; 1080p cần seedance-2.5 |
aspect_ratio | Một trong bảy giá trị; dùng auto hoặc bỏ trống khi có image_urls |
image_urls | 1–2 URL (khung hình đầu trước, rồi khung hình cuối); JPEG, PNG hoặc WebP, tối đa 30 MB mỗi file; không kết hợp với các trường tham chiếu |
reference_image_urls | Tối đa 10; JPEG, PNG hoặc WebP, tối đa 30 MB mỗi file |
reference_video_urls | Tối đa 5; MP4 hoặc MOV, mỗi file 2–30 giây và tối đa 200 MB; tổng thời lượng tối đa 30 giây |
reference_audio_urls | Tối đa 5; MP3 hoặc WAV, mỗi file 2–30 giây và tối đa 15 MB; tổng thời lượng tối đa 30 giây; cần có ảnh hoặc video tham chiếu |
| Mọi URL media | HTTP hoặc HTTPS công khai, tải trực tiếp được (không có trang đăng nhập hay bản xem trước có hạn) |
Tổng thời lượng tham chiếu được kiểm tra khi gửi tác vụ. Schema cũng đặt additionalProperties: false cho input, nên đừng gửi các trường từ API của nhà cung cấp khác như seed hay negative_prompt.
Các lỗi nên xử lý
Luôn đọc trường code trong body: một số lỗi kiểm tra từ endpoint gửi trả về HTTP 200 kèm "code": 400. Tài liệu mã lỗi liệt kê các lỗi sau:
| Mã | Loại | Cách xử lý |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Sửa yêu cầu hoặc media; đừng thử lại nguyên trạng |
401 | authentication_error | Kiểm tra header Bearer và xem khóa còn tồn tại không |
402 | insufficient_credits_error | Nạp thêm credit, rồi gửi lại |
429 | Giới hạn tần suất | Giãn thời gian chờ (1 giây, 2 giây, 4 giây...) trước khi polling hoặc gửi lại |
500, 502, 503 | Máy chủ hoặc upstream | Thử lại lệnh gọi trạng thái với backoff; kiểm tra trạng thái trước khi gửi lại |
Tác vụ failed | Có error_message | Ghi log task ID; tác vụ thất bại báo credits_amount: 0 |
Hóa đơn đầu tiên được tính thế nào
Khi không có video tham chiếu, chi phí bằng số giây đầu ra nhân với đơn giá mỗi giây: 18,5 credit ($0,0925) ở 480p, 41 credit ($0,205) ở 720p, với 1 credit = $0,005. Âm thanh được tạo không tính thêm phí.
| Yêu cầu ở trên | Số giây tính phí | Credit | USD |
|---|---|---|---|
| Thử cURL, 5 giây 480p | 5 | 92.5 | $0.4625 |
| Văn bản sang video, 30 giây 720p | 30 | 1,230 | $6.15 |
| Khung hình đầu/cuối, 5 giây 720p | 5 | 205 | $1.025 |
| Ảnh tham chiếu + âm thanh, 6 giây 480p | 6 | 111 | $0.555 |
Thêm bất kỳ reference_video_urls nào sẽ chuyển sang đơn giá có video thấp hơn (11,5 credit ở 480p, 25,5 ở 720p), áp dụng cho số giây tính phí: thời lượng đầu ra cộng với độ dài của từng video tham chiếu, làm tròn xuống thành số giây nguyên. Bảng phân tích giá Seedance 2.5 API tính chi tiết các trường hợp đó. Phí của một tác vụ đã hoàn tất hiển thị trong trường credits_amount của phản hồi trạng thái.
Chuyển sang Seedance 2.5 để có 1080p
Các trường yêu cầu giống nhau, nên chuyển một job từ Flash sang mô hình Seedance 2.5 tiêu chuẩn chỉ là đổi model ID:
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
Hai chi tiết cần lưu ý: tài liệu seedance-2.5 liệt kê resolution là bắt buộc, nên luôn gửi trường này, và mô hình tiêu chuẩn cho phép tối đa 30 ảnh, 10 video và 10 âm thanh tham chiếu. Ở 1080p, giá là 114 credit ($0,57) mỗi giây. Để quyết định định tuyến, xem Seedance 2.5 Flash vs Seedance 2.5; để so sánh Seedance 2.5 với nhà cung cấp khác, xem Kling 4.0 vs Seedance 2.5.
Câu hỏi thường gặp
Model ID của Seedance 2.5 Flash API là gì? seedance-2.5-flash, dùng dấu chấm. Dạng có gạch nối seedance-2-5-flash chỉ là slug của trang mô hình.
Seedance 2.5 Flash API có hỗ trợ 1080p không? Không. Nó nhận 480p và 720p. Gửi cùng body với "model": "seedance-2.5" và "resolution": "1080p" để có 1080p gốc.
Làm sao để tắt âm thanh trong Seedance 2.5 API? Đặt "generate_audio": false để có clip không tiếng, hoặc giữ âm thanh và loại bỏ từng lớp riêng trong prompt, chẳng hạn "no background music".
Có thể dùng khung hình đầu và ảnh tham chiếu trong cùng một yêu cầu Seedance 2.5 Flash không? Không. image_urls và các trường reference_* phải được gửi trong các yêu cầu riêng.
Một tác vụ Seedance 2.5 Flash API mất bao lâu? Trong thử nghiệm của PoYo ngày 16 tháng 11 năm 2026, khoảng hai phút cho 4 giây ở 480p và chưa đầy ba phút cho 30 giây ở 720p, tính từ đầu đến cuối. Hãy polling hoặc dùng callback thay vì giữ một yêu cầu mở.
Tôi có bị tính phí nếu tác vụ Seedance 2.5 Flash thất bại không? Không. Tác vụ thất bại không bị tính phí, và trạng thái của chúng hiển thị credits_amount: 0.