✨ API Agent-First

Visão geral

A Agent-First API da TokenLab enriquece respostas de erro com dicas estruturadas que agentes de IA podem analisar e agir imediatamente — sem buscas na web, sem consultas à documentação, sem suposições. Erros de gateway compatíveis com OpenAI em Chat Completions e Responses podem incluir campos opcionais como did_you_mean, suggestions, hint, retryable e retry_after no objeto error. Anthropic Messages e Gemini mantêm seus formatos de erro nativos e não prometem essas extensões.

Campos de dica de erro

Nos erros de gateway compatíveis com OpenAI, todos os campos de dica são extensões opcionais dentro do objeto error:

Campo	Tipo	Descrição
`did_you_mean`	`string`	Nome do modelo com a correspondência mais próxima
`suggestions`	`array`	Modelos recomendados com metadados
`alternatives`	`array`	Modelos alternativos atualmente disponíveis
`hint`	`string`	Orientação de próxima etapa legível por humano/agente
`retryable`	`boolean`	Se tentar novamente a mesma solicitação pode ter sucesso
`retry_after`	`number`	Segundos a aguardar antes de tentar novamente
`balance_usd`	`number`	Saldo atual da conta em USD
`estimated_cost_usd`	`number`	Custo estimado da solicitação com falha

Exemplos de código de erro

model_not_found (400)

Quando um nome de modelo não corresponde a nenhum modelo ativo:

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [
      {"id": "gpt-5.4"},
      {"id": "gpt-5-mini"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

A resolução de did_you_mean utiliza:

Mapeamento de alias estático (a partir de dados de erro em produção)
Correspondência de string normalizada (remove hífens, sem distinção entre maiúsculas/minúsculas)
Correspondência por distância de edição (limite ≤ 3)

Rotas públicas não expõem códigos de erro separados para modelos ocultos, adiados ou não públicos. Trate modelos públicos indisponíveis da mesma forma que um erro de correspondência: verifique did_you_mean, suggestions e hint, e então tente novamente com um modelo público suportado.

insufficient_balance (402)

Quando o saldo da conta é insuficiente para o custo estimado:

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5-mini"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

suggestions contém modelos mais baratos que o custo estimado para os quais o agente pode alternar.

all_channels_failed (503)

Quando todos os canais upstream para um modelo estão indisponíveis:

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}

retryable é false quando a razão é no_channels (nenhum canal configurado para esse modelo). É true apenas para falhas transitórias como disparos de circuito ou esgotamento de cota.

rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

O valor de retry_after é calculado a partir do tempo real de reset da janela de limite de taxa.

Endpoints compatíveis com OpenAI usam os tipos de erro públicos estáveis da TokenLab, como rate_limit_exceeded, upstream_error e all_channels_failed. Endpoints compatíveis com Anthropic e Gemini usam suas próprias formas de resposta nativas.

context_length_exceeded (400)

Quando a entrada excede a janela de contexto do modelo (erro upstream, enriquecido com dicas):

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Descoberta de endpoints nativos

Não deduza a disponibilidade de um protocolo nativo pelo nome do modelo ou provedor nem por cabeçalhos de resposta do Chat. Antes de escolher um endpoint nativo, consulte GET /v1/models/{model} e use apenas um formato de solicitação anunciado nos detalhes do modelo e atendido por uma rota do mesmo protocolo. O campo a consultar é tokenlab.accepted_request_formats.

Formato da solicitação	Endpoint
Chat Completions	`/v1/chat/completions`
Responses	`/v1/responses`
Messages	`/v1/messages`
Gemini	`/v1beta/models/{model}:generateContent`

O formato anunciado determina a disponibilidade do endpoint; o suporte a campos e ferramentas específicos continua dependendo do upstream.

Melhorias em /v1/models

/v1/models agora carrega metadados de recomendação não-chat que agentes podem usar antes de chamar endpoints de imagem, vídeo, música, 3D, TTS, STT, embedding, rerank ou tradução.

{
  "id": "gemini-2.5-flash-image",
  "tokenlab": {
    "category": "image",
    "pricing_unit": "per_request",
    "agent_preferences": {
      "image": {
        "preferred_rank": 1,
        "success_rate_24h": 0.98,
        "sample_count_24h": 423,
        "status": "ready",
        "updated_at": "2026-03-28T12:00:00.000Z",
        "basis": {
          "source": "recent_activity_24h"
        }
      }
    }
  }
}

Campo	Valores	Descrição
`category`	`chat`, `image`, `video`, `audio`, `tts`, `stt`, `3d`, `embedding`, `rerank`	Tipo de modelo
`pricing_unit`	`per_token`, `per_image`, `per_second`, `per_request`	Como o modelo é cobrado
`cache_pricing`	object or `null`	Só é retornado quando o modelo tem preços de prompt cache upstream.
`agent_preferences.<scene>`	object	Snapshot de recomendação não-chat retornado apenas em `GET /v1/models?recommended_for=<scene>`

Quando recommended_for está presente, agent_preferences é derivado de um snapshot de taxa de sucesso em cache de 24 horas:

Janela: 24 horas
Cache do snapshot: stale-while-revalidate
status = "ready" significa que o modelo tem amostras recentes suficientes para participar do ranqueamento
status = "insufficient_samples" significa que o modelo permanece visível, mas não é ranqueado à frente de modelos pontuados

Filtragem por categoria

GET https://api.tokenlab.sh/v1/models?category=chat          # Chat models only
GET https://api.tokenlab.sh/v1/models?category=image         # Image generation models
GET https://api.tokenlab.sh/v1/models?tag=coding&category=chat  # Coding-optimized chat models

Descoberta de recomendações

Para fluxos não-chat, agentes devem buscar primeiro a lista recomendada atual:

GET https://api.tokenlab.sh/v1/models?recommended_for=image
GET https://api.tokenlab.sh/v1/models?recommended_for=translation
GET https://api.tokenlab.sh/v1/models?category=tts&recommended_for=tts

Valores válidos para recommended_for são:

image
video
music
3d
tts
stt
embedding
rerank
translation

Se category e recommended_for estiverem presentes, eles devem corresponder exatamente. Fluxo recomendado para agentes:

GET /v1/models?recommended_for=<scene>
Escolher o primeiro modelo com agent_preferences.<scene>.status == "ready"
Chamar o endpoint explicitamente com model=<selected>
Em erros transitórios apenas, tentar novamente com o próximo modelo ready

llms.txt

Uma visão geral da API em formato legível por máquina está disponível em:

GET https://api.tokenlab.sh/llms.txt

Inclui:

Template para a primeira chamada com um exemplo funcional
Nomes comuns de modelos (gerados dinamicamente a partir dos dados de uso)
Todos os 12 endpoints da API
Parâmetros de filtro para descoberta de modelos
Orientações de tratamento de erros

Agentes de IA que leem llms.txt antes da primeira chamada à API normalmente conseguem ter sucesso na primeira tentativa.

Uso no código do agente

Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokenlab.sh/v1"
)

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # Use did_you_mean for auto-correction
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

JavaScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

Princípios de design

Falhe rápido, falhe de forma informativa

Erros retornam imediatamente com todos os dados que um agente precisa para se auto-corrigir.

Sem roteamento automático

A API nunca substitui silenciosamente um modelo diferente. O agente decide.

Sugestões orientadas por dados

Todas as recomendações vêm de dados de produção, não de listas codificadas.

Compatível com versões anteriores

Todos os campos de dica são opcionais. Clientes existentes não veem diferença.

Primeiros passos

Guias principais

Guias de mídia

✨ API Agent-First

Visão geral

Campos de dica de erro

Exemplos de código de erro

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Descoberta de endpoints nativos

Melhorias em /v1/models

Filtragem por categoria

Descoberta de recomendações

llms.txt

Uso no código do agente

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Princípios de design

Falhe rápido, falhe de forma informativa

Sem roteamento automático

Sugestões orientadas por dados

Compatível com versões anteriores

​Visão geral

​Campos de dica de erro

​Exemplos de código de erro

​model_not_found (400)

​insufficient_balance (402)

​all_channels_failed (503)

​rate_limit_exceeded (429)

​context_length_exceeded (400)

​Descoberta de endpoints nativos

​Melhorias em /v1/models

​Filtragem por categoria

​Descoberta de recomendações

​llms.txt

​Uso no código do agente

​Python (OpenAI SDK)

​JavaScript (OpenAI SDK)

​Princípios de design

Falhe rápido, falhe de forma informativa

Sem roteamento automático

Sugestões orientadas por dados

Compatível com versões anteriores

Visão geral

Campos de dica de erro

Exemplos de código de erro

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Descoberta de endpoints nativos

Melhorias em /v1/models

Filtragem por categoria

Descoberta de recomendações

llms.txt

Uso no código do agente

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Princípios de design