Daftar periksa produksi Seedance API untuk tim text-to-video

Prototipe Seedance API dapat terlihat selesai setelah satu video berhasil dibuat. Integrasi produksi baru selesai ketika sistem Anda mampu bertahan terhadap pekerjaan yang lambat, peristiwa duplikat, rute model yang berubah, kegagalan parsial, dan biaya yang tidak pasti.

Perbedaan itu penting karena pembuatan video bukan fitur request-response biasa. Aplikasi mengirim pekerjaan, menunggu, menerima perubahan status, menyimpan output berukuran besar, dan memutuskan apakah kegagalan harus dicoba ulang. Panggilan model hanyalah satu tahap dalam alur kerja yang lebih panjang.

Daftar periksa ini mengubah alur kerja tersebut menjadi kontrak produksi yang dapat ditinjau bersama oleh tim produk, platform, dan keuangan Anda.

Catatan rute saat ini: Katalog model publik Flatkey mencantumkan seedance-2.5 untuk text-to-video dan image-to-video, serta seedance-2.0-i2v untuk image-to-video, saat panduan ini diperiksa pada Senin, 27 Juli 2026. Perlakukan nama-nama tersebut sebagai status katalog, bukan konstanta permanen. Konfirmasikan direktori model Flatkey saat ini sebelum melakukan rilis atau mengubah allowlist.

Jawaban singkat

Jangan hubungkan permintaan yang terlihat oleh pengguna secara langsung ke panggilan penyedia video. Tempatkan lapisan pekerjaan yang tahan lama di antara keduanya.

Jalur produksi minimum Anda sebaiknya adalah:

1. terima dan validasi permintaan pembuatan dari pengguna
2. tetapkan idempotency key dan ID pekerjaan Anda sendiri
3. simpan permintaan sebelum memanggil rute model
4. kirim pekerjaan melalui adapter sisi server
5. proses pembaruan webhook dan polling secara idempotent
6. salin media yang selesai ke penyimpanan yang Anda kendalikan
7. catat latensi, alasan kegagalan, rute model, dan estimasi biaya
8. tampilkan status produk yang stabil dan tidak bergantung pada wording penyedia

Jika salah satu langkah tersebut hilang, integrasi mungkin masih terlihat baik saat demo, tetapi lebih sulit dioperasikan dengan aman.

Mengapa pekerjaan produksi Seedance API berbeda

Generasi teks sering kali menghasilkan respons yang berguna dalam satu pertukaran HTTP. Generasi video biasanya berperilaku seperti pekerjaan batch terdistribusi. Tindakan pengguna dapat melampaui permintaan aplikasi, deployment, sesi browser, atau bahkan URL sementara yang akhirnya menyimpan hasilnya.

Konsekuensi praktisnya mudah diremehkan:

Tujuannya bukan untuk menyembunyikan provider. Tujuannya adalah mencegah perilaku khusus provider menjadi kontrak permanen produk Anda.

1. Bekukan kontrak produk sebelum payload

Mulailah dari pengalaman yang Anda janjikan kepada pengguna, bukan dari field provider yang tersedia hari ini.

Tentukan:

• tipe input yang diterima: hanya teks, gambar plus teks, atau keduanya
• rasio aspek yang didukung dan rentang durasi
• ukuran upload maksimum dan format media yang diterima
• pemeriksaan moderasi dan hak sebelum pengiriman
• pembaruan status yang diharapkan dan perilaku pembatalan
• periode penyimpanan output
• apakah job yang gagal mengonsumsi kredit pengguna
• apa arti “retry” di dalam produk

Kemudian terjemahkan kontrak itu ke route Seedance saat ini di dalam sebuah adapter.

Pemisahan ini melindungi Anda dari dua mode kegagalan umum. Pertama, pembaruan route dapat menambah atau mengganti nama parameter tanpa memaksa penulisan ulang frontend. Kedua, aplikasi Anda dapat menolak kombinasi yang tidak didukung sebelum menghabiskan uang untuk job yang sudah pasti gagal.

2. Gunakan job ID dan idempotency key milik Anda sendiri

Setiap permintaan membutuhkan dua pengenal:

• product job ID: pengenal stabil yang ditampilkan di seluruh sistem Anda
• idempotency key: pengenal yang digunakan untuk mencegah pengiriman duplikat yang tidak disengaja

Jangan gunakan provider task ID sebagai primary key Anda. ID itu tidak ada sampai setelah pengiriman, dan dapat berubah jika Anda secara sengaja mengirim ulang melalui route lain.

Record permintaan sederhana dapat terlihat seperti ini:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Buat record ini sebelum panggilan API keluar. Jika aplikasi crash setelah pengiriman tetapi sebelum menyimpan respons, idempotency key memberi Anda cara untuk melakukan rekonsiliasi alih-alih secara buta menagih untuk generasi lain.

3. Letakkan Seedance di belakang satu adapter sisi server

Pertahankan konstruksi request yang spesifik untuk provider dalam satu modul. Sisa produk Anda harus mengirim perintah yang dinormalisasi seperti:

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

Adapter bertanggung jawab untuk:

• memetakan qualityProfile ke model dan pengaturan yang saat ini tersedia
• menambahkan autentikasi di sisi server
• menerjemahkan pilihan aspek rasio dan durasi Anda ke skema API yang aktif
• mengirimkan tugas
• menormalkan error provider
• menyimpan ID tugas provider
• melaporkan metadata yang cukup untuk analisis biaya dan keandalan

Flatkey memberi tim satu API key, endpoint router yang stabil, saldo bersama, dan visibilitas penggunaan terpusat di seluruh keluarga model. Untuk tim yang sudah menggunakan lapisan akses itu, pertahankan logika async khusus Seedance di adapter, alih-alih menyebarkan asumsi rute ke seluruh codebase. Panduan sebelumnya tentang stable OpenAI-compatible base URL untuk tim Seedance API menjelaskan batasan itu secara lebih rinci.

4. Model alur kerja sebagai state machine

Jangan biarkan string status arbitrer masuk ke logika produk. Normalkan semuanya.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

Hanya izinkan transisi maju kecuali Anda menjalankan proses pemulihan yang eksplisit. Event running yang terlambat tidak boleh menimpa job yang sudah ditandai succeeded. Webhook succeeded yang duplikat tidak boleh memicu dua salinan penyimpanan atau dua notifikasi pelanggan.

Simpan event provider mentah secara terpisah untuk debugging, tetapi buat keputusan produk dari state yang dinormalisasi.

5. Gunakan webhook dan polling bersama-sama

Webhook efisien, tetapi tidak menjamin aplikasi Anda memproses setiap event tepat satu kali dan sesuai urutan. Polling lebih lambat, tetapi berguna untuk rekonsiliasi.

Gunakan keduanya:

• jalur webhook: pembaruan status berlatensi rendah
• jalur polling: pemulihan terjadwal untuk job yang tidak berubah недавно

Webhook handler Anda harus:

1. mengautentikasi callback ketika API aktif mendukung verifikasi
2. mem-parsing event tanpa melakukan pekerjaan berat secara inline
3. menulis fingerprint event ke tabel deduplikasi
4. mengantrikan pemrosesan
5. mengembalikan sukses dengan cepat

Worker rekonsiliasi Anda harus melakukan polling hanya pada job yang masih non-terminal setelah jeda yang wajar. Tambahkan jitter agar deployment tidak menyebabkan ribuan pengecekan status pada saat yang sama.

Bidang webhook dan query yang spesifik untuk penyedia dapat berubah. Verifikasikan terhadap referensi API resmi terkini saat implementasi, alih-alih menyalin payload lama dari sebuah posting blog.

6. Buat keputusan retry berdasarkan kelas kegagalan

“Retry failed jobs” bukanlah sebuah kebijakan. Itu adalah risiko biaya.

Normalisasikan error ke dalam kelas-kelas berikut:

Pembedaan terakhir ini sangat penting. Jika video berhasil digenerate tetapi salinan ke storage Anda gagal, melakukan regenerasi video akan menimbulkan biaya yang tidak perlu dan dapat menghasilkan hasil yang berbeda.

Tetapkan anggaran retry per job. Kebijakan yang wajar mungkin mengizinkan lebih banyak pemeriksaan status dan percobaan penyalinan ke storage dibandingkan pengiriman generasi.

7. Salin output ke storage yang Anda kontrol

Anggap URL hasil yang di-host oleh penyedia sebagai lokasi transfer, bukan aset produk permanen Anda.

Setelah job berhasil:

1. verifikasi bahwa respons berisi jenis media yang diharapkan
2. unduh dengan batas ukuran dan waktu
3. validasi bahwa file tidak kosong atau jelas terpotong
4. hitung checksum
5. salin ke object storage Anda
6. simpan durasi, dimensi, codec, dan ukuran
7. ubah job produk ke succeeded hanya setelah salinan permanen tersedia

Jika produk Anda mengizinkan pengguna mengunduh aset asli dari penyedia sebelum penyalinan selesai, representasikan itu sebagai status sementara yang terpisah. Jangan menjanjikan permanensi secara diam-diam.

8. Tambahkan kontrol biaya sebelum membuka fitur

Job video cukup mahal sehingga batasan produk harus ada sebelum peluncuran publik.

Setidaknya, tentukan:

• batas pengeluaran per key atau per tim
• allowlist model untuk application key
• jumlah maksimum job simultan per akun
• durasi maksimum dan profil kualitas berdasarkan paket
• batas pengiriman harian untuk akun baru atau tidak tepercaya
• circuit breaker ketika tingkat kegagalan atau biaya per keberhasilan meningkat

Dokumentasi publik Flatkey menjelaskan cap per-key, allowlist model opsional, dan visibilitas penggunaan melalui Usage & Logs atau ledger API. Gunakan kontrol tersebut sebagai pagar pengaman pada layer akses, lalu tambahkan kuota di level produk berdasarkan paket Anda sendiri dan risiko penyalahgunaan.

Sebelum mengaktifkan rute baru, bandingkan katalog saat ini dan harga Flatkey. Jangan sematkan harga numerik dari artikel ini ke dalam logika aplikasi; harga dan ketersediaan rute adalah data yang dapat diperbarui.

9. Ukur seluruh pekerjaan, bukan hanya latensi API

Untuk alur kerja Seedance API asinkron, pengiriman yang berhasil tetap dapat menghasilkan pengalaman pelanggan yang buruk.

Lacak setidaknya:

• tingkat penerimaan pengiriman
• waktu tunggu antrean
• waktu pembuatan
• waktu total hingga output yang tahan lama
• tingkat keberhasilan berdasarkan model yang terselesaikan
• tingkat kegagalan berdasarkan kelas kegagalan yang dinormalisasi
• keterlambatan pengiriman webhook
• tingkat pemulihan polling
• tingkat kegagalan penyalinan ke penyimpanan
• biaya per pekerjaan yang dikirim
• biaya per output tahan lama yang berhasil
• jumlah pencegahan pengiriman duplikat

Gunakan persentil, bukan hanya rata-rata. Waktu pembuatan median bisa terlihat sehat sementara sepuluh persen pekerjaan yang paling lambat menghasilkan sebagian besar tiket dukungan.

Catat juga requestedModel dan resolvedModel secara terpisah. Itu membuat perubahan rute terlihat dan memberi Anda bukti untuk keputusan rollback.

10. Kirim perubahan model sebagai migrasi

Perubahan katalog bukan sekadar penggantian string. Perlakukan seperti peningkatan dependensi.

Sebelum memindahkan lalu lintas produksi ke rute Seedance baru:

1. pastikan rute saat ini di direktori model live
2. bandingkan input yang didukung dan batasan output
3. jalankan set evaluasi tetap pada tipe prompt umum Anda
4. bandingkan tingkat keberhasilan, latensi, penerimaan output, dan biaya
5. uji webhook, polling, dan normalisasi kesalahan
6. lakukan canary pada persentase kecil lalu lintas
7. pertahankan rute rollback hingga canary stabil
8. perbarui allowlist model dan runbook operasional

Jika aplikasi Anda mengekspos pengaturan “quality”, petakan ke profil kapabilitas alih-alih ID model permanen. Itu memungkinkan Anda mengubah rute pendukung tanpa merusak API produk.

Daftar periksa kesiapan produksi

Gunakan daftar ini sebagai gerbang peluncuran.

Permintaan dan akses

• [ ] kunci API tetap berada di sisi server
• [ ] kunci aplikasi memiliki batas pengeluaran dan allowlist model
• [ ] setiap permintaan memiliki ID pekerjaan internal dan kunci idempoten
• [ ] input divalidasi sebelum pengiriman
• [ ] rute model Seedance saat ini diperiksa di katalog live

Eksekusi asinkron

• [ ] logika khusus penyedia berada di satu adapter
• [ ] status produk menggunakan mesin status yang dinormalisasi
• [ ] event webhook diautentikasi jika didukung dan dideduplikasi
• [ ] polling merekonsiliasi pekerjaan non-terminal yang usang
• [ ] event yang terlambat atau duplikat tidak dapat membalik status terminal

Keandalan dan biaya

• [ ] perilaku retry bervariasi حسب kelas kegagalan
• [ ] retry pembuatan memiliki anggaran yang ketat
• [ ] retry penyalinan output tidak meregenerasi video yang berhasil
• [ ] batas konkurensi dan batas pekerjaan harian ditegakkan
• [ ] circuit breaker dapat menjeda rute yang menurun kualitasnya

Output dan observabilitas

• [ ] media yang berhasil disalin ke penyimpanan terkontrol
• [ ] metadata output dan checksum disimpan
• [ ] ID model yang diminta dan yang diselesaikan dicatat
• [ ] biaya per output tahan lama yang berhasil diukur
• [ ] operator memiliki runbook untuk job yang macet, gagal, dan duplikat

Di mana Flatkey cocok

Flatkey tidak menghilangkan kebutuhan akan lapisan job video asinkron. Ini mengurangi pekerjaan akses dan tata kelola di sekitar lapisan tersebut: satu akun, satu saldo, kontrol API key, surface router yang stabil, katalog model live, dan catatan penggunaan terpusat.

Untuk integrasi pertama, mulailah dengan Seedance API quickstart untuk tim produk text-to-video yang lebih luas. Saat fitur bergerak menuju produksi, terapkan daftar periksa ini pada lapisan antrean, state, retry, penyimpanan, dan observabilitas di sekitar panggilan model.

Jika tim Anda sedang memutuskan rute saat ini dan kontrol penggunaan mana yang sesuai untuk peluncuran, tinjau model live dan harga sebelum menyetujui konfigurasi produksi.

Pertanyaan yang sering diajukan

Apakah Seedance API sinkron atau asinkron?

Perlakukan pembuatan video sebagai job asinkron. Produk Anda harus mengirimkan pekerjaan, mengembalikan ID job miliknya sendiri, dan memproses pembaruan status melalui webhook dan/atau polling sesuai referensi API saat ini.

Apakah saya harus menggunakan provider task ID sebagai primary key database saya?

Tidak. Buat ID job stabil Anda sendiri sebelum pengiriman. Simpan provider task ID sebagai referensi eksternal agar Anda dapat merekonsiliasi, mengirim ulang, atau mengubah rute tanpa mengubah pengenal produk.

Apakah saya memerlukan webhook dan polling?

Untuk sistem produksi yang tangguh, ya. Webhook menyediakan pembaruan cepat; polling memulihkan job yang event-nya tertunda, terlewat, atau tidak diproses.

Kapan aman untuk mencoba ulang job Seedance yang gagal?

Coba ulang hanya setelah mengklasifikasikan kegagalan. Kegagalan kapasitas dan jaringan mungkin dapat dicoba ulang. Kegagalan validasi, autentikasi, keselamatan, atau kegagalan terminal lainnya biasanya memerlukan perubahan konfigurasi atau pengguna. Jika pengiriman time out, lakukan rekonsiliasi berdasarkan idempotency key sebelum mengirim job berbayar lainnya.

Apakah saya harus menyimpan video yang dihasilkan sendiri?

Ya. Salin output yang selesai ke penyimpanan yang Anda kontrol, validasi file, dan simpan metadata-nya. URL hasil yang di-host provider tidak boleh dianggap sebagai penyimpanan produk permanen kecuali syarat saat ini secara eksplisit menjamin perilaku tersebut.

Bagaimana saya harus menangani versi model Seedance yang baru?

Perlakukan sebagai migrasi: verifikasi katalog saat ini, jalankan set evaluasi tetap, bandingkan kualitas, latensi, kegagalan, dan biaya, lakukan canary traffic, dan pertahankan rute rollback sampai perubahan stabil.

Model Seedance mana yang harus saya hardcode?

Hindari meng-hardcode model secara permanen berdasarkan artikel statis. Resolusikan profil kapabilitas produk ke model yang tercantum di direktori model Flatkey saat ini, dan simpan rute yang dipilih dalam konfigurasi agar operator dapat mengubahnya dengan aman.