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:

FieldArtiApa yang harus dilakukan
idID tugas TokenLabSimpan bersama catatan pekerjaan Anda sendiri
task_idNama lain untuk ID tugas yang samaPerlakukan sebagai setara dengan id
statusStatus tugas saat iniTerus periksa hingga selesai atau gagal
poll_urlURL status untuk tugas tersebutSimpan; lakukan polling /v1/tasks/{id} dengan ID tugas
modelModel yang digunakan untuk tugasSimpan 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 terjadiPerilaku yang lebih aman
Sebelum server Anda menerima respons pembuatanKirim 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 disimpanLanjutkan polling task_id yang disimpan
Selama pollingCoba lagi request status dengan backoff
Setelah status terminalJangan 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_id dari request pembuatan.
  • task_id / id dari tugas.
  • billing_transaction_id jika 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

GejalaPenyebab yang mungkinApa yang harus diperiksa
404 async_task_not_foundID tugas tidak diketahui, milik workspace lain, atau tugas yang selesai sudah melewati jendela statusnyaPeriksa task_id yang disimpan dan workspace API key
403 task_not_ownedKepemilikan tugas tidak dapat dikonfirmasi untuk workspace saat iniKonfirmasi workspace atau organisasi yang terkait dengan API key
503 async_task_owner_unavailableKepemilikan tugas tidak dapat diperiksa saat ini. retryable adalah trueCoba lagi request status dengan backoff
Tugas tidak pernah selesaiKlien terus melakukan polling URL yang salah atau berhenti sebelum status terminalLakukan polling GET /v1/tasks/{id} dengan ID tugas yang disimpan dan periksa status terbaru
URL media akhir hilangTugas belum selesai, atau selesai tanpa file yang dapat digunakanTerus lakukan polling hingga selesai, lalu perlakukan hasil yang hilang sebagai gagal
Pengguna melihat duplikatJalur retry membuat tugas baru setelah timeout atau refreshLakukan deduplikasi berdasarkan ID pekerjaan Anda sendiri dan task_id yang disimpan
Ketidakcocokan penagihanPenagihan akhir belum dicatat, atau ID yang salah sedang dibandingkanBandingkan 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

TopikReferensi
Dapatkan Status TugasMendapatkan Status Tugas
Batalkan TugasMembatalkan Tugas
Pembuatan GambarImage Generation
Pembuatan VideoGenerasi Video
Pembuatan MusikMusic Generation
Pembuatan 3D3D Generation
Penagihan & HargaBilling & 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.

Di halaman ini