TokenLab HTTP Başlıklarını ve Yerel Protokol Uç Noktalarını Anlama

Protokol Uç Noktaları Yük Şemalarını Belirler

TokenLab, çalışma zamanında yanıt şemalarını belirtmek için dinamik biçim ipucu başlıkları (örneğin tescilli format-hint etiketleri) kullanmaz. Bunun yerine, yük yapıları kesin olarak çağrılan uç nokta tarafından yönetilir. İstemci yanıtlarını ayrıştırmak, yük türleri için yanıt başlıklarını incelemek yerine istekleri hedef yerel protokol uç noktasına yönlendirmeyi gerektirir:

• Chat Completions (/v1/chat/completions): choices, message.content ve bir usage bloğu (prompt_tokens, completion_tokens, total_tokens) döndüren OpenAI uyumlu şemaları kullanır.
• Responses (/v1/responses): Arka plan görevleri, sunucu araçları ve yanıt olayları için OpenAI Responses API biçimine bağlıdır.
• Anthropic Messages (/v1/messages): Yerel Anthropic şemasını (content blokları, thinking ve output_tokens) kullanarak Anthropic Claude modelleriyle etkileşime girer. Anthropic SDK'yı yapılandırırken, temel URL'yi /v1 öneki olmadan https://api.tokenlab.sh olarak ayarlayın.
• Gemini (/v1beta/models/:model:generateContent): Yerel Gemini şemalarını (contents, parts) kabul eder ve standart Gemini REST aday nesnelerini döndürür.

Bir model isteğini yönlendirmeden önce, Bir Modeli Alın (GET /v1/models/{model}) çağrısı yaparak veya Modeller kataloğunu inceleyerek hangi protokolleri kabul ettiğini doğrulayın. Yanıttaki tokenlab.accepted_request_formats listesini kontrol edin. Kapsamlı uç nokta eşleme kuralları için API Biçimleri kılavuzuna başvurun.

Belgelenmiş İstek Başlıkları

TokenLab uç noktalarına yapılan tüm standart çağrılar belirli HTTP istek başlıklarını gerektirir:

• Authorization: Kimlik bilgilerini bir taşıyıcı belirteç (bearer token) olarak iletir (Authorization: Bearer $TOKENLAB_API_KEY). Yönetim uç noktaları bir yönetim belirteci gerektirir (Authorization: Bearer mt-...).
• Content-Type: JSON gövdeleri içeren POST istekleri için application/json olmalıdır.

Belgelenmiş Yanıt Başlıkları

TokenLab hız sınırları, faturalandırma mutabakatı ve eşzamansız görev yönetimi için standart ve özel HTTP başlıkları döndürür:

Hız Sınırlandırma Başlıkları

Bir istek hesap katmanı sınırlarını aştığında, TokenLab iki başlık eşliğinde bir HTTP 429 rate_limit_exceeded durumu döndürür:

• Retry-After: Çağrıyı yeniden denemeden önce saniye cinsinden gereken bekleme süresini belirtir.
• X-RateLimit-Limit: Kimliği doğrulanmış katman için geçerli olan dakika başına istek sınırınızı bildirir.

Yeniden denemeleri yönetmek için geri çekilme (backoff) sınırlarını sabit kodlamak yerine her zaman Retry-After başlık değerini kullanın. Kurtarma yönetimiyle ilgili daha fazla ayrıntı Hız Sınırları kılavuzunda yer almaktadır.

Faturalandırma ve Gözlemlenebilirlik Başlıkları

Akışsız (non-streaming) ve eşzamansız etkileşimler için TokenLab, ücretleri ve arka plan işlemlerini izlemek üzere tanımlama başlıkları sağlar:

• X-Billing-Transaction-ID: Faturalandırma HTTP yanıtı gönderilmeden önce kesinleştiğinde döndürülür. Akışsız OpenAI uyumlu uç noktalar JSON gövdesine billing_transaction_id dahil eder, ancak Gemini ve yerel biçim uç noktaları bunu bu başlık aracılığıyla sunar. Akış çağrıları bağlantı kapandıktan sonra kesinleşebilir; bulunmadığında, kimliği çalışma alanı kullanım kayıtlarından alın. Kesinleşme iş akışlarını Faturalandırma ve Fiyatlandırma kılavuzunda inceleyin.
• X-Task-ID: Video, müzik, 3D veya görev tabanlı görüntü oluşturma için eşzamansız işler oluşturulurken yanıt başlıklarında döndürülür. Görev id değerine karşılık gelen başlık düzeyinde bir bağıntı kimliği sağlar. Günlük kaydı standartları için Günlükler ve Sorun Giderme kılavuzuna başvurun.

Uygulama: Başlıkları Yakalama ve 429 Durumunda Yeniden Deneme

Aşağıdaki Python örneği, Chat Completions uç noktasına nasıl istek gönderileceğini, işlem tanımlayıcılarının nasıl inceleneceğini ve hız sınırları sırasında Retry-After başlıklarının nasıl ele alınacağını gösterir:

import os
import time
import requests

API_KEY = os.environ["TOKENLAB_API_KEY"]
ENDPOINT = "https://api.tokenlab.sh/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Summarize system status."}]
}

max_attempts = 3
for attempt in range(max_attempts):
    response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)

    if response.status_code == 200:
        # Check for billing transaction header on settled non-streaming calls
        billing_id = response.headers.get("X-Billing-Transaction-ID")
        data = response.json()
        print(f"Settled Transaction ID: {billing_id}")
        print(data["choices"][0]["message"]["content"])
        break

    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After")
        limit = response.headers.get("X-RateLimit-Limit")
        wait_seconds = float(retry_after) if retry_after else 2 ** attempt
        print(f"Rate limit reached ({limit} req/min). Retrying in {wait_seconds}s...")
        time.sleep(wait_seconds)
    else:
        response.raise_for_status()

Günlük Kaydı ve Gözlemlenebilirlik Uygulamaları

İstek izlemeyi yapılandırırken, kullanıcı istemlerini veya kimlik bilgilerini saklamadan kayıtları uzlaştırmak için başlıklarda ve yüklerde döndürülen genel izleme tanımlayıcılarını günlüğe kaydedin:

• Durum kodları ve yanıt gecikmelerinin yanı sıra request_id, X-Billing-Transaction-ID ve X-Task-ID değerlerini saklayın.
• Authorization başlıklarını, ham API anahtarlarını ve özel imzalı URL'leri telemetri veri hatlarından her zaman gizleyin (redact edin).
• Sunucu tarafı finansal mutabakat için, gösterge paneli sayfalarını kazımak veya toplamları yalnızca ham belirteç sayaçlarından tahmin etmek yerine GET /v1/management/api-keys/{keyId}/usage sorgusu yapın.