> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Pekerjaan Async & Polling

> Buat pekerjaan media asinkron, polling status tugas TokenLab publik, dan rekonsiliasi hasil akhir tanpa ID spesifik penyedia.

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

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

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## Contoh Polling

```bash theme={null}
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](/id/api-reference/tasks/get-task-status) |
| Batalkan Tugas        | [Batalkan Tugas](/id/api-reference/tasks/cancel-task)            |
| Generasi Gambar       | [Generasi Gambar](/id/guides/image-generation)                   |
| Generasi Video        | [Generasi Video](/id/guides/video-generation)                    |
| Generasi Musik        | [Generasi Musik](/id/guides/music-generation)                    |
| Generasi 3D           | [Generasi 3D](/id/guides/3d-generation)                          |
| Penagihan & Harga     | [Penagihan & Harga](/id/guides/billing)                          |