Comprendre les en-têtes HTTP et les points de terminaison de protocole natif de TokenLab

Les points de terminaison de protocole déterminent les schémas de charge utile

TokenLab n'utilise pas d'en-têtes dynamiques d'indication de format (tels que des balises format-hint propriétaires) pour indiquer les schémas de réponse lors de l'exécution. Les structures de charge utile sont plutôt strictement régies par le point de terminaison appelé. L'analyse des réponses côté client nécessite d'acheminer les requêtes vers le point de terminaison de protocole natif cible plutôt que d'inspecter les en-têtes de réponse pour identifier les types de charge utile :

• Chat Completions (/v1/chat/completions) : utilise des schémas compatibles avec OpenAI retournant choices, message.content et un bloc usage (prompt_tokens, completion_tokens, total_tokens).
• Responses (/v1/responses) : respecte le format de l'API OpenAI Responses pour les tâches en arrière-plan, les outils serveur et les événements de réponse.
• Anthropic Messages (/v1/messages) : interagit avec les modèles Anthropic Claude en utilisant le schéma natif d'Anthropic (blocs content, thinking et output_tokens). Lors de la configuration du SDK Anthropic, définissez l'URL de base sur https://api.tokenlab.sh sans le préfixe /v1.
• Gemini (/v1beta/models/:model:generateContent) : accepte les schémas natifs Gemini (contents, parts) et renvoie des objets candidats REST standard Gemini.

Avant d'acheminer une requête vers un modèle, vérifiez quels protocoles il accepte en appelant Obtenir un modèle (GET /v1/models/{model}) ou en consultant le catalogue des modèles. Inspectez la liste tokenlab.accepted_request_formats dans la réponse. Consultez le guide des formats d'API pour connaître l'ensemble des règles de mappage des points de terminaison.

En-têtes de requête documentés

Tous les appels standards aux points de terminaison TokenLab requièrent des en-têtes de requête HTTP spécifiques :

• Authorization : transmet les identifiants sous forme de jeton porteur (Authorization: Bearer $TOKENLAB_API_KEY). Les points de terminaison de gestion nécessitent un jeton de gestion (Authorization: Bearer mt-...).
• Content-Type : doit être application/json pour les requêtes POST contenant des corps JSON.

En-têtes de réponse documentés

TokenLab renvoie des en-têtes HTTP standard et personnalisés pour les limites de débit, la réconciliation de facturation et la gestion des tâches asynchrones :

En-têtes de limitation de débit

Lorsqu'une requête dépasse les limites du niveau du compte, TokenLab renvoie un statut HTTP 429 rate_limit_exceeded accompagné de deux en-têtes :

• Retry-After : spécifie le délai d'attente requis en secondes avant de retenter l'appel.
• X-RateLimit-Limit : indique votre limite active de requêtes par minute pour le niveau authentifié.

Utilisez toujours la valeur de l'en-tête Retry-After pour gérer les nouvelles tentatives plutôt que de coder en dur des limites de temporisation. Plus de détails sur la gestion de la reprise figurent dans le guide sur les limites de débit.

En-têtes de facturation et d'observabilité

Pour les interactions asynchrones et sans streaming, TokenLab fournit des en-têtes d'identification afin de suivre les frais et le travail en arrière-plan :

• X-Billing-Transaction-ID : renvoyé lorsque la facturation est réglée avant l'envoi de la réponse HTTP. Les points de terminaison non-streaming compatibles avec OpenAI incluent billing_transaction_id dans le corps JSON, mais Gemini et les points de terminaison au format natif l'exposent via cet en-tête. Les appels en streaming peuvent être réglés après la fermeture de la connexion ; en son absence, récupérez l'identifiant dans les enregistrements d'utilisation de l'espace de travail. Examinez les flux de règlement dans le guide Facturation et tarification.
• X-Task-ID : renvoyé dans les en-têtes de réponse lors de la création de tâches asynchrones pour la génération de vidéo, de musique, de 3D ou d'images basées sur des tâches. Il fournit un identifiant de corrélation au niveau de l'en-tête correspondant à l'id de la tâche. Consultez le guide Journaux et dépannage pour connaître les normes de journalisation.

Implémentation : capture des en-têtes et nouvelle tentative lors d'une 429

L'exemple Python suivant illustre comment envoyer une requête au point de terminaison Chat Completions, inspecter les identifiants de transaction et gérer les en-têtes Retry-After en cas de limitation de débit :

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()

Pratiques de journalisation et d'observabilité

Lors de l'instrumentation de la surveillance des requêtes, journalisez les identifiants de suivi publics renvoyés dans les en-têtes et les charges utiles pour réconcilier les enregistrements sans conserver les invites des utilisateurs ni les identifiants :

• Conservez request_id, X-Billing-Transaction-ID et X-Task-ID aux côtés des codes d'état et des latences de réponse.
• Masquez toujours les en-têtes Authorization, les clés d'API brutes et les URL signées privées de vos pipelines de télémétrie.
• Pour la réconciliation financière côté serveur, interrogez GET /v1/management/api-keys/{keyId}/usage plutôt que d'extraire les données des pages du tableau de bord ou d'estimer les totaux uniquement à partir des compteurs de jetons bruts.