Panduan inti
Async jobs and polling
Membuat tugas media dan menunggu hasil akhirnya
Banyak endpoint media mengembalikan tugas alih-alih file yang sudah jadi. Simpan ID tugas yang dikembalikan dan lakukan polling pada GET /v1/tasks/{id} hingga statusnya menjadi completed atau failed. Satu endpoint ini melayani tugas gambar, video, musik, 3D, Worlds, dan transkripsi audio asinkron.
Snapshot tugas terminal asinkron memiliki siklus hidup yang terpisah dari jendela pengambilan request/response 30 hari. URL file gambar, video, audio, 3D, dan Worlds yang dihasilkan adalah URL media-result TokenLab yang tetap valid selama 30 hari. Pembacaan status tugas yang sudah selesai berfungsi selama sekitar 7 hari, jadi simpan hasilnya segera setelah tugas selesai. Field media_retention pada respons melaporkan status penyimpanan dan expires_at setiap item; field ini bisa saja tidak ada jika status penyimpanan tidak diketahui tepat waktu, dan URL tersebut tetap berfungsi. Tugas yang gagal dan sedang berlangsung mengembalikan field URL media yang kosong. Lihat Retensi data.
Field untuk disimpan
Respons pembuatan (create) dapat mencakup:
| Field | Arti | Apa yang harus dilakukan |
|---|---|---|
id | ID tugas TokenLab | Simpan bersama catatan pekerjaan Anda sendiri |
task_id | Nama lain untuk ID tugas yang sama | Perlakukan sebagai setara dengan id |
status | Status tugas saat ini | Terus periksa hingga selesai atau gagal |
poll_url | URL status untuk tugas tersebut | Simpan; lakukan polling /v1/tasks/{id} dengan ID tugas |
model | Model yang digunakan untuk tugas | Simpan bersama catatan tugas |
Satu endpoint status
Lakukan polling GET /v1/tasks/{id} dengan id atau task_id dari respons pembuatan. Ini berfungsi untuk setiap jenis tugas. Untuk sebagian besar tugas, poll_url adalah path yang sama ini. Respons pembuatan Worlds mengembalikan poll_url di bawah /v1/worlds/generations/{id}; lakukan polling /v1/tasks/{id} dengan id tugas untuk Worlds juga.
Path status per-modalitas, seperti /v1/videos/generations/{id}, tetap didukung untuk integrasi yang sudah ada. Integrasi baru harus menggunakan /v1/tasks/{id}.
Simpan tugas dan periksa statusnya
Simpan id atau task_id segera setelah request pembuatan berhasil. Simpan poll_url, model, endpoint, dan ID pengguna atau pekerjaan Anda sendiri bersamanya. Untuk pekerjaan media yang panjang, memeriksa setiap 5–10 detik biasanya sudah cukup.
Berhenti saat status menjadi completed atau failed. Tugas yang selesai berisi hasil media; tugas yang gagal berisi error yang dapat Anda tampilkan atau catat. Mencoba kembali (retry) pembuatan yang gagal akan membuat tugas baru dan mungkin menimbulkan biaya baru.
{
"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 yang tersedia adalah pending, processing, completed, dan failed. Tugas yang dibatalkan menggunakan failed bersama dengan cancelled: true dan cancellation_status: "cancelled".
Pembacaan status yang berhasil mengembalikan HTTP 200 bahkan ketika tugas telah gagal. Gunakan status tugas untuk menentukan apakah pembuatan berhasil. Field error mempertahankan bentuk string atau objeknya. Tugas yang gagal juga dapat menyertakan error_details dengan status (status error bisnis), type, code, message, param, dan retryable. Misalnya, error_details.status: 400 dengan param: "size" berarti request perlu dikoreksi; ini tidak berarti request status itu sendiri gagal. param dihilangkan jika tidak ada field spesifik yang diketahui. Ketika error_details.projection_version adalah 2, message adalah alasan akhir kegagalan, biasanya penjelasan dari layanan upstream itu sendiri, seperti batas parameter atau keputusan kebijakan konten. Untuk tugas yang dijalankan pada rute Official, error_details.upstream juga membawa error upstream sebagaimana dilaporkan: message, ditambah code, param, dan source (nama layanan upstream) jika diketahui. Terus lakukan percabangan pada code dan type; nilai upstream.code ditentukan oleh layanan upstream dan dapat berubah.
Error yang menolak request pembuatan sebelum tugas diterima menggunakan status error HTTP normal dan objek error terstruktur. Mengulangi request pembuatan idempoten yang sama akan mempertahankan penolakan tersebut. Pembacaan status yang gagal tidak mengubah status terminal tugas.
Hindari tugas duplikat
Sebagian besar pembuatan duplikat berasal dari mencoba kembali (retry) request pembuatan setelah timeout.
| Di mana timeout terjadi | Perilaku yang lebih aman |
|---|---|
| Sebelum server Anda menerima respons pembuatan | Kirim request yang sama lagi dengan Idempotency-Key yang sama untuk mendapatkan tugas asli. Tanpa kunci, periksa request_id dan coba lagi hanya jika tidak ada tugas yang dibuat |
| Setelah respons pembuatan disimpan | Lanjutkan polling task_id yang disimpan |
| Selama polling | Coba lagi request status dengan backoff |
| Setelah status terminal | Jangan melakukan polling lagi kecuali pengguna secara eksplisit menyegarkan catatan |
Jangan mengirim request pembuatan kedua hanya karena browser disegarkan atau polling status gagal.
Catatan penagihan
Tugas asinkron dapat mencadangkan perkiraan biayanya saat diterima. Jumlah akhir dicatat setelah tugas selesai atau gagal. Respons status dapat menyertakan billing_transaction_id dan header X-Billing-Transaction-ID.
Simpan pengenal ini bersama-sama:
request_iddari request pembuatan.task_id/iddari tugas.billing_transaction_idjika ada.- ID pengguna, ID proyek, atau ID pekerjaan Anda sendiri.
Pembatalan
DELETE /v1/tasks/{id} dapat membatalkan tugas video Seedance yang didukung saat masih dalam antrean, termasuk seedance-2.0 dan seedance-2.0-fast.
Tugas yang tidak didukung akan mengembalikan 400 unsupported_task_cancel. Tugas yang sudah berjalan atau selesai akan mengembalikan 409 task_not_cancellable. Pembatalan adalah sebuah request, bukan jaminan bahwa pekerjaan yang sudah berlangsung akan berhenti. Pembatalan yang berhasil mengembalikan 200 dengan status: "failed", cancelled: true, dan cancellation_status: "cancelled". Tugas yang dibatalkan tidak dikenakan biaya.
Pemecahan masalah
| Gejala | Penyebab yang mungkin | Apa yang harus diperiksa |
|---|---|---|
404 async_task_not_found | ID tugas tidak diketahui, milik workspace lain, atau tugas yang selesai sudah melewati jendela statusnya | Periksa task_id yang disimpan dan workspace API key |
403 task_not_owned | Kepemilikan tugas tidak dapat dikonfirmasi untuk workspace saat ini | Konfirmasi workspace atau organisasi yang terkait dengan API key |
503 async_task_owner_unavailable | Kepemilikan tugas tidak dapat diperiksa saat ini. retryable adalah true | Coba lagi request status dengan backoff |
| Tugas tidak pernah selesai | Klien terus melakukan polling URL yang salah atau berhenti sebelum status terminal | Lakukan polling GET /v1/tasks/{id} dengan ID tugas yang disimpan dan periksa status terbaru |
| URL media akhir hilang | Tugas belum selesai, atau selesai tanpa file yang dapat digunakan | Terus lakukan polling hingga selesai, lalu perlakukan hasil yang hilang sebagai gagal |
| Pengguna melihat duplikat | Jalur retry membuat tugas baru setelah timeout atau refresh | Lakukan deduplikasi berdasarkan ID pekerjaan Anda sendiri dan task_id yang disimpan |
| Ketidakcocokan penagihan | Penagihan akhir belum dicatat, atau ID yang salah sedang dibandingkan | Bandingkan request_id, task_id, dan billing_transaction_id |
Apa yang harus dikirim ke dukungan
Sertakan request_id, task_id, billing_transaction_id jika ada, endpoint, model, waktu, dan nama field yang Anda kirim. Jangan pernah mengirim API key, media pribadi, URL yang ditandatangani, atau prompt lengkap kecuali dukungan secara khusus meminta contoh yang telah disunting.
Referensi API
| Topik | Referensi |
|---|---|
| Dapatkan Status Tugas | Mendapatkan Status Tugas |
| Batalkan Tugas | Membatalkan Tugas |
| Pembuatan Gambar | Image Generation |
| Pembuatan Video | Generasi Video |
| Pembuatan Musik | Music Generation |
| Pembuatan 3D | 3D Generation |
| Penagihan & Harga | Billing & Pricing |
Berhenti melakukan polling pada tugas terminal, dan berhenti pada 401, 403, 404, atau error yang tidak dapat dicoba kembali. Untuk menerima hasil tugas tanpa polling, konfigurasikan API manajemen Webhook dengan Management Token mt-….
Respons tugas juga membawa header X-Task-ID, X-Task-Type, dan X-Billing-Transaction-ID, yang dapat Anda catat di samping ID tugas.