TokenLab Management API Çalışma Alanı Bakiye Sorgulamasını Ekliyor

Otomatik bir üretim hattının boş bir bakiye nedeniyle durmasına izin vermek önlenebilir bir durumdur. TokenLab Management API bakiye sorgulaması, bir çıkarım (inference) anahtarı yerine bir yönetim token'ı kullanarak otomatik iş akışlarına sorgulanabilir bir bakiye toplamı sağlar.

Bu kılavuz, GET /v1/management/balance endpoint sözleşmesini, kimlik doğrulama gereksinimlerini, para birimi yönetimini ve yanıt şemalarının doğrudan resmi belgelere göre nasıl doğrulanacağını kapsar.

Önemli Çıkarımlar

• Management API bakiye endpoint'i (GET /v1/management/balance), mevcut çalışma alanı bakiyesini, toplam yüklemeleri ve kümülatif kullanım harcamasını döndürür.
• Kimlik doğrulama, operasyonel kontrolleri model çıkarım anahtarlarından (sk-...) ayrı tutarak Dashboard → API → Management Tokens bölümünde oluşturulan bir yönetim token'ı (mt-...) gerektirir.
• Tüm parasal değerler USD cinsinden döndürülür. Kesin hesaplamalar için döndürülen ondalık dizgeler (balance_decimal, total_recharge_decimal, total_used_decimal) kullanılmalıdır.
• Endpoint, /v1/management/api-keys/{keyId}/usage ve /v1/management/api-keys/{keyId}/billing gibi anahtar düzeyinde raporlama ile eşleşir.

Yönetim Token'ları ile Model Çıkarım API Anahtarlarının Karşılaştırması

Yönetim token'ları ve model çıkarım anahtarları, TokenLab'de farklı operasyonel rolleri yerine getirir:

• Model çıkarım API anahtarları (sk-...): POST /v1/chat/completions, POST /v1/responses, POST /v1/messages üzerindeki yerel Anthropic Messages ve /v1beta/models/... üzerindeki Gemini gibi çıkarım endpoint'lerini çağırmak için kullanılır. Bu anahtarlar üretim isteklerini yürütür ancak kuruluş düzeyindeki finansal verileri açığa çıkarmaz.
• Yönetim token'ları (mt-...): /v1/management/* rotalarıyla sınırlandırılmıştır. Model üretim erişimi vermeden arka uçların çalışma alanı bakiyelerini incelemesine, API anahtarlarını listelemesine veya düzenlemesine ve kullanımı izlemesine olanak tanır.

Bu kimlik bilgilerinin ayrılması, muhasebe script'lerinin ve finans izleyicilerinin faturalandırılabilir çıkarım çağrılarını tetikleyememesini sağlarken, model çalışanlarının hesap yönetimine hiçbir zaman erişim kazanamamasını güvence altına alır.

Bakiye Endpoint'i İletişim Sözleşmesi

Authorization başlığında yönetim token'ınızla kimlik doğrulaması yaparak https://api.tokenlab.sh/v1/management/balance adresine bir GET isteği gönderin:

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

Yanıt Şeması

Başarılı bir istek, bir organization_balance nesnesi ile birlikte 200 OK döndürür:

{
  "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"
}

Yanıt Alanları

• object (string): Her zaman organization_balance.
• organization_id (string): Geçerli yönetim token'ı ile ilişkili kuruluş.
• balance (number): Gösterim amaçlı kayan noktalı sayı olarak USD cinsinden mevcut çalışma alanı bakiyesi.
• balance_decimal (string): Finansal mutabakat için ondalık dizge olarak biçimlendirilmiş, USD cinsinden kesin mevcut çalışma alanı bakiyesi.
• total_recharge (number): USD cinsinden toplam başarılı çalışma alanı yükleme tutarı.
• total_recharge_decimal (string): Ondalık dizge olarak biçimlendirilmiş, USD cinsinden kesin toplam başarılı çalışma alanı yükleme tutarı.
• total_used (number): USD cinsinden toplam çalışma alanı kullanım harcaması.
• total_used_decimal (string): Ondalık dizge olarak biçimlendirilmiş, USD cinsinden kesin toplam çalışma alanı kullanım harcaması.

Parasal alanlar kesinlikle USD cinsindendir. Eşik kontrolleri veya defter mutabakatı için bakiyeyi programatik olarak ayrıştırırken, hassasiyet kaybını önlemek amacıyla kayan noktalı temel veri tipleri yerine rastgele duyarlıklı bir ondalık kitaplığı ile balance_decimal değerini ayrıştırın.

Bakiye Kontrollerini Uygulama

Yaygın entegrasyon modelleri şunları içerir:

1. Toplu İşlem Öncesi Güvenlik Önlemleri (Pre-Batch Guardrails): gpt-5.5 veya glm-5.2 gibi modellerde yüksek hacimli üretim gibi büyük iş yüklerini göndermeden önce /v1/management/balance endpoint'ini sorgulayın. balance_decimal tahmini toplu iş maliyetinin altına düşerse iş kuyruğunu duraklatın.
2. Düşük Bakiye Uyarıları: Otomatik e-posta bildirimleri Console → Settings altından yapılandırılabilirken, zamanlanmış bir izleme cron'u endpoint'i düzenli aralıklarla sorgulayabilir ve dahili Slack, PagerDuty veya webhook bildirimlerini tetikleyebilir.
3. Fatura Mutabakatı: Belirlenen fatura kalemlerine karşı token harcamalarını mutabakat altına almak için canlı çalışma alanı bakiyesini bağımsız anahtar kullanım kayıtları (/v1/management/api-keys/{keyId}/usage) ile birleştirin.

Eksiksiz endpoint özellikleri ve anahtar yönetimi yöntemleri için Get Workspace Balance API Reference ve Management API Overview belgelerini inceleyin.