Comprender los encabezados HTTP y los endpoints de protocolo nativo de TokenLab

Los endpoints de protocolo determinan los esquemas de carga útil

TokenLab no utiliza encabezados dinámicos de sugerencia de formato (como etiquetas de sugerencia de formato propietarias) para indicar los esquemas de respuesta en tiempo de ejecución. En su lugar, las estructuras de la carga útil están regidas estrictamente por el endpoint al que se llama. El análisis de las respuestas de los clientes requiere enrutar las solicitudes al endpoint de protocolo nativo de destino en lugar de inspeccionar los encabezados de respuesta en busca de tipos de carga útil:

• Chat Completions (/v1/chat/completions): Utiliza esquemas compatibles con OpenAI que devuelven choices, message.content y un bloque usage (prompt_tokens, completion_tokens, total_tokens).
• Responses (/v1/responses): Se adhiere al formato de OpenAI Responses API para tareas en segundo plano, herramientas de servidor y eventos de respuesta.
• Anthropic Messages (/v1/messages): Interactúa con los modelos Claude de Anthropic mediante el esquema nativo de Anthropic (bloques content, thinking y output_tokens). Al configurar el SDK de Anthropic, establezca la URL base en https://api.tokenlab.sh sin el prefijo /v1.
• Gemini (/v1beta/models/:model:generateContent): Acepta esquemas nativos de Gemini (contents, parts) y devuelve objetos candidatos REST estándar de Gemini.

Antes de enrutar una solicitud de modelo, verifique qué protocolos acepta llamando a Obtener un modelo (GET /v1/models/{model}) o revisando el catálogo de modelos. Inspeccione la lista tokenlab.accepted_request_formats en la respuesta. Consulte la guía de formatos de API para conocer las reglas exhaustivas de mapeo de endpoints.

Encabezados de solicitud documentados

Todas las llamadas estándar a los endpoints de TokenLab requieren encabezados de solicitud HTTP específicos:

• Authorization: Pasa las credenciales como un token bearer (Authorization: Bearer $TOKENLAB_API_KEY). Los endpoints de gestión requieren un token de gestión (Authorization: Bearer mt-...).
• Content-Type: Debe ser application/json para solicitudes POST que contengan cuerpos JSON.

Encabezados de respuesta documentados

TokenLab devuelve encabezados HTTP estándar y personalizados para límites de frecuencia, conciliación de facturación y gestión de tareas asíncronas:

Encabezados de límite de frecuencia

Cuando una solicitud supera los límites del nivel de cuenta, TokenLab devuelve un estado HTTP 429 rate_limit_exceeded acompañado de dos encabezados:

• Retry-After: Especifica el período de espera requerido en segundos antes de reintentar la llamada.
• X-RateLimit-Limit: Informa su límite activo de solicitudes por minuto para el nivel autenticado.

Utilice siempre el valor del encabezado Retry-After para gestionar los reintentos en lugar de definir tiempos de espera fijos en el código. Encontrará más detalles sobre la gestión de recuperación en la guía de límites de frecuencia.

Encabezados de facturación y observabilidad

Para interacciones asíncronas y sin streaming, TokenLab proporciona encabezados de identificación para rastrear cobros y trabajo en segundo plano:

• X-Billing-Transaction-ID: Se devuelve cuando la facturación se liquida antes de que se despache la respuesta HTTP. Los endpoints compatibles con OpenAI sin streaming incluyen billing_transaction_id en el cuerpo JSON, pero Gemini y los endpoints de formato nativo lo exponen a través de este encabezado. Las llamadas con streaming pueden liquidarse después de que se cierre la conexión; cuando esté ausente, recupere el ID de los registros de uso del espacio de trabajo. Revise los flujos de trabajo de liquidación en la guía de facturación y precios.
• X-Task-ID: Se devuelve en los encabezados de respuesta al crear tareas asíncronas para la generación de video, música, 3D o imágenes basadas en tareas. Proporciona un ID de correlación a nivel de encabezado correspondiente al id de la tarea. Consulte la guía de registros y resolución de problemas para conocer los estándares de registro.

Implementación: Captura de encabezados y reintentos ante un error 429

El siguiente ejemplo en Python ilustra cómo enviar una solicitud al endpoint Chat Completions, inspeccionar identificadores de transacción y manejar los encabezados Retry-After durante límites de frecuencia:

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

Prácticas de registro y observabilidad

Al instrumentar la monitorización de solicitudes, registre los identificadores de seguimiento públicos devueltos en los encabezados y cargas útiles para conciliar los registros sin almacenar las instrucciones (prompts) ni las credenciales de los usuarios:

• Conserve request_id, X-Billing-Transaction-ID y X-Task-ID junto con los códigos de estado y las latencias de respuesta.
• Oculte siempre los encabezados Authorization, las claves de API sin procesar y las URL privadas firmadas de las canalizaciones de telemetría.
• Para la conciliación financiera en el lado del servidor, consulte GET /v1/management/api-keys/{keyId}/usage en lugar de extraer datos mediante scraping de las páginas del panel o estimar totales únicamente a partir de contadores de tokens sin procesar.