API Manajemen TokenLab Menambahkan Pemeriksaan Saldo Workspace

Membiarkan pipeline produksi otomatis terhenti karena saldo kosong adalah hal yang dapat dicegah. Pemeriksaan saldo API Manajemen TokenLab menyediakan total saldo yang dapat dikueri untuk alur kerja otomatis menggunakan token manajemen, alih-alih kunci inferensi.

Panduan ini membahas kontrak endpoint GET /v1/management/balance, persyaratan autentikasi, penanganan mata uang, serta cara memverifikasi skema respons secara langsung terhadap dokumentasi resmi.

Poin-Poin Penting

• Endpoint saldo API Manajemen (GET /v1/management/balance) mengembalikan saldo workspace saat ini, total isi ulang (top-up), dan pengeluaran penggunaan kumulatif.
• Autentikasi memerlukan token manajemen (mt-...) yang dibuat di Dashboard → API → Management Tokens, sehingga menjaga pemeriksaan operasional tetap terpisah dari kunci inferensi model (sk-...).
• Semua nilai moneter dikembalikan dalam USD. Perhitungan eksak harus menggunakan string desimal yang dikembalikan (balance_decimal, total_recharge_decimal, total_used_decimal).
• Endpoint ini berpasangan dengan pelaporan tingkat kunci seperti /v1/management/api-keys/{keyId}/usage dan /v1/management/api-keys/{keyId}/billing.

Token Manajemen vs. Kunci API Inferensi Model

Token manajemen dan kunci inferensi model memenuhi peran operasional yang berbeda di TokenLab:

• Kunci API inferensi model (sk-...): Digunakan untuk memanggil endpoint inferensi seperti POST /v1/chat/completions, POST /v1/responses, Anthropic Messages bawaan pada POST /v1/messages, dan Gemini pada /v1beta/models/.... Kunci ini mengeksekusi permintaan pembuatan (generasi), tetapi tidak mengekspos data keuangan tingkat organisasi.
• Token manajemen (mt-...): Dibatasi untuk rute /v1/management/*. Token ini memungkinkan backend untuk memeriksa saldo workspace, menampilkan daftar atau mengedit kunci API, serta memantau penggunaan tanpa memberikan akses pembuatan model.

Memisahkan kredensial ini memastikan skrip pembukuan dan pemantau keuangan tidak dapat memicu panggilan inferensi berbayar, sementara worker model tidak pernah mendapatkan akses ke administrasi akun.

Kontrak Wire Endpoint Saldo

Kirim permintaan GET ke https://api.tokenlab.sh/v1/management/balance dengan melakukan autentikasi menggunakan token manajemen Anda di header Authorization:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Skema Respons

Permintaan yang berhasil akan mengembalikan 200 OK dengan objek organization_balance:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

Bidang Respons

• object (string): Selalu bernilai organization_balance.
• organization_id (string): Organisasi yang terkait dengan token manajemen saat ini.
• balance (number): Saldo workspace saat ini dalam USD sebagai angka floating-point untuk tampilan.
• balance_decimal (string): Saldo workspace saat ini yang eksak dalam USD yang diformat sebagai string desimal untuk rekonsiliasi keuangan.
• total_recharge (number): Total jumlah pengisian ulang (recharge) workspace yang berhasil dalam USD.
• total_recharge_decimal (string): Total jumlah pengisian ulang workspace yang berhasil dan eksak dalam USD yang diformat sebagai string desimal.
• total_used (number): Total pengeluaran penggunaan workspace dalam USD.
• total_used_decimal (string): Total pengeluaran penggunaan workspace yang eksak dalam USD yang diformat sebagai string desimal.

Bidang moneter ditetapkan secara ketat dalam USD. Saat mengurai (parsing) saldo secara terprogram untuk pemeriksaan ambang batas atau rekonsiliasi buku besar, uraikan balance_decimal menggunakan pustaka desimal presisi arbitrer (arbitrary-precision) alih-alih tipe primitif floating-point untuk mencegah hilangnya presisi.

Mengimplementasikan Pemeriksaan Saldo

Pola integrasi yang umum meliputi:

1. Perlindungan Pra-Batch (Pre-Batch Guardrails): Sebelum mengirimkan beban kerja besar—seperti pembuatan bervolume tinggi pada model seperti gpt-5.5 atau glm-5.2—kueri /v1/management/balance. Jika balance_decimal berada di bawah perkiraan biaya batch, jeda antrean tugas (job queue).
2. Peringatan Saldo Rendah: Meskipun notifikasi email otomatis dapat dikonfigurasi di bawah Console → Settings, cron pemantauan terjadwal dapat melakukan polling pada endpoint dan memicu notifikasi internal ke Slack, PagerDuty, atau webhook.
3. Rekonsiliasi Penagihan: Gabungkan saldo workspace langsung dengan catatan penggunaan kunci individual (/v1/management/api-keys/{keyId}/usage) untuk merekonsiliasi pengeluaran token terhadap baris faktur yang telah diselesaikan.

Untuk spesifikasi endpoint lengkap dan metode manajemen kunci, tinjau Referensi API Dapatkan Saldo Workspace dan Ikhtisar API Manajemen.