Referência da API

Visão Geral

A TokenLab é native-first e compatível com OpenAI. Use rotas nativas do provedor, como POST /v1/messages para Anthropic e /v1beta/models/...:generateContent para Gemini, quando precisar de comportamento nativo. Use endpoints /v1 compatíveis com OpenAI ao migrar SDKs ou ferramentas no estilo OpenAI. POST /v1/responses continua sendo um caminho avançado opcional para comportamento específico de Responses.

URL Base

https://api.tokenlab.sh

Autenticação

As solicitações a modelos usam uma chave API da TokenLab. O cabeçalho padrão de autenticação é:

Authorization: Bearer sk-your-api-key

GET /v1/models, GET /v1/models/{model} e GET /v1/pricing são públicos e não exigem chave. Anthropic Messages também aceita x-api-key; Gemini aceita x-goog-api-key ou ?key= além de Bearer. /v1/management/* exige um token de gerenciamento (mt-...).

Obtenha sua chave de API a partir do Dashboard.

Solicitações de geração aceitam X-TokenLab-Delivery-Policy: auto | verified | official. O cabeçalho tem prioridade sobre a chave API, que tem prioridade sobre o espaço de trabalho. auto prioriza TokenLab Verified e usa Official se necessário; a cobrança segue o modo que conclui a solicitação. verified usa preços TokenLab; official se baseia nos preços públicos do fabricante, ao preço exibido na TokenLab. Realtime usa a configuração da chave ou do espaço de trabalho, sem alteração por consulta. Cabeçalho inválido retorna 400; modo indisponível retorna 503 delivery_tier_unavailable e o ID da solicitação.

Sobre o Playground Interativo: O playground neste site de documentação é apenas para demonstração e não suporta a inserção de chaves de API. Para testar a API, por favor utilize:

cURL - Copie os comandos de exemplo e substitua sk-your-api-key pela sua chave real
Postman - Importe nossa OpenAPI spec
SDK - Use o SDK da OpenAI/Anthropic com nossa URL base

Endpoints Suportados

Chat & Geração de Texto

Endpoint	Método	Descrição
`/v1/chat/completions`	POST	Chat completions compatível com OpenAI
`/v1/messages`	POST	API de mensagens compatível com Anthropic
`/v1/responses`	POST	OpenAI Responses API

Embeddings e rerank

Endpoint	Método	Descrição
`/v1/embeddings`	POST	Criar embeddings de texto
`/v1/rerank`	POST	Reordenar documentos

Imagens

Endpoint	Método	Descrição
`/v1/images/generations`	POST	Gerar imagens a partir de texto
`/v1/images/edits`	POST	Editar imagens
`/v1/images/generations/{id}`	GET	Caminho de status de tarefa para respostas de imagem baseadas em tarefas

Os modelos de imagem podem retornar uma imagem pronta ou uma tarefa assíncrona. Se a resposta incluir poll_url, use essa URL para consultar a tarefa.

Áudio

Endpoint	Método	Descrição
`/v1/audio/speech`	POST	Texto para fala (TTS)
`/v1/audio/transcriptions`	POST	Transcrição de fala para texto (STT)

Tempo real

Endpoint	Método	Descrição
`/v1/realtime?model={model}`	WS	Sessões WebSocket em tempo real

Use /v1/realtime para solicitações de upgrade WebSocket. Um GET /v1/realtime comum retorna metadados do endpoint para clientes que não conseguem inspecionar rotas WebSocket diretamente. Esta não é a superfície REST do OpenAI Realtime; endpoints de client secret, translation client secret, Calls e legacy beta session não estão expostos no momento.

Vídeo

Endpoint	Método	Descrição
`/v1/videos/generations`	POST	Criar tarefa de geração de vídeo
`/v1/tasks/{id}`	GET	Obter status de tarefa assíncrona para jobs de vídeo
`/v1/videos/generations/{id}`	GET	Caminho de status de tarefa compatível com legados para vídeo

Para novos clientes, prefira /v1/tasks/{id} e siga o poll_url retornado pelas respostas de criação. Mantenha /v1/videos/generations/{id} apenas para compatibilidade retroativa.

Tarefas Assíncronas

Endpoint	Método	Descrição
`/v1/tasks/{id}`	GET	Endpoint unificado de status de tarefa assíncrona. Recomendado ao seguir um `poll_url` retornado

Este endpoint não se limita a vídeo, música e 3D. Algumas tarefas de imagem também podem usar /v1/tasks/{id} como o caminho canônico de polling.

Música

Endpoint	Método	Descrição
`/v1/music/generations`	POST	Criar tarefa de geração de música
`/v1/music/generations/{id}`	GET	Caminho de status específico para música

Para novos clientes, prefira primeiro o poll_url retornado. Se você precisar de um endpoint fixo de status de tarefa, use /v1/tasks/{id}; mantenha /v1/music/generations/{id} para caminhos de compatibilidade específicos de música.

Geração 3D

Endpoint	Método	Descrição
`/v1/3d/generations`	POST	Criar tarefa de geração de modelo 3D
`/v1/3d/generations/{id}`	GET	Caminho de status específico para 3D

Para novos clientes, prefira primeiro o poll_url retornado. Se você precisar de um endpoint fixo de status de tarefa, use /v1/tasks/{id}; mantenha /v1/3d/generations/{id} para caminhos de compatibilidade específicos de 3D.

Modelos

Endpoint	Método	Descrição
`/v1/models`	GET	Listar todos os modelos disponíveis
`/v1/models/{model}`	GET	Obter informações de um modelo específico

Gemini (v1beta)

Suporte nativo ao formato da API Google Gemini:

Endpoint	Método	Descrição
`/v1beta/models/{model}:generateContent`	POST	Gerar conteúdo (formato Gemini)
`/v1beta/models/{model}:streamGenerateContent`	POST	Gerar conteúdo em stream (formato Gemini)

Os endpoints Gemini suportam autenticação por parâmetro de query ?key= além do token Bearer padrão.

Formato de Resposta

Cada endpoint mantém seu formato API. Os exemplos de sucesso e erro abaixo usam o formato Chat Completions.

Resposta de Sucesso

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Transparência de Roteamento

O TokenLab não expõe detalhes de provedor, canal, política ou credenciais nos corpos de resposta públicos. Não dependa de _routing ou de outros campos internos de roteamento como campos aceitos pela API.

Para depuração e suporte, use os cabeçalhos públicos de resposta quando estiverem presentes:

Cabeçalho	Descrição
`X-Routing-Time-MS`	Tempo de seleção de rota, quando disponível
`X-Request-ID`	Identificador da solicitação para suporte e depuração, quando disponível
`X-Task-ID`	Identificador público de tarefa assíncrona para respostas baseadas em tarefas, quando disponível
`X-Billing-Transaction-ID`	Identificador da transação de faturamento após o faturamento final, quando disponível

Resposta de Erro

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

Limites de Taxa

Os limites de taxa são baseados em função e configuráveis por administradores. Valores padrão:

Função	Requisições/min
Usuário	1.000
Parceiro	10.000
VIP	10.000

Contate o suporte para limites de taxa personalizados. Valores exatos podem variar conforme a configuração da conta.

Quando os limites de taxa são excedidos, a API retorna um código de status 429 com um cabeçalho Retry-After indicando quanto tempo esperar.

Especificação OpenAPI

Baixe a especificação completa OpenAPI 3.1

Referência da API

Visão GeralCopy Anchor Link

URL BaseCopy Anchor Link

AutenticaçãoCopy Anchor Link

Endpoints SuportadosCopy Anchor Link

Chat & Geração de TextoCopy Anchor Link

Embeddings e rerankCopy Anchor Link

ImagensCopy Anchor Link

ÁudioCopy Anchor Link

Tempo realCopy Anchor Link

VídeoCopy Anchor Link

Tarefas AssíncronasCopy Anchor Link

MúsicaCopy Anchor Link

Geração 3DCopy Anchor Link

ModelosCopy Anchor Link

Gemini (v1beta)Copy Anchor Link

Formato de RespostaCopy Anchor Link

Resposta de SucessoCopy Anchor Link

Transparência de RoteamentoCopy Anchor Link

Resposta de ErroCopy Anchor Link

Limites de TaxaCopy Anchor Link

Especificação OpenAPICopy Anchor Link

Especificação OpenAPI

Nesta página

Visão Geral

URL Base

Autenticação

Endpoints Suportados

Chat & Geração de Texto

Embeddings e rerank

Imagens

Áudio

Tempo real

Vídeo

Tarefas Assíncronas

Música

Geração 3D

Modelos

Gemini (v1beta)

Formato de Resposta

Resposta de Sucesso

Transparência de Roteamento

Resposta de Erro

Limites de Taxa

Especificação OpenAPI