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.
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.
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.
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 -dAbra 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.
1export FREELLMAPI_API_KEY='SUA_CHAVE_UNIFICADA'2npx freellmapi setup-claude --url http://localhost:3001 --dry-run3npx freellmapi setup-claude --url http://localhost:3001Para 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.
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.