> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Compatibilidade de IDE e SDK
> Diretrizes de compatibilidade baseadas em evidências para ferramentas de codificação, SDKs e frameworks de IA
## Visão Geral
O TokenLab expõe múltiplos formatos de API para que ferramentas de codificação, SDKs e frameworks comuns possam se integrar com o mínimo de código de adaptação.
Esta página é intencionalmente mais restrita do que uma matriz de marketing:
* **Suportado** significa que documentamos um caminho de configuração concreto e o TokenLab expõe o formato de protocolo que esse caminho espera.
* **Caminho nativo forte** significa que o repositório também possui evidências diretas de adaptador ou formato de solicitação para essa família de protocolos.
* **Melhor esforço** significa que a integração pode funcionar, mas o cliente upstream não trata este fluxo de gateway personalizado como um contrato estável.
Campos não suportados não são tratados de forma uniforme. Em rotas de compatibilidade, alguns campos são ignorados ou normalizados. Em `/v1/responses`, campos não suportados podem retornar erros explícitos `400` ou `503` quando essa rota não pode garantir o comportamento solicitado.
## Formatos de API Suportados
| Endpoint | Formato | Caso de Uso |
| --------------------------------------- | ------------------ | ------------------------------- |
| `/v1/chat/completions` | OpenAI Chat | Compatibilidade universal |
| `/v1/responses` | OpenAI Responses | Conversas com estado (stateful) |
| `/v1/messages` | Anthropic Messages | Recursos nativos do Claude |
| `/v1beta/models/:model:generateContent` | Google Gemini | Recursos nativos do Gemini |
## Compatibilidade de IDE e CLI
### Caminhos de Ferramentas Documentados
| Ferramenta | Nível de Suporte | Formato | Notas |
| ------------------- | --------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cursor** | Suportado com limites | Compatível com OpenAI | Funciona para fluxos padrão de chat/editor BYOK, não como substituto para recursos gerenciados pelo Cursor, como o Tab Completion |
| **Claude Code CLI** | Caminho nativo forte | Anthropic | Rota nativa `/v1/messages` com cobertura de adaptador para raciocínio (thinking) e `tool_choice` |
| **Codex CLI** | Suportado com limites de modelo/caminho | OpenAI Responses | Trate `/v1/responses` como um caminho avançado para fluxos de trabalho específicos do Codex; alguns campos exclusivos de Responses não são garantidos em todos os modelos e caminhos roteados |
| **Gemini CLI** | Melhor esforço / experimental | Gemini | O fluxo de URL base personalizado do TokenLab não é uma integração oficial da Gemini CLI |
| **OpenCode** | Suportado | Compatível com OpenAI | Use um provedor compatível com OpenAI por padrão; mude para um provedor baseado em Responses apenas quando precisar explicitamente |
| **OpenHands** | Suportado | Compatível com OpenAI | Use o caminho LiteLLM/compatível com OpenAI com `openai/` e a URL base `/v1` do TokenLab |
Outros editores e ferramentas de agente compatíveis com OpenAI geralmente funcionam com o mesmo padrão de URL base; verifique o suporte a provedores personalizados da própria ferramenta antes de usá-la em produção.
### Exemplos de Configuração
```
Base URL: https://api.tokenlab.sh/v1
API Key: sk-your-tokenlab-key
```
O Cursor usa internamente o formato de ferramentas estilo Anthropic. O TokenLab suporta ambos:
* Formato OpenAI: `{ type: "function", function: { name, parameters } }`
* Formato Anthropic: `{ name, input_schema }` (sem o campo type)
```bash theme={null}
export ANTHROPIC_BASE_URL="https://api.tokenlab.sh"
export ANTHROPIC_API_KEY="sk-your-tokenlab-key"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export LOCAL_ENDPOINT="https://api.tokenlab.sh/v1"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export OPENAI_BASE_URL="https://api.tokenlab.sh/v1"
aider --model gpt-5.4
```
## Compatibilidade de SDK
### Caminhos de SDK e Framework Documentados
| SDK / Framework | Linguagem | Nível de Suporte | Notas |
| -------------------------------------------------------- | ------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI SDK** | Python/JS/Go | Caminho principal suportado | Caminho de compatibilidade para Chat Completions e Embeddings `/v1`; use rotas de provedor nativas para comportamentos específicos do provedor e não presuma que campos exclusivos de Responses funcionem em todos os modelos |
| **Anthropic SDK** | Python/JS | Caminho nativo forte | Rota Messages nativa com evidência direta para ferramentas, raciocínio e cache de prompt |
| **Vercel AI SDK** | TypeScript | Padrão de integração recomendado | Prefira `@ai-sdk/openai-compatible`; use `@ai-sdk/openai` apenas quando desejar explicitamente o comportamento nativo de Responses |
| **LangChain** | Python/JS | Superfícies padrão suportadas | `ChatOpenAI` e `OpenAIEmbeddings` são o escopo pretendido; extras nativos de fornecedores estão fora do escopo |
| **LlamaIndex** | Python | Suportado via `OpenAILike` | Use `OpenAILike`, não as classes internas da OpenAI, para gateways de terceiros como o TokenLab |
| **OpenAI Agents SDK** | Python | Caminho de chat-completions suportado | Use `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` com `OpenAIChatCompletionsModel`; o comportamento nativo de Responses depende do modelo e da rota selecionados |
| **AutoGen** | Python | Caminho de endpoint personalizado suportado | Use `OpenAIChatCompletionClient` com `base_url: https://api.tokenlab.sh/v1` |
| **Semantic Kernel** | .NET | Caminho de endpoint personalizado suportado | Use o endpoint personalizado do conector de chat completion da OpenAI e aponte para `https://api.tokenlab.sh/v1` |
| **CrewAI** | Python | Caminho de endpoint personalizado suportado | Defina `OPENAI_API_BASE` ou `LLM(base_url=...)` para o endpoint `/v1` do TokenLab |
| **Pydantic AI** | Python | Caminho de provedor compatível com OpenAI suportado | Use `OpenAIChatModel` com `OpenAIProvider(base_url="https://api.tokenlab.sh/v1")` |
| **DSPy** | Python | Caminho de endpoint personalizado suportado | Use `dspy.LM("openai/", api_base="https://api.tokenlab.sh/v1")` |
| **Langflow** | Python / Web | Suportado com limites de escopo | Use o campo **OpenAI API Base** do componente OpenAI com o endpoint `/v1` do TokenLab |
| **Haystack** | Python | Caminho de endpoint personalizado suportado | Use `OpenAIChatGenerator(api_base_url="https://api.tokenlab.sh/v1")` |
| **Graphiti** | Python | Caminho de endpoint personalizado suportado | Use `OpenAIGenericClient` com o endpoint `/v1` do TokenLab |
| **Dify** | - | Suportado com limites de escopo | O provedor OpenAI e fluxos orientados a chat-completions são o caminho pretendido; não é adequado para Responses específicos do Codex ou comportamento de WebSocket |
| **Flowise** | Web / Node | Suportado com limites de escopo | Use o nó de chat do TokenLab quando disponível, ou um nó compatível com ChatOpenAI apontado para `https://api.tokenlab.sh/v1` |
| **Mem0** | Python | Caminho de endpoint personalizado suportado | Mantenha o provedor OpenAI e defina `openai_base_url` para o endpoint `/v1` do TokenLab |
| **Agno** | Python | Caminho suportado | Use o wrapper de modelo do TokenLab quando disponível, ou o caminho de URL base compatível com OpenAI |
| **Browser Use** | Python | Caminho de endpoint personalizado suportado | Use `ChatOpenAILike` com o endpoint `/v1` do TokenLab |
| **VoltAgent** | TypeScript | Caminho de endpoint personalizado suportado | Passe um provedor OpenAI do AI SDK configurado com `baseURL: "https://api.tokenlab.sh/v1"` |
| **Ragas** | Python | Caminho de endpoint personalizado suportado | Passe `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` para o `llm_factory` |
| **Guardrails** | Python | Caminho de validação suportado | Passe um callable de chat completions do SDK OpenAI configurado com o endpoint `/v1` do TokenLab |
| **Prompt flow** | Python / CLI | Caminho de endpoint personalizado suportado | Crie uma conexão OpenAI com `base_url=https://api.tokenlab.sh/v1` |
| **Promptfoo** | CLI / Node | Caminho suportado | Use provedores de chat ou Responses da OpenAI com `apiBaseUrl: https://api.tokenlab.sh/v1` |
| **Portkey Gateway** | Gateway | Caminho suportado | Use o TokenLab como um provedor upstream para tráfego de chat e Responses compatível com OpenAI |
| **Helicone** | Gateway / Observabilidade | Caminho de observabilidade suportado | Roteie solicitações compatíveis com OpenAI através do Helicone Gateway com `Helicone-Target-Url: https://api.tokenlab.sh` |
| **Langfuse** | Observabilidade | Caminho de rastreamento suportado | Configure a integração OpenAI do Langfuse com a URL base `/v1` do TokenLab |
| **OpenLIT** | Observabilidade | Caminho de rastreamento suportado | Instrumente um cliente SDK OpenAI configurado com a URL base `/v1` do TokenLab |
| **OpenLLMetry** | Observabilidade | Caminho de rastreamento suportado | Use a instrumentação do SDK OpenAI com a URL base `/v1` do TokenLab |
| **Phoenix** | Observabilidade | Caminho de rastreamento suportado | Auto-instrumente o cliente SDK OpenAI configurado com a URL base `/v1` do TokenLab |
| **Opik** | Observabilidade | Caminho de rastreamento suportado | Envolva um cliente SDK OpenAI configurado com a URL base `/v1` do TokenLab |
| **LangBot** | Bot Platform | Caminho de chat suportado | Use o solicitante do TokenLab quando disponível, ou configure um solicitante compatível com OpenAI com o endpoint `/v1` do TokenLab |
| **Open WebUI** | Web Chat | Caminho de chat-app suportado | Adicione o TokenLab como uma conexão de API compatível com OpenAI e atualize a lista de modelos |
| **Chatbox / DeepChat / Jan / LibreChat / Cherry Studio** | Desktop / Web | Caminho de chat-app suportado | Use o fluxo de provedor personalizado compatível com OpenAI de cada aplicativo; esses aplicativos geralmente são orientados a chat-completions |
## Parâmetros de Chat Completions
### Parâmetros Principais
| Parâmetro | Tipo | Descrição |
| ------------- | ------- | ------------------------------------- |
| `model` | string | Identificador do modelo (obrigatório) |
| `messages` | array | Mensagens da conversa (obrigatório) |
| `max_tokens` | integer | Tokens máximos de saída |
| `temperature` | number | Temperatura de amostragem (0-2) |
| `top_p` | number | Amostragem de núcleo (0-1) |
| `stream` | boolean | Habilitar streaming |
### Chamada de Ferramentas (Tool Calling)
```json theme={null}
{
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Obter previsão do tempo para um local",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
},
"strict": true
}
}
],
"tool_choice": "auto",
"parallel_tool_calls": true
}
```
### Opções de Escolha de Ferramenta (Tool Choice)
| Formato | Exemplo | Descrição |
| ---------------- | --------------------------------------------------------------------- | ------------------------ |
| String | `"auto"`, `"none"`, `"required"` | Seleção simples |
| Objeto OpenAI | `{ "type": "function", "function": { "name": "fn" } }` | Forçar função específica |
| Objeto Anthropic | `{ "type": "tool", "name": "fn", "disable_parallel_tool_use": true }` | Formato nativo Anthropic |
### Parâmetros Avançados
| Parâmetro | Tipo | Descrição |
| ------------------- | ------------ | -------------------------------------------------------------------------- |
| `stream_options` | object | Apenas Chat Completions: `{ include_usage: true }` para contagem de tokens |
| `reasoning_effort` | string | `"low"`, `"medium"`, `"high"` para modelos GPT-5 com raciocínio habilitado |
| `service_tier` | string | `"auto"` ou `"default"` |
| `seed` | integer | Saídas determinísticas |
| `logprobs` | boolean | Retornar log probabilidades |
| `top_logprobs` | integer | Número de top logprobs (0-20) |
| `logit_bias` | object | Mapa de viés de token (-100 a 100) |
| `frequency_penalty` | number | Penalidade de repetição (-2 a 2) |
| `presence_penalty` | number | Penalidade de tópico (-2 a 2) |
| `stop` | string/array | Sequências de parada |
| `n` | integer | Número de conclusões (1-128) |
| `user` | string | Identificador de usuário para rastreamento |
### Recursos Avançados da OpenAI
| Parâmetro | Tipo | Descrição |
| ------------ | ------- | --------------------------------------------- |
| `modalities` | array | `["text", "audio"]` para multimodal |
| `audio` | object | Configuração de saída de áudio (voz, formato) |
| `prediction` | object | Saída prevista para conclusão mais rápida |
| `metadata` | object | Pares chave-valor para rastreamento |
| `store` | boolean | Armazenar para recuperação posterior |
### Opções Específicas do Provedor
```json theme={null}
{
"anthropic_options": {
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"prompt_caching": true
},
"google_options": {
"safety_settings": [...],
"google_search": true,
"code_execution": true
}
}
```
## Parâmetros de Anthropic Messages
### Parâmetros Principais
| Parâmetro | Tipo | Descrição |
| ------------ | ------------ | ------------------------- |
| `model` | string | Identificador do modelo |
| `messages` | array | Mensagens da conversa |
| `max_tokens` | integer | Saída máxima (até 128000) |
| `system` | string/array | Prompt do sistema |
| `stream` | boolean | Habilitar streaming |
### Chamada de Ferramentas (Tool Calling)
```json theme={null}
{
"tools": [
{
"name": "get_weather",
"description": "Obter previsão do tempo",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
}
}
],
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
```
### Raciocínio Estendido (Extended Thinking)
```json theme={null}
{
"model": "claude-opus-4-6",
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}
```
## Parâmetros da API de Responses
### Parâmetros Principais
| Parâmetro | Tipo | Descrição |
| ---------------------- | ------------ | ----------------------- |
| `model` | string | Identificador do modelo |
| `input` | string/array | Conteúdo de entrada |
| `instructions` | string | Instruções do sistema |
| `max_output_tokens` | integer | Tokens máximos de saída |
| `previous_response_id` | string | Continuar conversa |
### Parâmetros Avançados
| Parâmetro | Tipo | Descrição |
| --------------------- | ------ | --------------------------------- |
| `truncation_strategy` | string | `"auto"` ou `"disabled"` |
| `include` | array | `["reasoning.encrypted_content"]` |
| `reasoning_effort` | string | Para modelos de raciocínio |
| `service_tier` | string | Nível de prioridade |
### Formato de Ferramenta
Suporta formatos de ferramenta da OpenAI e Anthropic:
```json theme={null}
// Formato OpenAI
{ "type": "function", "name": "fn", "parameters": {...} }
// Formato Anthropic (compatibilidade com Cursor)
{ "name": "fn", "input_schema": {...} }
```
## Parâmetros da API Gemini
### Parâmetros Principais
| Parâmetro | Tipo | Descrição |
| ------------------- | ------ | ------------------------ |
| `contents` | array | Conteúdo da conversa |
| `systemInstruction` | object | Prompt do sistema |
| `generationConfig` | object | Configurações de geração |
### Ferramentas
```json theme={null}
{
"tools": [{
"functionDeclarations": [{
"name": "search",
"description": "Pesquisar na web",
"parameters": {...}
}],
"codeExecution": {},
"googleSearch": {}
}],
"toolConfig": {
"functionCallingConfig": {
"mode": "AUTO"
}
}
}
```
### Configurações de Segurança
```json theme={null}
{
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_MEDIUM_AND_ABOVE"
}
]
}
```
### Parâmetros Adicionais
| Parâmetro | Tipo | Descrição |
| ------------------ | ------ | -------------------------------------- |
| `cachedContent` | string | Referência de conteúdo em cache |
| `responseMimeType` | string | `"text/plain"` ou `"application/json"` |
| `responseSchema` | object | Esquema JSON para saída estruturada |
## Streaming
Endpoints de geração que expõem `stream: true`, incluindo Chat Completions e Responses, usam Server-Sent Events (SSE):
```bash theme={null}
# Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
-H "Authorization: Bearer sk-xxx" \
-d '{"model": "gpt-4o", "messages": [...], "stream": true}'
# Rastreamento de uso de Chat Completions
-d '{"...", "stream_options": {"include_usage": true}}'
```
## Tratamento de Erros
O TokenLab retorna respostas de erro compatíveis com a OpenAI:
```json theme={null}
{
"error": {
"message": "Chave de API inválida",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}
```
Veja o [Guia de Tratamento de Erros](/guides/error-handling) para detalhes.
## Melhores Práticas
Parâmetros desconhecidos são encaminhados apenas quando a rota pública e o modelo selecionados os suportam.
Para streaming de Chat Completions, habilite `stream_options.include_usage` para contagens precisas de tokens. Responses possui seu próprio contrato de streaming e não expõe essa opção exclusiva de Chat.
Combine com o formato esperado pelo seu SDK. O TokenLab aceita formatos da OpenAI e da Anthropic.