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.shAutenticaçã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-keyGET /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.
Autousa 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.Officialcobra 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
| Endpoint | Método | Descrição |
|---|---|---|
/v1/chat/completions | POST | Completions de chat compatíveis com OpenAI |
/v1/messages | POST | Messages compatíveis com Anthropic |
/v1/messages/count_tokens | POST | Contar os tokens de entrada de uma solicitação Messages |
/v1/messages/batches | POST, GET | Criar e listar Message Batches |
/v1/messages/batches/{message_batch_id} | GET, DELETE | Recuperar ou excluir um Message Batch |
/v1/messages/batches/{message_batch_id}/results | GET | Ler os resultados |
/v1/messages/batches/{message_batch_id}/cancel | POST | Cancelar um Message Batch |
/v1/responses | POST | API de Responses da OpenAI |
/v1/responses/{id} | GET, DELETE | Recuperar ou excluir uma resposta armazenada |
/v1/responses/compact | POST | Compactar o contexto de uma conversa de Responses |
/v1/translations | POST | Tradução de texto para texto |
Embeddings e Rerank
| Endpoint | Método | Descrição |
|---|---|---|
/v1/embeddings | POST | Criar embeddings de texto |
/v1/multimodal/embeddings | POST | Criar embeddings com um modelo de embedding multimodal |
/v1/rerank | POST | Rerank de documentos |
Decisões
| Endpoint | Método | Descrição |
|---|---|---|
/v1/systemone | POST | Avaliar perguntas de decisão tipadas |
Arquivos e Batches
| Endpoint | Método | Descrição |
|---|---|---|
/v1/files | POST, GET | Upload e listar arquivos |
/v1/files/{file_id} | GET, DELETE | Recuperar ou excluir um arquivo |
/v1/files/{file_id}/content | GET | Baixar conteúdo do arquivo |
/v1/batches | POST, GET | Criar e listar batches |
/v1/batches/{batch_id} | GET | Recuperar um batch |
/v1/batches/{batch_id}/cancel | POST | Cancelar um batch |
Imagens
| Endpoint | Método | Descrição |
|---|---|---|
/v1/images/generations | POST | Gerar imagens a partir de texto |
/v1/images/edits | POST | Editar imagens |
/v1/images/variations | POST | Criar variações de imagem |
/v1/images/generations/{id} | GET | Caminho 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
| Endpoint | Método | Descrição |
|---|---|---|
/v1/audio/speech | POST | Texto para fala (TTS) |
/v1/audio/transcriptions | POST | Fala para texto (STT) |
/v1/audio/translations | POST | Traduzir fala para texto em inglês |
Tempo Real
| Endpoint | Método | Descrição |
|---|---|---|
/v1/realtime?model={model} | WS | Sessõ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
| Endpoint | Método | Descrição |
|---|---|---|
/v1/videos/generations | POST | Criar tarefa de geração de vídeo |
/v1/videos/generations/{id} | GET | Caminho de status de compatibilidade |
/v1/videos/assets | POST, GET | Criar e listar ativos de material Seedance |
/api/v3/contents/generations/tasks | POST, GET | Tarefas 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
| Endpoint | Método | Descrição |
|---|---|---|
/v1/tasks/{id} | GET | Status para qualquer tarefa assíncrona |
/v1/tasks/{id} | DELETE | Cancelar 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
| 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 de compatibilidade |
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 de compatibilidade |
Worlds
| Endpoint | Método | Descrição |
|---|---|---|
/v1/worlds/generations | POST | Criar uma tarefa de geração de mundo |
/v1/worlds/list | POST | Listar mundos |
/v1/worlds/{id} | GET, DELETE | Recuperar ou excluir um mundo |
/v1/worlds/media-assets/prepare-upload | POST | Preparar um upload de ativo de mídia |
Modelos e Preços
| 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 |
/v1/models/{model}/pricing | GET | Obter os preços de um modelo |
/v1/pricing | GET | Listar preços dos modelos |
Gemini (v1beta)
Suporte nativo ao formato da API Google Gemini:
| Endpoint | Método | Descrição |
|---|---|---|
/v1beta/models | GET | Listar modelos que aceitam solicitações Gemini |
/v1beta/models/{model} | GET | Obter um modelo |
/v1beta/models/{model}:generateContent | POST | Gerar conteúdo |
/v1beta/models/{model}:streamGenerateContent | POST | Gerar conteúdo via stream |
/v1beta/models/{model}:countTokens | POST | Contar tokens |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | Arquivos 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çalho | Descrição |
|---|---|
X-Request-ID | Identificador de solicitação para suporte e depuração |
X-Routing-Time-MS | Sem 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-ID | Identificador público de tarefa assíncrona para respostas baseadas em tarefa |
X-Billing-Transaction-ID | Identificador 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