Panduan inti
Log dan pemecahan masalah
Simpan ID yang diperlukan untuk melacak permintaan, tugas, dan tagihan
Simpan ID permintaan, tugas, dan penagihan TokenLab di log Anda. ID tersebut menghubungkan tindakan pengguna dengan hasil dan tagihannya tanpa menyimpan prompt atau media pribadi.
Di Console, detail permintaan dan respons yang ditangkap tersedia selama 30 hari sejak penangkapan, dengan akses yang berakhir tepat pada saat kedaluwarsa meskipun pembersihan fisik masih dalam antrean. Identitas permintaan dan riwayat penagihan/penggunaan memiliki masa berlaku yang independen. Lihat Retensi data.
Dari permintaan ke investigasi dan dukungan
-
Buka Runs di workspace yang memiliki permintaan tersebut. Temukan Request ID-nya dan pilih baris tersebut.
-
Pilih Open full details untuk halaman khusus. Back to requests akan memulihkan filter daftar. Tautan tidak akan pernah memberikan akses ke workspace lain; gunakan akun yang diotorisasi untuk workspace tersebut.
-
Untuk status tertunda atau tidak diketahui, segarkan progres terlebih dahulu. Untuk respons yang gagal atau terputus, pilih Investigate the issue jika tersedia. Ini akan memulai investigasi untuk permintaan tersebut di Agent dalam aplikasi; tindakan ini tidak memutar ulang permintaan model asli. Permintaan yang berhasil tidak memerlukan investigasi secara default.
-
Jika Anda masih memerlukan bantuan, pilih tindakan dukungan manusia dari permintaan atau investigasi. Ini akan membuka pratinjau dengan permintaan dan percakapan yang tertaut jika tersedia. Tinjau ringkasannya dan hapus konten pribadi, lalu pilih Submit secara eksplisit. Investigasi atau pratinjau saja tidak akan mengirimkan permintaan dukungan.
-
Setelah pengiriman, simpan konfirmasi dan lanjutkan percakapan yang sama di Support. Gunakan kembali percakapan tersebut untuk balasan dan informasi tambahan alih-alih mengirimkan duplikat.
ID yang perlu disimpan
| Pengidentifikasi | Tempat munculnya | Gunakan untuk |
|---|---|---|
request_id | Isi error, log dashboard, catatan penggunaan | Dukungan tingkat permintaan dan rekonsiliasi |
id / task_id | Respons pembuatan dan status asinkron | Melakukan polling pekerjaan asinkron apa pun dengan GET /v1/tasks/{id} |
poll_url | Respons pembuatan asinkron | URL status; poll /v1/tasks/{id} dengan id |
billing_transaction_id | Respons non-streaming saat diselesaikan, respons status tugas asinkron, catatan penggunaan, X-Billing-Transaction-ID | Rekonsiliasi biaya |
X-Task-ID | Header respons tugas asinkron | Korelasi tugas tingkat header |
| ID pekerjaan/pengguna Anda sendiri | Aplikasi Anda | Menemukan permintaan TokenLab untuk tindakan pengguna |
Catatan yang ditujukan untuk pelanggan harus menggunakan ID TokenLab. Jangan pernah mengekspos URL layanan pribadi, kunci cache, atau metadata diagnostik.
Apa yang harus dicatat
Catatlah informasi yang cukup untuk mendiagnosis permintaan tanpa membocorkan rahasia:
- Endpoint, metode HTTP, model, kode status, stempel waktu, dan latensi.
- Pengidentifikasi publik:
request_id,task_id,poll_url, danbilling_transaction_idjika ada. - Nama field yang dikirim dalam permintaan, bukan prompt lengkap atau konten media pribadi.
- Respons status asinkron akhir dan field error yang aman.
- Jumlah percobaan ulang klien dan apakah percobaan ulang tersebut membuat tugas baru atau melanjutkan tugas yang sudah ada.
Selalu lakukan redaksi pada Authorization, API key, token manajemen, URL yang ditandatangani, URL media pribadi, prompt lengkap, dan data pribadi pengguna kecuali Anda memiliki izin eksplisit untuk menyimpannya.
Matriks Pemecahan Masalah
| Gejala | Pemeriksaan pertama | Halaman yang berguna |
|---|---|---|
401 atau 403 | API key, token manajemen, akses organisasi, cakupan kunci | Autentikasi |
402 | Saldo, batas penggunaan API key | Penagihan & Harga |
429 | Tingkat akun, batas tarif endpoint, perilaku percobaan ulang | Batas Tarif |
400 invalid_request_error | Field tidak didukung, endpoint salah, field wajib diisi tidak ada, atau ketidakcocokan permintaan model | Penanganan Error |
| Tugas asinkron tidak dapat ditemukan | API key salah, ID salah ketik, atau tugas kedaluwarsa | Pekerjaan Asinkron & Polling |
| Biaya tidak sesuai dengan UI | Waktu penyelesaian atau membandingkan pengidentifikasi yang salah | Penagihan & Harga |
Rekonsiliasi Penggunaan
Gunakan Management API untuk rekonsiliasi sisi server:
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
-H "Authorization: Bearer mt-your-management-token"GET /v1/management/api-keys/{keyId}/usage dapat memfilter berdasarkan scene, model, modelVendor, startDate, dan endDate. Gunakan catatan ini alih-alih melakukan scraping halaman Console atau menghitung tagihan hanya dari jumlah token respons. endDate yang hanya berupa tanggal berarti 00:00 UTC pada awal hari tersebut; lihat Dapatkan Penggunaan API Key.
Respons streaming mungkin diselesaikan setelah stream dikirim, sehingga header penagihan bisa saja tidak ada meskipun penggunaan dicatat kemudian. Tugas media asinkron mungkin diselesaikan setelah polling terminal.
Apa yang harus dikirim ke dukungan
Saat menghubungi dukungan, sertakan:
request_id.task_iddanpoll_urluntuk pekerjaan asinkron.billing_transaction_idjika ada.- Endpoint, metode, model, stempel waktu, dan kode status.
- Nama field permintaan dan isi error yang aman.
- Hasil yang Anda harapkan dan apa yang sebenarnya dilihat oleh pengguna.
Jangan sertakan API key, token manajemen, media pribadi, prompt lengkap, URL layanan pribadi, atau pengidentifikasi diagnostik. Jika dukungan memerlukan contoh permintaan, kirimkan salinan yang telah diredaksi.
Pemeriksaan yang layak diotomatisasi
- Berikan peringatan pada respons
401,402,429, dan5xxyang berulang secara terpisah; masing-masing memerlukan respons yang berbeda. - Lacak pekerjaan asinkron yang tetap tidak terminal lebih lama dari SLA produk Anda.
- Lacak upaya pembuatan duplikat untuk ID pekerjaan pengguna yang sama.
- Ambil sampel pekerjaan yang telah selesai dan verifikasi apakah aset yang terlihat oleh pengguna, catatan penggunaan, dan catatan tugas yang disimpan sudah sesuai.
Referensi API
| Topik | Referensi |
|---|---|
| Penanganan Error | Penanganan Error |
| Batas Tarif | Batas Tarif |
| Penagihan & Harga | Penagihan & Harga |
| Dapatkan Penggunaan API Key | Dapatkan Penggunaan API Key |
| Dapatkan Status Tugas | Dapatkan Status Tugas |