Pekerjaan Async & Polling

Banyak endpoint media bersifat asinkron. Permintaan pembuatan memulai pekerjaan dan mengembalikan identitas tugas TokenLab publik; aplikasi Anda melakukan polling hingga tugas tersebut mencapai status terminal. Jangan membangun alur kerja pelanggan di sekitar URL tugas upstream, ID routing, atau perilaku callback penyedia.

Kontrak Tugas Publik

Respon pembuatan dapat mencakup:

Field	Arti	Apa yang harus dilakukan
`id`	ID tugas TokenLab publik	Simpan bersama catatan pekerjaan Anda sendiri
`task_id`	Alias kompatibilitas untuk identitas tugas publik yang sama	Anggap setara dengan `id`
`status`	Status tugas publik saat ini	Mulai polling ketika tidak terminal
`poll_url`	URL status yang disukai	Gunakan ini terlebih dahulu jika ada
`model`	Model yang diminta atau diselesaikan oleh endpoint	Simpan untuk dukungan dan rekonsiliasi penagihan

/v1/tasks/{id} adalah endpoint status tetap kanonik untuk pekerjaan media asinkron publik. Rute status spesifik media mungkin ada untuk kompatibilitas, tetapi integrasi baru harus lebih memilih poll_url atau /v1/tasks/{id}.

Alur yang Direkomendasikan

Validasi permintaan pengguna dan kirim panggilan pembuatan dengan model yang eksplisit.
Simpan id / task_id, poll_url, endpoint, model, ID pengguna, dan ID pekerjaan Anda sendiri sebelum mengembalikan kontrol ke UI.
Lakukan polling setiap 5-10s untuk tugas media yang berjalan lama.
Hentikan hanya ketika tugas sudah completed atau failed.
Pada completed, baca bidang hasil spesifik media dan simpan URL atau metadata akhir.
Pada failed, simpan kesalahan publik dan tawarkan pengulangan hanya sebagai pekerjaan baru yang terlihat oleh pengguna.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

Contoh Polling

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Status publik yang diharapkan adalah pending, processing, completed, dan failed. Tugas yang dibatalkan diwakili sebagai failed dengan cancelled: true dan cancellation_status: "cancelled" sehingga penanganan status yang lebih lama tetap berfungsi.

Aturan Pengulangan Klien

Timeout jaringan adalah sumber paling umum dari pekerjaan duplikat. Gunakan aturan ini:

Di mana timeout terjadi	Perilaku yang lebih aman
Sebelum server Anda menerima respon pembuatan	Periksa log server untuk `request_id`; ulangi hanya jika tidak ada tugas yang dibuat
Setelah respon pembuatan disimpan	Lanjutkan polling `task_id` yang disimpan
Selama polling	Ulangi permintaan status dengan backoff
Setelah status terminal	Jangan polling lagi kecuali pengguna secara eksplisit menyegarkan catatan

Jangan kirim permintaan pembuatan kedua hanya karena browser diperbarui atau polling status gagal.

Penagihan dan Penyelesaian

Pekerjaan asinkron dapat memesan jumlah yang diperkirakan ketika permintaan pembuatan diterima. Penyelesaian akhir terjadi setelah status terminal. Ketika tersedia, respon status tugas dapat mengekspos billing_transaction_id dan header X-Billing-Transaction-ID. Untuk rekonsiliasi, gabungkan pengidentifikasi ini di log Anda:

request_id dari permintaan pembuatan.
task_id / id dari tugas.
billing_transaction_id jika ada.
ID pengguna Anda sendiri, ID proyek, atau ID pekerjaan.

Pembatalan

DELETE /v1/tasks/{id} sengaja sempit. Saat ini mendukung tugas video Volcengine Seedance yang antre seperti seedance-1.5-pro, seedance-2.0, dan seedance-2.0-fast. Tugas yang tidak didukung mengembalikan 400 unsupported_task_cancel. Tugas yang sudah berjalan atau terminal mengembalikan 409 task_not_cancellable. Bangun UI pembatalan sebagai “permintaan pembatalan” daripada tombol berhenti yang dijamin.

Pemecahan Masalah

Gejala	Penyebab yang mungkin	Apa yang harus diperiksa
`async_task_not_found`	Tugas tidak dikenal, kedaluwarsa, tidak dapat diakses dengan kunci API ini, atau bukan tugas asinkron publik	Konfirmasi kepemilikan kunci API dan `task_id` publik yang disimpan
Tugas tidak pernah tampak selesai	Klien terus polling URL yang salah atau berhenti sebelum status terminal	Gunakan `poll_url` atau `/v1/tasks/{id}` dan periksa status terbaru
URL media akhir hilang	Tugas tidak selesai, atau pekerjaan upstream selesai tanpa output yang dapat digunakan	Terus polling hingga terminal, lalu tangani output yang hilang sebagai gagal
Pengguna melihat duplikat	Jalur pengulangan membuat tugas baru setelah timeout atau penyegaran	Hapus duplikat berdasarkan ID pekerjaan Anda sendiri dan `task_id` yang disimpan
Ketidaksesuaian penagihan	Penyelesaian bersifat asinkron atau klien membandingkan ID penyedia	Bandingkan `request_id`, `task_id`, dan `billing_transaction_id`

Paket Dukungan

Saat menghubungi dukungan, sertakan request_id, task_id, billing_transaction_id jika ada, endpoint, model, timestamp, dan bentuk permintaan yang telah disanitasi. Jangan sertakan kunci API, media pribadi, URL yang ditandatangani, atau prompt lengkap kecuali dukungan meminta contoh yang disunting.

Referensi API

Topik	Referensi
Dapatkan Status Tugas	Dapatkan Status Tugas
Batalkan Tugas	Batalkan Tugas
Generasi Gambar	Generasi Gambar
Generasi Video	Generasi Video
Generasi Musik	Generasi Musik
Generasi 3D	Generasi 3D
Penagihan & Harga	Penagihan & Harga

​Kontrak Tugas Publik

​Alur yang Direkomendasikan

​Contoh Polling

​Aturan Pengulangan Klien

​Penagihan dan Penyelesaian

​Pembatalan

​Pemecahan Masalah

​Paket Dukungan

​Referensi API