Documentação da API

Comece em 2 Minutos

A APIVAI fornece um proxy de API compatível com os formatos Anthropic e OpenAI. Basta definir duas variáveis de ambiente e você está pronto para começar.

1. Obtenha sua Chave de API

Cadastre-se em apivai.com e recarregue o saldo; depois crie uma chave de API na página Painel.

2. Defina sua URL Base

3. Comece a usar

Se ANTHROPIC_API_KEY já estiver definida no seu terminal, remova-a primeiro, ou ela será usada no lugar da sua chave da APIVAI: unset ANTHROPIC_API_KEY (PowerShell: Remove-Item Env:ANTHROPIC_API_KEY).

Claude Messages API (formato nativo da Anthropic)

Use a API padrão Anthropic Messages. Basta alterar base_url e api_key.

Python (Anthropic SDK)

cURL (Messages API)

cURL (streaming)

Listar modelos

Autenticação

Todas as solicitações de API exigem uma chave de API passada como token Bearer no cabeçalho Authorization (Authorization: Bearer YOUR_API_KEY). O cabeçalho x-api-key, que o SDK da Anthropic e o Claude Code enviam, também funciona. Obtenha sua chave de API no Painel após fazer login.

Usando OpenAI SDK

POST /v1/chat/completions

Cria uma conclusão de chat. Compatível com o formato de conclusões de chat da OpenAI.

Corpo da Solicitação

Modelos Disponíveis

Todos os modelos (Claude + GPT) podem ser chamados pelo mesmo endpoint, /v1/chat/completions. Os modelos Claude também funcionam por /v1/messages (formato Anthropic) e os GPT por /v1/responses (usado pelo Codex CLI). Informe o ID do modelo nas suas requisições.

Preços e detalhes de todos os modelos →

Streaming (SSE)

Defina stream: true para receber os tokens em tempo real via Server-Sent Events.

Use streaming em tarefas longas (muito raciocínio, respostas grandes): uma requisição sem streaming que leva mais de 100 segundos para responder é cortada no caminho; com streaming a conexão continua aberta por mais que o modelo pense.

Editores e agentes

Essas ferramentas aceitam uma base URL e uma chave compatíveis com OpenAI. Escolha o modelo em GET /v1/models e comece com uma tarefa pequena — ferramentas de agente enviam muitos tokens.

Codex CLI

O Codex usa a Responses API (/v1/responses), que o APIVAI oferece, então chamadas de ferramentas e streaming funcionam como esperado.

Cline

Aider

Para edições de rotina, um modelo mais barato costuma bastar; troque para um mais poderoso só em mudanças difíceis.

Continue.dev

Edite ~/.continue/config.yaml (Windows: %USERPROFILE%\.continue\config.yaml; o antigo formato config.json está obsoleto) e adicione uma entrada de modelo. Com provider: openai, o apiBase termina em /v1 e a mesma entrada funciona com IDs de modelos Claude e GPT. Guia completo: configuração do Continue.

Antes de começar

• A base URL contém /v1 exatamente uma vez.
• O modelo escolhido aparece na lista atual de modelos.
• O processo da ferramenta consegue ler a chave (ambiente ou configurações).
• As chaves ficam fora dos arquivos do projeto, das configurações compartilhadas e das capturas de tela.

Mais detalhes: API compatível com OpenAI · Proxy da API do Claude

Perguntas frequentes

Solução de problemas

Verifique nesta ordem: configuração, descoberta de modelos e depois uma requisição de chat mínima. Mantenha a requisição pequena até que endpoint, chave e modelo funcionem.

1. Verifique a lista de modelos

Se falhar, corrija a autenticação ou a base URL antes de testar qualquer outra coisa.

2. Envie uma requisição de chat mínima

Códigos de status

Todos os códigos de erro com causas e soluções: códigos de erro da API do Claude.

Por que recebo 404 Not Found?

O endereço final está errado — geralmente /v1 falta, sobra ou está repetido. As requisições precisam chegar a https://api.apivai.com/v1/messages, /v1/chat/completions, /v1/responses ou /v1/models; o Claude Code e o SDK da Anthropic usam https://api.apivai.com, as ferramentas no estilo OpenAI https://api.apivai.com/v1.

Por que minha chave retorna 401?

A chave está ausente, digitada errado, foi excluída ou não está visível para o processo que envia a requisição. No Claude Code, uma ANTHROPIC_API_KEY que ficou no terminal tem prioridade sobre a sua chave da APIVAI; remova-a.

Por que recebo 402 ou 429?

402 insufficient_quota significa que o orçamento da chave acabou: adicione orçamento à chave ou recarregue seu saldo. 429 significa requisições demais de uma vez (60 por minuto por chave por padrão) ou sem orçamento: diminua o ritmo e tente novamente com backoff.

Por que uma requisição longa falha com 524?

Uma requisição sem streaming que leva mais de ~100 segundos é cortada no caminho. Envie requisições longas com "stream": true; respostas em streaming não são cortadas.

Por que o streaming não exibe nada?

Geralmente o cliente não lê a resposta como stream ou ignora os trechos sem texto. Verifique:

• O corpo da requisição inclui "stream": true.
• Seu cliente HTTP lê o corpo de forma incremental.
• A requisição sem streaming funciona — isso separa problemas de parsing de problemas de autenticação ou de modelo.
• Alguns trechos trazem apenas metadados ou um motivo de término, sem texto.

Por que a resposta veio vazia ou cortada?

O raciocínio vem ativado por padrão e seus tokens contam para o limite de saída. Com um max_tokens pequeno, o modelo pode gastar todo o limite raciocinando e não retornar texto, e a requisição ainda é cobrada.

• O motivo de término é "length" (ou stop_reason é "max_tokens") — o limite foi atingido.
• Defina max_tokens como 4096 ou mais; para respostas longas ou código, 8192 ou mais.
• Você paga apenas pelos tokens realmente usados, então um limite maior não custa mais por si só.

Por que o curl retorna erro de parsing de JSON?

As aspas do terminal são uma causa frequente de erros de parsing de JSON. Salve o corpo em um arquivo e envie com --data @body.json.

Antes de contatar o suporte

• Código de status HTTP e caminho do endpoint (nunca a chave).
• Horário aproximado e fuso horário.
• Corpos de requisição e resposta sem segredos nem conteúdo privado.
• Ambiente de execução e versão, como Python ou Node.js.

Integração de Ferramentas

A APIVAI funciona como uma substituição direta das APIs oficiais. Basta alterar a URL base na sua ferramenta favorita.