Voltar para o blog
post.md

FreeLLMAPI: como usar modelos gratuitos com Claude Code

Entenda como o FreeLLMAPI conecta Claude Code a provedores configurados por você, com instalação, roteamento, fallback e limites reais das faixas gratuitas.

FreeLLMAPIClaude CodeIALLMGatewayFallbackModelos gratuitos

O FreeLLMAPI não fornece tokens próprios: ele conecta as faixas gratuitas dos provedores para os quais você tem conta e chave. Cada oferta tem regras e limites.

Claude Code pode usar um endpoint que fala o protocolo de mensagens da Anthropic. O FreeLLMAPI aproveita essa possibilidade para encaminhar pedidos a modelos dos provedores que você configurou. É uma forma interessante de estudar gateways, roteamento e fallback sem integrar cada API separadamente.

Usar essa integração não transforma outro modelo em Claude. Recursos, qualidade e disponibilidade dependem do modelo escolhido. O próprio projeto recomenda experimentação pessoal e não oferece uma garantia de produção.

Consultei a documentação e o código em 12 de novembro de 2026. Os comandos abaixo seguem os guias oficiais; não executei um teste local com chaves reais para este artigo. Confira a versão instalada, os termos e os limites da sua conta.

O que é o FreeLLMAPI

É um gateway local que expõe interfaces compatíveis com clientes existentes. O aplicativo envia um pedido ao servidor local; o roteador seleciona um modelo elegível entre provedores habilitados e encaminha o pedido com a chave correspondente. A resposta volta ao cliente pela interface do gateway.

O projeto documenta /v1/chat/completions e /v1/responses para clientes no formato OpenAI, além de /v1/messages para o formato Anthropic. O painel permite cadastrar chaves, organizar a cadeia de fallback e consultar uso. O estado local fica em SQLite, e as chaves dos provedores são criptografadas em repouso.

Fluxo do Claude Code para o gateway FreeLLMAPI local e três provedores configurados pelo usuário.
O gateway reúne autenticação, seleção e medição de limites. Cada provedor continua exigindo conta e chave próprias.

Como o roteamento e o fallback funcionam

O roteador considera modelos e chaves saudáveis, prioridade ou estratégia configurada e limites de requisições e tokens por minuto ou por dia. Em falhas elegíveis, como 429 ou 5xx, ele pode colocar uma opção em espera e tentar outra da cadeia. Cabeçalhos como X-Routed-Via ajudam a identificar quem respondeu.

Fallback é uma nova tentativa de encaminhamento. Não garante continuar uma resposta já iniciada nem preservar qualidade, latência, contexto ou suporte a ferramentas quando o modelo muda. Um pedido longo pode ser enviado novamente a outro provedor; leve isso em conta ao avaliar limites, custo e dados.

O que significa “grátis” aqui

O catálogo inclui provedores como Google, Groq, Cerebras, Mistral, OpenRouter e Cloudflare. Modelos e limites mudam. Uma faixa gratuita, um crédito promocional e um modelo de pesos abertos são coisas diferentes: nenhum deles cria uma cota universal de tokens no gateway.

O README apresenta uma estimativa agregada de 7,4 bilhões de tokens por mês ao somar capacidades listadas. Essa é uma afirmação do mantenedor, não uma franquia individual verificada. Sua instalação só pode usar provedores aos quais sua conta tem acesso; limites por requisição, conta, projeto ou organização reduzem a capacidade prática. Não interprete o número como “Claude Code ilimitado”.

Instalação local com Docker Compose

O guia oficial oferece Docker, app desktop e execução a partir do código. Para o caminho com Docker Compose em macOS ou Linux, prepare Docker, Compose e OpenSSL. A chave de criptografia é gerada localmente e não deve ir para o repositório.

snippetbash
1git clone https://github.com/tashfeenahmed/freellmapi.git2cd freellmapi34ENCRYPTION_KEY="$(openssl rand -hex 32)"5printf 'ENCRYPTION_KEY=%s\nPORT=3001\n' "$ENCRYPTION_KEY" > .env67docker compose up -d

Abra http://localhost:3001, conclua a configuração inicial, cadastre suas chaves na página Keys e copie a chave unificada do gateway. Proteja .env, o volume SQLite, os backups e o acesso ao painel. O comando não cria contas nem créditos nos provedores.

Conectando ao Claude Code

Com o gateway ativo, o CLI pode preparar a configuração do cliente. Use --dry-run primeiro para inspecionar a alteração; o comando real mescla a configuração e cria backup. Mantenha a credencial fora do repositório.

snippetbash
1export FREELLMAPI_API_KEY='SUA_CHAVE_UNIFICADA'2npx freellmapi setup-claude --url http://localhost:3001 --dry-run3npx freellmapi setup-claude --url http://localhost:3001

Para Claude Code, a URL aponta para a raiz http://localhost:3001: o cliente adiciona a rota da API Anthropic. Clientes OpenAI costumam usar uma base com /v1. O CLI também documenta npx freellmapi launch para iniciar Claude Code com credenciais injetadas apenas no processo filho, sem gravá-las na configuração.

Teste primeiro uma tarefa pequena com chamadas de ferramentas e formato de resposta. O projeto também documenta setup-codex e launch-codex para Codex CLI pela interface /v1/responses; compatibilidade de protocolo não garante comportamento igual entre modelos.

Inspecionando uma requisição

Depois de configurar uma chave unificada válida, um pedido simples à API local permite observar a rota. O exemplo usa model: auto e imprime cabeçalhos. É um exemplo da documentação adaptado para inspeção, não um resultado executado aqui.

snippetbash
1curl -i http://localhost:3001/v1/chat/completions \2  -H "Authorization: Bearer $FREELLMAPI_API_KEY" \3  -H 'Content-Type: application/json' \4  -d '{"model":"auto","messages":[{"role":"user","content":"Explique fallback em uma frase."}]}'

Se um provedor estiver disponível, procure X-Routed-Via. Em caso de fallback, a referência da API descreve cabeçalhos de tentativas. O resultado depende das chaves, modelos e condições da instalação.

Limitações que mudam a decisão

  • Disponibilidade: o gateway acompanha cotas, mas não controla planos, filas, 429 ou mudanças dos provedores.
  • Qualidade e latência: após um fallback, o modelo pode ser menos adequado à tarefa; compare resultados de casos reais.
  • Privacidade: o roteador é local, mas prompt e contexto seguem ao provedor escolhido. Confira retenção, região e políticas de dados.
  • Segurança: a instalação é descrita como de usuário único. Proteja painel, token unificado, chave de criptografia, banco e backups.
  • Compatibilidade: contexto, streaming, ferramentas, visão e parâmetros variam por modelo e provedor.
  • Produção: sem SLA, não trate faixas gratuitas como base de uma funcionalidade que exige disponibilidade previsível.

Quando vale testar

Eu usaria o FreeLLMAPI para estudar como um gateway organiza múltiplos provedores, comparar modelos em tarefas pequenas e observar limites reais. Comece com um experimento reversível: dados não sensíveis, tarefa curta, orçamento de requisições conhecido e registro do modelo efetivamente usado. Se a qualidade ou as ferramentas não atenderem ao critério, volte à configuração anterior.

O valor técnico está em reunir integrações e oferecer fallback entre opções elegíveis. O acesso gratuito continua condicionado às contas e regras de terceiros; Claude Code é o cliente, mesmo quando outro modelo responde. Para depender desse caminho no trabalho, avalie dados, qualidade, limite e disponibilidade.

@brunopaim.dev

© 2026 Bruno Paim. Engenharia de software, IA e produtos digitais.