
Seedance 2.5 Flash API adalah tingkat Seedance 2.5 API yang lebih cepat dan lebih murah, dan di PoYo hanya memakai satu ID model: seedance-2.5-flash. ByteDance merilisnya pada 12 November 2026; halaman model Seedance 2.5 Flash menyediakan playground dan harga terkini. Panduan ini membawa Anda dari permintaan cURL pertama hingga loop produksi di Python, menggunakan skema di dokumentasi Seedance 2.5 Flash API yang diperiksa pada 16 November 2026.
Seedance 2.5 Flash API secara ringkas
| Item | Nilai |
|---|---|
| Endpoint pengiriman | POST https://api.poyo.ai/api/generate/submit |
| Endpoint status | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Header autentikasi | Authorization: Bearer $POYO_API_KEY |
| ID model | seedance-2.5-flash (slug halaman seedance-2-5-flash bukan ID model) |
| Field wajib | prompt, duration |
| Durasi | Detik bulat, 4–30 |
| Resolusi | 480p atau 720p, default 720p |
| Rasio aspek | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, default auto |
| Audio | generate_audio, default true |
| Pengiriman hasil | Tugas asinkron: lakukan polling status atau atur callback_url |
Permintaan Seedance 2.5 API pertama Anda dengan cURL
Ekspor kunci Anda sebagai POYO_API_KEY dan simpan di server, jangan pernah di kode browser. Ini adalah permintaan text-to-video 5 detik pada 480p, uji pertama berbiaya rendah seharga 92,5 kredit:
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"
}
}'
Pengiriman yang berhasil mengembalikan code: 200 dan objek data berisi task_id, status (selalu not_started tepat setelah pengiriman), dan created_time. Ini adalah tanda terima, bukan video. Simpan task_id, lalu kueri:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status bergerak melalui not_started, running, finished, dan failed. Saat tugas finished, URL video ada di data.files[].file_url dengan file_type: "video"; saat failed, baca data.error_message. File yang dihasilkan tetap bisa diakses selama 3 hari, jadi salin ke penyimpanan Anda sendiri.
Python: kirim dan polling dengan tenggat yang tegas
Dokumentasi status menyarankan polling setiap 2–5 detik, melakukan backoff saat 429 dan 5xx, dan selalu mengatur timeout. Loop di bawah melakukan ketiganya dan tidak pernah mengirim ulang saat timeout, karena pengiriman kedua berarti tugas kedua yang ditagih.
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)
Sebagai referensi, dalam pengujian PoYo pada 16 November 2026, klip 4 detik 480p selesai dalam sekitar dua menit dan klip 30 detik 720p dalam waktu kurang dari tiga menit, dari awal hingga akhir. Waktunya bervariasi tergantung beban, jadi tenggat 15 menit adalah batas pengaman, bukan perkiraan.
Lewati polling: gunakan callback_url
Tambahkan callback_url di level teratas, di samping model. Saat tugas menjadi finished atau failed, PoYo mengirim POST yang body-nya adalah objek data tugas (task_id, status, files, created_time, error_message) tanpa pembungkus code/data. Menurut dokumentasi webhook video:
- URL harus berupa HTTPS publik, paling panjang 2048 karakter, tanpa IP privat.
- Balas dengan 2xx dalam 30 detik; pengiriman yang gagal diulang hingga 5 kali dengan exponential backoff.
- Verifikasi
X-Webhook-Signaturesebagaibase64(HMAC-SHA256(task_id + "." + timestamp, key)), dengantimestampdariX-Webhook-Timestampdan kunci dariGET /api/api-keys/webhook-secret. - Buat handler yang idempoten. Jika semua percobaan ulang gagal, endpoint status tetap menyimpan hasilnya.
Tiga mode input, dengan body JSON
API memilih mode berdasarkan media yang Anda kirim. Tidak ada field mode.
| Mode | Dipilih saat | Rasio aspek |
|---|---|---|
| Reference-to-video | Salah satu dari reference_image_urls, reference_video_urls, reference_audio_urls tidak kosong | Nilai apa pun yang didukung |
| Image-to-video (frame pertama/terakhir) | image_urls tidak kosong | auto atau dihilangkan; output mengikuti frame pertama |
| Text-to-video | Tanpa media | Nilai apa pun yang didukung |
image_urls dan field referensi dikirim dalam permintaan terpisah. Body berikut adalah contoh yang terdokumentasi.
Text-to-video (30 detik pada 720p, dengan daftar shot berwaktu di dalam 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
}
}
Frame pertama dan terakhir (satu URL menetapkan pembuka; URL kedua menetapkan akhir):
{
"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"
}
}
Reference-to-video (rujuk file berdasarkan urutan unggah sebagai @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"
}
}
Aturan validasi yang perlu diterapkan sebelum mengirim
Memeriksa aturan ini di sisi klien menghemat satu kali bolak-balik dan memberi pengguna Anda pesan yang lebih jelas daripada 400 generik.
| Field | Aturan |
|---|---|
prompt | Wajib, string tidak kosong |
duration | Integer wajib, 4–30 |
resolution | Hanya 480p atau 720p; 1080p memerlukan seedance-2.5 |
aspect_ratio | Salah satu dari tujuh nilai; gunakan auto atau hilangkan jika memakai image_urls |
image_urls | 1–2 URL (frame pertama, lalu frame terakhir); JPEG, PNG, atau WebP, masing-masing hingga 30 MB; tidak boleh digabung dengan field referensi |
reference_image_urls | Hingga 10; JPEG, PNG, atau WebP, masing-masing hingga 30 MB |
reference_video_urls | Hingga 5; MP4 atau MOV, masing-masing 2–30 dtk dan hingga 200 MB; total durasi paling lama 30 dtk |
reference_audio_urls | Hingga 5; MP3 atau WAV, masing-masing 2–30 dtk dan hingga 15 MB; total durasi paling lama 30 dtk; memerlukan gambar atau video referensi |
| Semua URL media | HTTP atau HTTPS publik, bisa diunduh langsung (tanpa halaman login atau pratinjau yang kedaluwarsa) |
Total durasi referensi diperiksa saat tugas dikirim. Skema juga menetapkan additionalProperties: false pada input, jadi jangan kirim field dari API vendor lain seperti seed atau negative_prompt.
Error yang perlu ditangani
Selalu baca field code di body: sebagian error validasi dari endpoint pengiriman dikembalikan dengan HTTP 200 dan "code": 400. Referensi kode error mencantumkan hal berikut:
| Kode | Tipe | Yang perlu dilakukan |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Perbaiki permintaan atau media; jangan ulangi tanpa perubahan |
401 | authentication_error | Periksa header Bearer dan pastikan kunci masih ada |
402 | insufficient_credits_error | Isi ulang, lalu kirim ulang |
429 | Rate limit | Lakukan backoff (1 dtk, 2 dtk, 4 dtk...) sebelum polling atau mengirim lagi |
500, 502, 503 | Server atau upstream | Ulangi panggilan status dengan backoff; periksa status sebelum mengirim ulang |
Tugas failed | error_message terisi | Catat ID tugas; tugas yang gagal melaporkan credits_amount: 0 |
Cara tagihan pertama dihitung
Tanpa video referensi, biaya adalah jumlah detik output dikali tarif per detik: 18,5 kredit ($0.0925) pada 480p, 41 kredit ($0.205) pada 720p, dengan 1 kredit = $0.005. Audio yang dihasilkan tidak menambah biaya.
| Permintaan di atas | Detik yang ditagih | Kredit | USD |
|---|---|---|---|
| Uji cURL, 5 dtk 480p | 5 | 92.5 | $0.4625 |
| Text-to-video, 30 dtk 720p | 30 | 1,230 | $6.15 |
| Frame pertama/terakhir, 5 dtk 720p | 5 | 205 | $1.025 |
| Gambar referensi + audio, 6 dtk 480p | 6 | 111 | $0.555 |
Menambahkan reference_video_urls apa pun akan beralih ke tarif dengan video yang lebih rendah (11,5 kredit pada 480p, 25,5 pada 720p) yang diterapkan ke detik yang ditagih: durasi output ditambah durasi setiap video referensi yang dibulatkan ke bawah ke detik penuh. Rincian harga Seedance 2.5 API menghitung kasus-kasus tersebut. Biaya untuk tugas yang selesai muncul sebagai credits_amount di respons status.
Beralih ke Seedance 2.5 untuk 1080p
Field permintaannya sama, jadi memindahkan job dari Flash ke model Seedance 2.5 standar cukup dengan mengganti ID model:
{
"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"
}
}
Dua detail: dokumentasi seedance-2.5 mencantumkan resolution sebagai wajib, jadi selalu kirimkan, dan model standar mengizinkan hingga 30 gambar, 10 video, dan 10 audio referensi. Pada 1080p, biayanya 114 kredit ($0.57) per detik. Untuk keputusan routing, lihat Seedance 2.5 Flash vs Seedance 2.5; untuk perbandingan Seedance 2.5 dengan vendor lain, lihat Kling 4.0 vs Seedance 2.5.
Pertanyaan yang sering diajukan
Apa ID model untuk Seedance 2.5 Flash API? seedance-2.5-flash, dengan titik. seedance-2-5-flash yang memakai tanda hubung hanyalah slug halaman model.
Apakah Seedance 2.5 Flash API mendukung 1080p? Tidak. API ini menerima 480p dan 720p. Kirim body yang sama dengan "model": "seedance-2.5" dan "resolution": "1080p" untuk 1080p native.
Bagaimana cara mematikan audio di Seedance 2.5 API? Atur "generate_audio": false untuk klip tanpa suara, atau biarkan audio aktif dan hilangkan lapisan tertentu lewat prompt, misalnya "no background music".
Bisakah saya memakai frame pertama dan gambar referensi dalam satu permintaan Seedance 2.5 Flash? Tidak. image_urls dan field reference_* harus dikirim dalam permintaan terpisah.
Berapa lama tugas Seedance 2.5 Flash API berjalan? Dalam pengujian PoYo pada 16 November 2026, sekitar dua menit untuk 4 detik pada 480p dan kurang dari tiga menit untuk 30 detik pada 720p, dari awal hingga akhir. Lakukan polling atau gunakan callback alih-alih menahan permintaan tetap terbuka.
Apakah saya ditagih jika tugas Seedance 2.5 Flash gagal? Tidak. Tugas yang gagal tidak ditagih, dan statusnya menampilkan credits_amount: 0.