✨ API Multi-Formato

Visão Geral

O TokenLab expõe quatro superfícies de protocolo com uma única chave de API: Chat Completions, Responses, Anthropic Messages e Gemini nativo. Uma entrada nativa só está disponível quando o modelo anuncia esse formato e existe uma rota upstream do mesmo protocolo; entradas nativas nunca voltam para Chat Completions. Apenas a entrada Chat pode ser compilada em uma direção para outro protocolo compatível.

Formato OpenAI

/v1/chat/completions Formato padrão, compatibilidade mais ampla

Responses

/v1/responses Ciclo de vida e eventos nativos de Responses

Formato Anthropic

/v1/messages Raciocínio estendido, recursos nativos do Claude

Formato Gemini

/v1beta/models/:model:generateContent Integração com o ecossistema Google

Por que Multi-Formato?

Benefício	Descrição
SDK nativo do protocolo	Use um SDK nativo apenas com modelos que anunciam esse formato; Chat continua sendo a superfície portátil mais ampla
Recursos nativos	Acesse funcionalidades específicas do formato
Migração fácil	Mude das APIs oficiais apenas alterando a URL base
Faturamento único	Uma conta, uma chave de API, todos os formatos

Comparação de Formatos

Recurso	OpenAI	Anthropic	Gemini
Endpoint	`/v1/chat/completions`	`/v1/messages`	`/v1beta/models/:model:generateContent`
Cabeçalho de Autenticação	`Authorization: Bearer`	`x-api-key`	`Authorization: Bearer`
Prompt do Sistema	No array `messages`	Campo separado `system`	Em `systemInstruction`
Raciocínio Estendido	❌	✅	❌
Fluxo contínuo	✅ SSE	✅ SSE	✅ SSE
Chamada de ferramentas	✅	✅	✅
Visão	✅	✅	✅

Formato OpenAI

Use esta rota de compatibilidade para integrações OpenAI SDK existentes e fluxos portáteis de chat ou embeddings. Para comportamento nativo Claude ou Gemini, use o formato Anthropic ou Gemini abaixo.

from openai import OpenAI

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

# Portable chat works across many models
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # Claude via OpenAI format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

Melhor para:

Uso geral
Integrações existentes com o SDK OpenAI
Compatibilidade máxima

Formato Anthropic

API Messages nativa da Anthropic. Necessário para recursos específicos do Claude, como o raciocínio estendido.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # No /v1 suffix!
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",  # Separate system field
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

Raciocínio Estendido (Claude Opus 4.6)

Disponível apenas no formato Anthropic:

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this complex problem..."}]
)

# Access thinking process
for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Answer: {block.text}")

Melhor para:

Recursos específicos do Claude
Modo de raciocínio estendido
Usuários do SDK Anthropic nativo

Formato Gemini

Formato nativo da API Google Gemini para integração ao ecossistema Google.

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Hello!"}]
    }],
    "systemInstruction": {
      "parts": [{"text": "You are a helpful assistant."}]
    }
  }'

Streaming

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a story"}]}]
  }'

Melhor para:

Integrações com Google Cloud
Código existente do SDK Gemini
Recursos nativos do Gemini

Gemini Files e Cache: A rota nativa do Gemini oferece /upload/v1beta/files, /v1beta/files, /v1beta/files:register e /v1beta/cachedContents. Files usa canais upstream compatíveis com a Gemini File API; recursos explícitos de Cache também podem ser roteados por canais Vertex AI. Recursos criados via TokenLab ficam vinculados ao mesmo canal/key upstream para chamadas generateContent posteriores.

Limite de compatibilidade de ferramentas

Ferramentas de função só podem ser compiladas em uma direção a partir da entrada Chat quando o destino representa o ciclo completo. Ferramentas nativas do provedor devem permanecer na rota nativa:

Ferramentas hospedadas e nativas do OpenAI Responses, como tool_search, web_search, file_search, code_interpreter, MCP, shell/apply_patch e ferramentas computer-use, exigem /v1/responses.
Ferramentas server/native da Anthropic, como web_search_*, web_fetch_*, code_execution_*, tool_search_*, bash, computer-use e text-editor, exigem /v1/messages.
Ferramentas integradas do Gemini, como googleSearch, codeExecution, urlContext, computerUse e campos tools semelhantes, exigem /v1beta.

O TokenLab não rebaixa solicitações de protocolo nativo para Chat Completions. Campos desconhecidos e combinações de ferramentas são encaminhados em best-effort; o upstream escolhido decide o suporte.

Escolhendo o Formato Certo

Guias de Migração

A partir da API Oficial da OpenAI

# Before (OpenAI)
client = OpenAI(api_key="sk-openai-key")

# After (TokenLab)
client = OpenAI(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1"  # Add this line
)
# That's it! Same code works

A partir da API Oficial da Anthropic

# Before (Anthropic)
client = Anthropic(api_key="sk-ant-key")

# After (TokenLab)
client = Anthropic(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # Add this line (no /v1!)
)

A partir do Google AI Studio

# Before (Google)
import google.generativeai as genai
genai.configure(api_key="google-api-key")

# After (TokenLab) - Use REST API
import requests

response = requests.post(
    "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent",
    headers={"Authorization": "Bearer sk-tokenlab-key"},
    json={"contents": [{"parts": [{"text": "Hello"}]}]}
)

Compatibilidade portátil de Chat

Use /v1/chat/completions quando um cliente precisar acessar modelos atendidos por protocolos upstream diferentes. Uma solicitação Chat portátil pode ser compilada em uma direção para Responses, Messages ou Gemini quando puder ser representada por completo. Solicitações nativas de Responses, Messages e Gemini nunca são convertidas para Chat; o nome do modelo ou provedor não implica disponibilidade nativa.

Limites de Responses e Gemini

A superfície atual de Responses inclui criação, compactação, recuperação, exclusão e SSE. Background funciona apenas por HTTP. WebSocket aceita somente response.create; o streaming é implícito, e background e response.cancel não são oferecidos nesse transporte. Excluir não é cancelar. No Gemini, tanto lowerCamelCase do ProtoJSON quanto os nomes proto originais em snake_case são oficiais e preservados, inclusive em solicitações mistas. A superfície atual inclui list/get models, generateContent, streamGenerateContent, countTokens, embedContent e batchEmbedContents; Interactions e Live não fazem parte dela. Campos desconhecidos são encaminhados em best-effort e o upstream decide o suporte.

Primeiros passos

Guias principais

Guias de mídia

✨ API Multi-Formato

Visão Geral

Formato OpenAI

Responses

Formato Anthropic

Formato Gemini

Por que Multi-Formato?

Comparação de Formatos

Formato OpenAI

Formato Anthropic

Raciocínio Estendido (Claude Opus 4.6)

Formato Gemini

Streaming

Limite de compatibilidade de ferramentas

Escolhendo o Formato Certo

Guias de Migração

A partir da API Oficial da OpenAI

A partir da API Oficial da Anthropic

A partir do Google AI Studio

Compatibilidade portátil de Chat

Limites de Responses e Gemini

​Visão Geral

Formato OpenAI

Responses

Formato Anthropic

Formato Gemini

​Por que Multi-Formato?

​Comparação de Formatos

​Formato OpenAI

​Formato Anthropic

​Raciocínio Estendido (Claude Opus 4.6)

​Formato Gemini

​Streaming

​Limite de compatibilidade de ferramentas

​Escolhendo o Formato Certo

​Guias de Migração

​A partir da API Oficial da OpenAI

​A partir da API Oficial da Anthropic

​A partir do Google AI Studio

​Compatibilidade portátil de Chat

​Limites de Responses e Gemini

Visão Geral

Por que Multi-Formato?

Comparação de Formatos

Formato OpenAI

Formato Anthropic

Raciocínio Estendido (Claude Opus 4.6)

Formato Gemini

Streaming

Limite de compatibilidade de ferramentas

Escolhendo o Formato Certo

Guias de Migração

A partir da API Oficial da OpenAI

A partir da API Oficial da Anthropic

A partir do Google AI Studio

Compatibilidade portátil de Chat

Limites de Responses e Gemini