Entendendo os Cabeçalhos HTTP e os Endpoints de Protocolos Nativos do TokenLab

Endpoints de Protocolo Determinam Esquemas de Payload

O TokenLab não utiliza cabeçalhos dinâmicos de dicas de formato (como tags proprietárias de format-hint) para indicar esquemas de resposta em tempo de execução. Em vez disso, as estruturas de payload são governadas estritamente pelo endpoint chamado. O parsing de respostas de clientes requer o roteamento de requisições para o endpoint do protocolo nativo de destino, em vez da inspeção de cabeçalhos de resposta para tipos de payload:

• Chat Completions (/v1/chat/completions): Utiliza esquemas compatíveis com a OpenAI retornando choices, message.content e um bloco usage (prompt_tokens, completion_tokens, total_tokens).
• Responses (/v1/responses): Adere ao formato da API Responses da OpenAI para tarefas em segundo plano, ferramentas de servidor e eventos de resposta.
• Anthropic Messages (/v1/messages): Interage com modelos Anthropic Claude usando o esquema nativo da Anthropic (blocos content, thinking e output_tokens). Ao configurar o SDK da Anthropic, defina a URL base como https://api.tokenlab.sh sem o prefixo /v1.
• Gemini (/v1beta/models/:model:generateContent): Aceita esquemas nativos do Gemini (contents, partes) e retorna objetos de candidatos REST padrão do Gemini.

Antes de rotear uma requisição de modelo, verifique quais protocolos ele aceita chamando Obter um Modelo (GET /v1/models/{model}) ou revisando o catálogo de Modelos. Inspecione a lista tokenlab.accepted_request_formats na resposta. Consulte o guia de Formatos de API para regras abrangentes de mapeamento de endpoints.

Cabeçalhos de Requisição Documentados

Todas as chamadas padrão para endpoints do TokenLab exigem cabeçalhos de requisição HTTP específicos:

• Authorization: Passa credenciais como um token bearer (Authorization: Bearer $TOKENLAB_API_KEY). Endpoints de gerenciamento exigem um token de gerenciamento (Authorization: Bearer mt-...).
• Content-Type: Deve ser application/json para requisições POST contendo corpos JSON.

Cabeçalhos de Resposta Documentados

O TokenLab retorna cabeçalhos HTTP padrão e personalizados para limites de taxa, reconciliação de faturamento e gerenciamento de tarefas assíncronas:

Cabeçalhos de Rate Limiting

Quando uma requisição excede os limites de nível da conta, o TokenLab retorna um status HTTP 429 rate_limit_exceeded acompanhado por dois cabeçalhos:

• Retry-After: Especifica o período de espera obrigatório em segundos antes de tentar a chamada novamente.
• X-RateLimit-Limit: Informa seu limite ativo de requisições por minuto para o nível autenticado.

Sempre use o valor do cabeçalho Retry-After para lidar com novas tentativas em vez de definir limites de backoff estáticos no código. Mais detalhes sobre o tratamento de recuperação estão no guia de Limites de Taxa.

Cabeçalhos de Faturamento e Observabilidade

Para interações não-streaming e assíncronas, o TokenLab fornece cabeçalhos de identificação para rastrear cobranças e processamento em segundo plano:

• X-Billing-Transaction-ID: Retornado quando o faturamento é liquidado antes do envio da resposta HTTP. Endpoints não-streaming compatíveis com a OpenAI incluem billing_transaction_id no corpo JSON, mas endpoints do Gemini e de formato nativo o expõem por meio deste cabeçalho. Chamadas com streaming podem ser liquidadas após o fechamento da conexão; quando ausente, recupere o ID dos registros de uso do workspace. Revise os fluxos de liquidação no guia de Faturamento e Preços.
• X-Task-ID: Retornado nos cabeçalhos de resposta ao criar jobs assíncronos para geração de vídeo, música, 3D ou imagem baseada em tarefas. Ele fornece um ID de correlação no nível do cabeçalho correspondente ao id da tarefa. Consulte o guia de Logs e Solução de Problemas para padrões de registro em log.

Implementação: Capturando Cabeçalhos e Tentando Novamente em Caso de 429

O exemplo em Python a seguir ilustra como enviar uma requisição ao endpoint de Chat Completions, inspecionar identificadores de transação e tratar cabeçalhos Retry-After durante limites de taxa:

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áticas de Registro em Log e Observabilidade

Ao instrumentar o monitoramento de requisições, registre os identificadores públicos de rastreamento retornados em cabeçalhos e payloads para reconciliar registros sem persistir prompts de usuários ou credenciais:

• Mantenha request_id, X-Billing-Transaction-ID e X-Task-ID junto aos códigos de status e latências de resposta.
• Sempre remova cabeçalhos Authorization, chaves de API brutas e URLs assinadas privadas dos pipelines de telemetria.
• Para reconciliação financeira do lado do servidor, consulte GET /v1/management/api-keys/{keyId}/usage em vez de extrair dados de páginas do dashboard ou estimar totais apenas a partir de contadores de tokens brutos.