Essencial

Referência da API

Endpoints, autenticação, cabeçalhos de resposta e erros

Visão Geral

O TokenLab suporta endpoints compatíveis com OpenAI, além dos formatos de solicitação Anthropic e Gemini. Clientes OpenAI existentes podem usar /v1; escolha outro formato apenas quando sua aplicação precisar de um comportamento específico daquela API. POST /v1/responses é opcional e depende do suporte do modelo.

URL Base

https://api.tokenlab.sh

Autenticação

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

Authorization: Bearer sk-your-api-key

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

Obtenha sua chave de API no Console.

Política de Entrega

As solicitações de geração aceitam X-TokenLab-Delivery-Policy: auto | verified | official. Um cabeçalho de solicitação substitui a configuração da chave de API, que por sua vez substitui o padrão do Workspace.

  • Auto usa o TokenLab Verified quando disponível, e então o Official, se necessário. Você paga pela opção que concluir sua solicitação.
  • TokenLab Verified é uma entrega verificada pelo TokenLab. O preço Verified é aplicado.
  • Official cobra o preço Official, que é o preço publicado pelo criador do modelo.
  • Sessões em tempo real usam a chave de API ou a configuração do Workspace e não aceitam substituição via solicitação.

Um cabeçalho inválido retorna 400. Se a opção solicitada não estiver disponível, o TokenLab retorna 503 delivery_tier_unavailable e um ID de solicitação. Leia retryable: quando a operação selecionada não tem disponibilidade, o valor é false. Não repita a mesma solicitação sem alterações.

As páginas da API com um formulário de solicitação aceitam sua chave de API do TokenLab e enviam solicitações reais. Essas solicitações utilizam o saldo e os limites da sua conta. Você também pode usar cURL, Postman ou um SDK.

Endpoints Suportados

Chat e Geração de Texto

EndpointMétodoDescrição
/v1/chat/completionsPOSTCompletions de chat compatíveis com OpenAI
/v1/messagesPOSTMessages compatíveis com Anthropic
/v1/messages/count_tokensPOSTContar os tokens de entrada de uma solicitação Messages
/v1/messages/batchesPOST, GETCriar e listar Message Batches
/v1/messages/batches/{message_batch_id}GET, DELETERecuperar ou excluir um Message Batch
/v1/messages/batches/{message_batch_id}/resultsGETLer os resultados
/v1/messages/batches/{message_batch_id}/cancelPOSTCancelar um Message Batch
/v1/responsesPOSTAPI de Responses da OpenAI
/v1/responses/{id}GET, DELETERecuperar ou excluir uma resposta armazenada
/v1/responses/compactPOSTCompactar o contexto de uma conversa de Responses
/v1/translationsPOSTTradução de texto para texto

Embeddings e Rerank

EndpointMétodoDescrição
/v1/embeddingsPOSTCriar embeddings de texto
/v1/multimodal/embeddingsPOSTCriar embeddings com um modelo de embedding multimodal
/v1/rerankPOSTRerank de documentos

Decisões

EndpointMétodoDescrição
/v1/systemonePOSTAvaliar perguntas de decisão tipadas

Arquivos e Batches

EndpointMétodoDescrição
/v1/filesPOST, GETUpload e listar arquivos
/v1/files/{file_id}GET, DELETERecuperar ou excluir um arquivo
/v1/files/{file_id}/contentGETBaixar conteúdo do arquivo
/v1/batchesPOST, GETCriar e listar batches
/v1/batches/{batch_id}GETRecuperar um batch
/v1/batches/{batch_id}/cancelPOSTCancelar um batch

Imagens

EndpointMétodoDescrição
/v1/images/generationsPOSTGerar imagens a partir de texto
/v1/images/editsPOSTEditar imagens
/v1/images/variationsPOSTCriar variações de imagem
/v1/images/generations/{id}GETCaminho de status de compatibilidade para respostas de imagem baseadas em tarefa

Modelos de imagem podem retornar uma imagem finalizada ou uma tarefa assíncrona. Se a resposta incluir status: "pending" ou um ID de tarefa, consulte GET /v1/tasks/{id}.

Áudio

EndpointMétodoDescrição
/v1/audio/speechPOSTTexto para fala (TTS)
/v1/audio/transcriptionsPOSTFala para texto (STT)
/v1/audio/translationsPOSTTraduzir fala para texto em inglês

Tempo Real

EndpointMétodoDescrição
/v1/realtime?model={model}WSSessões WebSocket em tempo real

Use /v1/realtime para upgrades de WebSocket. Um GET /v1/realtime simples retorna metadados do endpoint. Esta não é a interface REST de tempo real da OpenAI; client-secret, Calls e endpoints de sessão beta legados não estão disponíveis.

Vídeo

EndpointMétodoDescrição
/v1/videos/generationsPOSTCriar tarefa de geração de vídeo
/v1/videos/generations/{id}GETCaminho de status de compatibilidade
/v1/videos/assetsPOST, GETCriar e listar ativos de material Seedance
/api/v3/contents/generations/tasksPOST, GETTarefas Seedance com o formato de solicitação Volcengine

Consulte GET /v1/tasks/{id} com o id da tarefa. /v1/videos/generations/{id} permanece disponível para integrações existentes.

Tarefas Assíncronas

EndpointMétodoDescrição
/v1/tasks/{id}GETStatus para qualquer tarefa assíncrona
/v1/tasks/{id}DELETECancelar uma tarefa assíncrona

Consulte GET /v1/tasks/{id} para cada tarefa assíncrona: imagens, vídeo, música, 3D, Worlds e transcrição de áudio assíncrona. Use o id ou task_id da resposta de criação. Uma resposta de criação de Worlds retorna uma poll_url em /v1/worlds/generations/{id}; consulte /v1/tasks/{id} lá também. Os caminhos de status por modalidade nesta página são endpoints de compatibilidade para integrações existentes.

Música

EndpointMétodoDescrição
/v1/music/generationsPOSTCriar tarefa de geração de música
/v1/music/generations/{id}GETCaminho de status de compatibilidade

Geração 3D

EndpointMétodoDescrição
/v1/3d/generationsPOSTCriar tarefa de geração de modelo 3D
/v1/3d/generations/{id}GETCaminho de status de compatibilidade

Worlds

EndpointMétodoDescrição
/v1/worlds/generationsPOSTCriar uma tarefa de geração de mundo
/v1/worlds/listPOSTListar mundos
/v1/worlds/{id}GET, DELETERecuperar ou excluir um mundo
/v1/worlds/media-assets/prepare-uploadPOSTPreparar um upload de ativo de mídia

Modelos e Preços

EndpointMétodoDescrição
/v1/modelsGETListar todos os modelos disponíveis
/v1/models/{model}GETObter informações de um modelo específico
/v1/models/{model}/pricingGETObter os preços de um modelo
/v1/pricingGETListar preços dos modelos

Gemini (v1beta)

Suporte nativo ao formato da API Google Gemini:

EndpointMétodoDescrição
/v1beta/modelsGETListar modelos que aceitam solicitações Gemini
/v1beta/models/{model}GETObter um modelo
/v1beta/models/{model}:generateContentPOSTGerar conteúdo
/v1beta/models/{model}:streamGenerateContentPOSTGerar conteúdo via stream
/v1beta/models/{model}:countTokensPOSTContar tokens
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEArquivos e conteúdo em cache do Gemini

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

Gerenciamento

/v1/management/* gerencia saldo, chaves de API e webhooks com um token de gerenciamento. Veja a API de Gerenciamento.

Formato de Resposta

Cada endpoint preserva seu formato de 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
  }
}

Cabeçalhos de resposta

Use estes cabeçalhos quando estiverem presentes.

CabeçalhoDescrição
X-Request-IDIdentificador de solicitação para suporte e depuração
X-Routing-Time-MSSem streaming: tempo total em milissegundos até a resposta do upstream, incluindo a fila e a inferência do upstream. Com streaming: sempre 0. Não mede roteamento nem fila.
X-Task-IDIdentificador público de tarefa assíncrona para respostas baseadas em tarefa
X-Billing-Transaction-IDIdentificador de transação de cobrança após o faturamento final

Rejeições oficiais de solicitação podem incluir upstream com o erro relatado pelo serviço e o nome público do serviço. Veja Lidar com erros da API.

Resposta de Erro

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

Limites de Taxa (Rate Limits)

Os limites dependem do nível da conta e aplicam-se por chave de API. Uma resposta 429 contém Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Veja Limites de taxa para os níveis e como tentar novamente.

Especificação OpenAPI

Especificação OpenAPI

Baixe a especificação completa da OpenAPI 3.1

Nesta página