Seedance API untuk tim produk text-to-video

Jika tim produk Anda ingin cara paling cepat dan aman untuk mengevaluasi akses Seedance API, langkah pertama yang tepat bukanlah membangun alur kerja video penuh pada hari pertama. Melainkan membuktikan tiga dasar dengan permukaan integrasi sekecil mungkin:

1. kunci Flatkey Anda terautentikasi dengan benar
2. aplikasi Anda dapat memanggil https://router.flatkey.ai/v1
3. tim Anda dapat melihat permintaan di Usage Logs sebelum Anda menghubungkan job video async

Itulah quickstart minim hambatan yang dibahas halaman ini.

Pada Jumat, 17 Juli 2026, quickstart publik Flatkey masih memberi tahu developer untuk menggunakan Bearer auth, base URL yang kompatibel dengan OpenAI https://router.flatkey.ai/v1, dan POST /v1/chat/completions untuk smoke test pertama. Katalog model live Flatkey juga secara publik mencantumkan seedance-2.5 untuk text-to-video plus image-to-video, serta seedance-2.0-i2v untuk image-to-video. Halaman API publik Seedance sendiri masih menggambarkan alur kerja video sebagai pembuatan tugas async, polling status, webhook, dan kredit berbasis penggunaan.

Kombinasi itu penting untuk onboarding: pola akses router memang sederhana, tetapi alur pembuatan video yang sebenarnya bukan panggilan chat sinkron. Tim produk sebaiknya memvalidasi router dengan request sekecil mungkin terlebih dahulu, lalu hanya mengganti model dan alur job yang mereka butuhkan untuk evaluasi Seedance.

Jawaban singkat

Gunakan urutan ini saat Anda menginginkan jalur onboarding Seedance yang dapat ditinjau dengan komponen seminimal mungkin.

Langkah	Yang digunakan	Yang dibuktikan
1. Buat kunci	Kunci API Flatkey yang diawali dengan sk-fk-	Tim Anda memiliki kredensial yang valid
2. Setel satu base URL	https://router.flatkey.ai/v1	Aplikasi Anda mengarah ke router bersama, bukan endpoint khusus penyedia
3. Jalankan smoke test terkecil	POST /v1/chat/completions dengan model teks sederhana	Auth, header, routing, dan Usage Logs berfungsi
4. Pindah ke rute Seedance	Ganti model placeholder dengan ID model Seedance yang disetujui	Lapisan akses yang sama kini dapat mendukung alur evaluasi video Anda
5. Tambahkan penanganan async	Logika polling atau webhook untuk job video	Produk Anda siap untuk eksekusi text-to-video yang sesungguhnya

Jika Anda hanya mengingat satu hal, ingat ini: permintaan cURL pertama adalah pemeriksaan konektivitas router, bukan payload final text-to-video.

Sebelum memulai

Anda membutuhkan empat hal:

• Akun Flatkey
• Kunci API Flatkey
• Sejumlah kredit prabayar untuk permintaan
• Keputusan produk tentang rute Seedance mana yang sebenarnya ingin Anda evaluasi

Untuk sebagian besar tim text-to-video, katalog model publik membuat pilihan saat ini cukup jelas untuk memulai percakapan:

Sinyal model publik saat ini di Flatkey	Penggunaan terbaik
seedance-2.5	Evaluasi text-to-video, plus image-to-video jika diperlukan
seedance-2.0-i2v	Hanya image-to-video

Jangan hardcode nama model dari tangkapan layar lama atau catatan internal. Periksa direktori model saat ini atau katalog live pada hari publikasi, karena ketersediaan route video dapat berubah lebih cepat daripada panduan setup statis.

Langkah 1: buat dan simpan API key Flatkey

Di Flatkey Console, buat API key dan simpan sebagai variabel lingkungan.

export FLATKEY_API_KEY="sk-fk-..."

Ini adalah titik pertama tempat tim menciptakan friksi yang sebenarnya bisa dihindari. Simpan key di sisi server, bukan di kode browser dan bukan di catatan lokal yang dibagikan. Jika evaluasinya untuk tim produk, bukan satu engineer, gunakan secret milik tim sejak awal.

Langkah 2: jalankan smoke test router sekecil mungkin

Quickstart Flatkey saat ini menggunakan POST /v1/chat/completions untuk permintaan pertama. Itu langkah yang tepat meskipun tujuan akhir Anda adalah generasi video Seedance, karena ini memverifikasi lapisan akses bersama sebelum Anda menambahkan kompleksitas workflow asinkron.

curl https://router.flatkey.ai/v1/chat/completions   -H "Authorization: Bearer $FLATKEY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Balas dengan kata connected."}
    ]
  }'

Respons yang sukses langsung memberi tahu Anda lima hal yang berguna:

• API key valid
• header Authorization: Bearer ... sudah benar
• base URL sudah benar
• client Anda dapat melakukan POST JSON dengan sukses
• permintaan tersebut akan muncul di Flatkey Usage Logs dengan hitungan token dan biaya

Itulah bukti terkecil yang bisa ditinjau bahwa lapisan akses berfungsi.

Langkah 3: pahami apa yang sebenarnya diperiksa oleh request smoke test

Smoke test chat-completions memang sengaja dibuat sederhana. Struktur yang diperlukan adalah:

Field request	Mengapa penting
header Authorization	Memastikan format Bearer token
Content-Type: application/json	Memastikan body request diparse dengan benar
model	Memastikan route dapat me-resolve ID model
messages	Memastikan body cocok dengan skema yang kompatibel dengan OpenAI

Dokumentasi chat-completions Flatkey saat ini juga menyoroti tiga field respons yang biasanya pertama kali diperiksa oleh tim produk:

• choices[0].message.content
• model
• usage

Field terakhir itu sangat berguna untuk onboarding, karena menyediakan tempat bersama bagi tim produk dan ops untuk memverifikasi bahwa request benar-benar melewati router.

Langkah 4: ganti model placeholder untuk evaluasi Seedance

Setelah smoke test lolos, pertahankan kredensial yang sama dan base URL router yang sama, lalu ubah hanya bagian yang spesifik untuk workflow video Anda.

Pertahankan yang ini tanpa perubahan:

• Authorization: Bearer $FLATKEY_API_KEY
• https://router.flatkey.ai/v1
• penanganan secret di sisi server Anda
• jalur peninjauan log dan billing Anda

Ubah yang berikutnya:

Apa yang berubah setelah smoke test	Mengapa berubah
model	Anda mengganti model teks placeholder dengan ID model Seedance yang disetujui
Bentuk request body	Generasi video memerlukan field payload tersendiri, bukan hanya array messages ala chat
Penanganan respons	Workflow video mengembalikan status job, aset, atau status async, bukan hanya teks langsung
Logika produk	Anda perlu polling atau webhook, bukan memperlakukan panggilan ini seperti chat sinkron

Untuk evaluasi produk text-to-video, placeholder aman pada hari peluncuran adalah:

seedance-2.5

Untuk evaluasi image-to-video, rute publik saat ini adalah:

seedance-2.0-i2v

Gunakan nama-nama tersebut sebagai titik awal untuk penelusuran, bukan sebagai janji bahwa setiap workflow downstream memiliki bentuk payload yang identik.

Step 5: design around Seedance's async video workflow

Ini adalah langkah yang paling sering dilewatkan quickstart.

Halaman API publik Seedance masih menjelaskan workflow-nya sebagai:

• pembuatan tugas async
• polling status
• webhook
• kredit berbasis penggunaan

Artinya, tim produksi sebaiknya mengasumsikan jalur video yang sebenarnya memerlukan setidaknya empat state di aplikasinya sendiri:

Status job	Apa yang harus dilakukan aplikasi Anda
queued	Catat job dan tampilkan bahwa permintaan telah diterima
running	Lakukan polling status atau tunggu webhook
succeeded	Ambil output asset dan tambahkan metadata
failed	Simpan error dan tentukan apakah perlu retry

Jika tim Anda mencoba memperlakukan Seedance seperti respons chat sinkron, integrasinya akan terasa tidak stabil meskipun API berperilaku normal.

Urutan onboarding yang praktis untuk tim produk

Jika Anda menginginkan loop evaluasi sekecil mungkin, gunakan urutan ini:

1. Buat key Flatkey.
2. Jalankan smoke test chat/completions.
3. Verifikasi bahwa request muncul di Usage Logs.
4. Pilih ID model Seedance saat ini yang benar-benar ingin Anda uji.
5. Implementasikan alur request async khusus Seedance.
6. Tambahkan satu jalur polling atau satu jalur webhook sebelum Anda memperluas rollout.

Ini mengurangi risiko onboarding karena Anda memisahkan verifikasi router dari implementasi workflow video.

Troubleshooting

401 atau 403 dari request cURL pertama

Biasanya berarti key tidak valid, kedaluwarsa, atau tidak dikirim sebagai Bearer token.

Periksa:

• key diawali dengan sk-fk-
• variabel shell benar-benar sudah diset
• header adalah Authorization: Bearer ...

404 atau route mismatch

Biasanya berarti aplikasi Anda mengarah ke URL yang salah.

Gunakan:

https://router.flatkey.ai/v1

Jangan arahkan request ke situs marketing atau menghilangkan suffix /v1.

Request berhasil tetapi Usage Logs tetap kosong

Quickstart Flatkey secara eksplisit menyatakan untuk menunggu beberapa detik lalu mencari lagi. Jika log tetap tidak muncul, periksa kembali nama model, API key, dan base URL yang benar-benar Anda kirim.

Smoke test berhasil tetapi alur kerja Seedance tidak

Itu biasanya berarti lapisan akses baik-baik saja dan masalahnya sekarang ada di salah satu tempat berikut:

• ID model Seedance yang salah
• bentuk payload video yang salah
• logika polling async yang hilang
• penanganan webhook belum diimplementasikan
• kode produk mengasumsikan respons teks sinkron

Itu kemajuan, bukan kegagalan. Anda sudah mengisolasi masalah dari auth dan routing.

Kapan quickstart ini sudah cukup

Quickstart ini sudah cukup ketika tim Anda perlu menjawab:

• Apakah kita bisa melakukan autentikasi melalui Flatkey?
• Apakah kita bisa memakai ulang jalur klien yang kompatibel dengan OpenAI?
• Apakah produk dan ops bisa melihat request di log?
• Apakah kita bisa beralih dari smoke test teks ke rute Seedance tanpa menambahkan key provider lain terlebih dahulu?

Jika jawaban untuk keempat pertanyaan itu ya, langkah persetujuan berikutnya biasanya berkaitan dengan alur kerja video async dan model biaya, bukan konektivitas dasar.

Jika Anda membutuhkan sisi harga sebelum peluncuran, tinjau halaman harga live Flatkey berikutnya agar tim dapat menyetujui evaluasi dengan permukaan penagihan yang sama yang akan digunakan di produksi.

FAQ

Apa cara tercepat untuk menguji akses API Seedance melalui Flatkey?

Mulailah dengan smoke test POST /v1/chat/completions Flatkey saat ini untuk memverifikasi auth, base URL, dan Usage Logs. Setelah itu berhasil, ganti model placeholder dengan ID model Seedance yang saat ini disetujui dan bangun alur kerja video async.

Apakah request cURL pertama menghasilkan video?

Tidak. Request cURL pertama adalah pemeriksaan konektivitas untuk shared router. Ini membuktikan key, header, base URL, dan log Anda bekerja sebelum Anda menambahkan penanganan request khusus video.

Model Seedance mana yang harus digunakan tim text-to-video untuk memulai?

Pada Jumat, 17 Juli 2026, katalog model publik Flatkey mencantumkan seedance-2.5 untuk text-to-video dan image-to-video. Periksa lagi direktori model saat ini sebelum meng-hardcode-nya ke dalam kode produk.

Model Seedance mana yang harus digunakan tim image-to-video untuk memulai?

Pada Jumat, 17 Juli 2026, katalog publik Flatkey mencantumkan seedance-2.0-i2v untuk image-to-video.

Mengapa alur onboarding dimulai dengan chat completions alih-alih pekerjaan video?

Karena request chat-completions adalah bukti sekecil mungkin bahwa jalur routing OpenAI-compatible Anda berfungsi. Ini memisahkan masalah auth dan logging dari masalah pipeline video.

Apa yang harus saya periksa dalam respons sukses pertama?

Periksa model, choices[0].message.content, dan usage, lalu konfirmasi bahwa request yang sama muncul di Usage Logs.

Apa yang berubah ketika saya beralih dari smoke test ke evaluasi Seedance yang sebenarnya?

Key dan base URL tetap sama. ID model, body request, dan penanganan job async berubah.