Guias principais
Formatos de API
Escolha entre Chat Completions, Responses, Messages ou Gemini
Uma chave de API do TokenLab funciona com quatro formatos de API comuns. Mantenha o formato que sua aplicação já utiliza, a menos que precise de um recurso específico de um modelo.
| Formato | Endpoint | Escolha quando |
|---|---|---|
| Chat Completions | /v1/chat/completions | Você usa um cliente de chat compatível com OpenAI ou deseja ampla compatibilidade de modelos |
| Responses | /v1/responses | Sua aplicação usa eventos de Responses, respostas em segundo plano ou ferramentas de Responses |
| Anthropic Messages | /v1/messages | Você precisa de campos de Messages do Claude, como thinking ou uso de ferramentas do Claude |
| Gemini | /v1beta/models/:model:generateContent | Você já usa contents, parts, files, cache ou ferramentas do Gemini |
Verifique tokenlab.accepted_request_formats na página do modelo ou em GET /v1/models/{model}. Um modelo não aceita necessariamente todos os quatro formatos.
Chat Completions
O Chat Completions é a escolha mais fácil para clientes compatíveis com OpenAI existentes e recursos de chat portáteis.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.chat.completions.create(
model="gpt-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)Use este formato para:
- integrações de chat existentes compatíveis com OpenAI
- histórico de mensagens padrão e streaming
- chamada de função (function calling) suportada pelo modelo selecionado
Campos exclusivos de outro formato de API não têm garantia de funcionamento aqui.
Responses
Use Responses apenas quando o modelo selecionado listar openai_responses em accepted_request_formats.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain why the sky is blue in two sentences.",
)
print(response.output_text)A API de Responses suporta criação, recuperação, compactação, exclusão, streaming, criação e continuação de WebSocket e respostas em segundo plano, onde o modelo selecionado os suporta. A exclusão remove uma resposta armazenada; ela não cancela uma resposta ativa.
Anthropic Messages
Use o SDK da Anthropic com o host do TokenLab, sem adicionar /v1 à URL base.
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)Escolha Messages para campos de solicitação e resposta específicos do Claude. Mantenha chamadas de ferramentas do Claude, blocos de thinking e campos de prompt-cache neste formato.
Gemini
As solicitações do Gemini usam o host do TokenLab e o caminho REST do Gemini.
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.6-flash:generateContent" \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello!"}]}]
}'Escolha Gemini quando sua aplicação já usar partes de conteúdo, declarações de função, arquivos, conteúdo em cache ou outros campos do Gemini. Tanto nomes ProtoJSON em lowerCamelCase quanto nomes proto originais em snake_case são aceitos; evite enviar ambas as grafias do mesmo campo em uma única solicitação.
Não misture formatos em uma mesma conversa
Messages, Responses, Chat Completions e Gemini representam o estado da conversa e as chamadas de ferramentas de maneiras diferentes. Mantenha um único formato para cada conversa. Se precisar migrar um histórico armazenado, converta-o e valide-o em sua aplicação antes de enviar a próxima solicitação.
Campos desconhecidos
O TokenLab pode transmitir campos que não reconhece, mas isso não significa que todos os modelos os aceitem. É seguro depender de um recurso apenas quando o modelo selecionado o documenta e sua aplicação lida com um erro de campo não suportado.