how-tos

Seedance 2.5 API: Panduan Memanggil Seedance 2.5 Flash dengan cURL dan Python

Poyo.ai Team
10 min read
Share:

Kurir bersepeda berpacu dengan menara jam saat fajar, ilustrasi editorial untuk panduan Seedance 2.5 Flash API

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

ItemNilai
Endpoint pengirimanPOST https://api.poyo.ai/api/generate/submit
Endpoint statusGET https://api.poyo.ai/api/generate/status/{task_id}
Header autentikasiAuthorization: Bearer $POYO_API_KEY
ID modelseedance-2.5-flash (slug halaman seedance-2-5-flash bukan ID model)
Field wajibprompt, duration
DurasiDetik bulat, 4–30
Resolusi480p atau 720p, default 720p
Rasio aspekauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, default auto
Audiogenerate_audio, default true
Pengiriman hasilTugas 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-Signature sebagai base64(HMAC-SHA256(task_id + "." + timestamp, key)), dengan timestamp dari X-Webhook-Timestamp dan kunci dari GET /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.

ModeDipilih saatRasio aspek
Reference-to-videoSalah satu dari reference_image_urls, reference_video_urls, reference_audio_urls tidak kosongNilai apa pun yang didukung
Image-to-video (frame pertama/terakhir)image_urls tidak kosongauto atau dihilangkan; output mengikuti frame pertama
Text-to-videoTanpa mediaNilai 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.

FieldAturan
promptWajib, string tidak kosong
durationInteger wajib, 4–30
resolutionHanya 480p atau 720p; 1080p memerlukan seedance-2.5
aspect_ratioSalah satu dari tujuh nilai; gunakan auto atau hilangkan jika memakai image_urls
image_urls1–2 URL (frame pertama, lalu frame terakhir); JPEG, PNG, atau WebP, masing-masing hingga 30 MB; tidak boleh digabung dengan field referensi
reference_image_urlsHingga 10; JPEG, PNG, atau WebP, masing-masing hingga 30 MB
reference_video_urlsHingga 5; MP4 atau MOV, masing-masing 2–30 dtk dan hingga 200 MB; total durasi paling lama 30 dtk
reference_audio_urlsHingga 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 mediaHTTP 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:

KodeTipeYang perlu dilakukan
400validation_error, file_format_error, content_moderation_errorPerbaiki permintaan atau media; jangan ulangi tanpa perubahan
401authentication_errorPeriksa header Bearer dan pastikan kunci masih ada
402insufficient_credits_errorIsi ulang, lalu kirim ulang
429Rate limitLakukan backoff (1 dtk, 2 dtk, 4 dtk...) sebelum polling atau mengirim lagi
500, 502, 503Server atau upstreamUlangi panggilan status dengan backoff; periksa status sebelum mengirim ulang
Tugas failederror_message terisiCatat 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 atasDetik yang ditagihKreditUSD
Uji cURL, 5 dtk 480p592.5$0.4625
Text-to-video, 30 dtk 720p301,230$6.15
Frame pertama/terakhir, 5 dtk 720p5205$1.025
Gambar referensi + audio, 6 dtk 480p6111$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.

Share: