Se você já tentou usar várias APIs de inteligência artificial, conhece a confusão: uma chave para cada provedor, limites diferentes e um jeito diferente de falhar em cada serviço. O FreeLLMAPI tenta organizar isso com um router que expõe uma API compatível com OpenAI e também uma interface compatível com Anthropic.
A palavra importante aqui é juntar, não dar de graça. O projeto não transforma uma API paga em ilimitada e também não roda modelos grandes no seu computador. Ele reúne as cotas gratuitas que você configurar, acompanha o uso e tenta outro provedor quando o atual chega ao limite. Vamos subir tudo com Docker e conectar ao OpenCode e ao Claude Code sem expor as chaves originais dos provedores.
O Que o FreeLLMAPI Faz de Verdade
O FreeLLMAPI funciona como proxy e router local. Você adiciona no painel as chaves dos provedores que pretende usar, e o serviço guarda tudo criptografado no SQLite. Depois, seus clientes usam uma única chave freellmapi-..., enquanto o router escolhe um modelo disponível para cada requisição.
A API compatível com OpenAI oferece rotas como GET /v1/models e POST /v1/chat/completions. Ela também inclui POST /v1/responses, /v1/completions para clientes de autocomplete, embeddings e uma API Anthropic em POST /v1/messages. O catálogo de modelos muda com frequência, então consulte o catálogo atual do FreeLLMAPI em vez de copiar uma lista fixa para um tutorial.
Quando um provedor responde com 429, um erro 5xx ou demora demais, o router pode passar para o próximo modelo da cadeia de fallback. O cabeçalho X-Routed-Via mostra quem realmente respondeu à requisição. O modo virtual fusion envia o prompt para vários modelos e pede que outro sintetize os rascunhos. É interessante para comparar respostas, mas uma pergunta passa a consumir várias chamadas e acaba com as cotas muito mais rápido.
Instalação com Docker
A documentação de Docker do projeto recomenda Docker, Docker Compose e OpenSSL. No macOS ou Linux, a instalação manual fica assim:
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -dA imagem oficial é ghcr.io/tashfeenahmed/freellmapi:latest. O Compose publica o serviço na porta 3001 e guarda o SQLite no volume freellmapi-data. Por padrão, a publicação fica presa a 127.0.0.1, o que é uma escolha sensata para uma ferramenta pessoal.
Confira se o contêiner está funcionando e acompanhe os logs:
docker compose ps
docker compose logs -f freellmapiAbra http://localhost:3001, crie a conta do painel e adicione as chaves em Keys. A chave que seus clientes vão usar é a chave unificada mostrada nessa página, não a chave do Google, Groq, OpenRouter ou de qualquer outro provedor.
Se quiser o caminho mais rápido, o script oficial de instalação do projeto prepara ~/freellmapi, gera a chave de criptografia e inicia o contêiner. Mesmo assim, eu leria o script antes de executá-lo e manteria a instalação manual se você precisar controlar exatamente o que está sendo iniciado.
Rodando em Outra Máquina
Em um VPS ou Raspberry Pi, você pode iniciar o Compose com HOST_BIND=0.0.0.0 quando precisar acessar o serviço a partir de uma rede confiável:
HOST_BIND=0.0.0.0 docker compose up -dIsso só muda onde o Docker escuta; não adiciona segurança. O projeto foi pensado para um único usuário, e a documentação avisa que ele não deve ser exposto diretamente à internet. Para acessar de fora, use uma rede privada, um túnel ou um reverse proxy com HTTPS e autenticação, além de restringir o firewall. Uma URL local como http://127.0.0.1:3001 só funciona na máquina onde o FreeLLMAPI está rodando.
Fazendo a Primeira Requisição
Guarde a chave unificada em uma variável do shell para não colá-la em todos os comandos nem deixá-la escrita em um arquivo do repositório:
export FREELLMAPI_KEY="freellmapi-sua-chave-unificada"
curl http://localhost:3001/v1/models \
-H "Authorization: Bearer $FREELLMAPI_KEY"Depois, teste uma conversa simples. auto deixa o router escolher entre os modelos habilitados; você também pode informar um identificador exato que apareça em /v1/models.
curl http://localhost:3001/v1/chat/completions \
-H "Authorization: Bearer $FREELLMAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Explique o que o Docker faz em três frases."}
]
}'Não use fusion como modelo padrão. A documentação do projeto para Anthropic e clientes Claude deixa claro que esse modo faz várias chamadas, e todas consomem as cotas normais.
OpenCode: Integração Local ou Remota
O OpenCode pode usar um provedor compatível com OpenAI. No opencode.json, a URL base precisa terminar em /v1, porque o SDK acrescenta as rotas OpenAI a esse prefixo:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"freellmapi": {
"npm": "@ai-sdk/openai-compatible",
"name": "FreeLLMAPI",
"options": {
"baseURL": "http://127.0.0.1:3001/v1"
},
"models": {
"auto": {
"name": "FreeLLMAPI Auto"
}
}
}
}
}Configure a chave unificada usando o mecanismo de credenciais aceito pela sua versão do OpenCode. Não coloque a chave no opencode.json se esse arquivo for para o Git. A documentação de provedores do OpenCode explica o formato de provedores personalizados, que pode mudar entre versões.
Se o OpenCode e o FreeLLMAPI estiverem no mesmo computador, 127.0.0.1 é o endereço certo. Se o OpenCode estiver em outra máquina, troque pelo IP privado ou pelo hostname de uma rede segura. Nesse caso, já não é uma integração local: o tráfego atravessa a rede e o endpoint precisa ser protegido.
Claude Code: Usando a Interface Anthropic
Aqui existe uma diferença importante. O Claude Code não espera uma API OpenAI; ele usa o formato Anthropic Messages. O FreeLLMAPI implementa /v1/messages, então ANTHROPIC_BASE_URL deve ser a origem do servidor, sem acrescentar /v1/messages. O próprio Claude Code monta esse caminho.
Com Claude Code e FreeLLMAPI na mesma máquina, teste primeiro no terminal em que você vai executar claude:
export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_AUTH_TOKEN="$FREELLMAPI_KEY"
claudeO FreeLLMAPI recomenda ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY: a primeira variável é enviada como Authorization: Bearer. A documentação atual do Claude Code para gateways confirma essas variáveis e também permite guardá-las em env, dentro de ~/.claude/settings.json, ou em .claude/settings.local.json para um projeto específico. Se criar o segundo arquivo manualmente, deixe-o fora do Git.
Antes de abrir o Claude Code, você pode testar o endpoint Anthropic diretamente:
curl "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 64,
"messages": [{"role": "user", "content": "Responda apenas: funciona"}]
}'O nome claude-sonnet-4-5 é apenas um exemplo da camada Anthropic. A aba Keys -> Anthropic do FreeLLMAPI decide como as famílias default, opus, sonnet e haiku são mapeadas para o catálogo gratuito que você ativou. Se o modelo não existir, confira o mapeamento no painel e o catálogo atual; um nome com “Claude” não significa que um modelo da Anthropic esteja rodando por trás.
Se o FreeLLMAPI estiver em um servidor remoto, use uma URL https:// acessível a partir da máquina onde o Claude Code roda e proteja esse servidor. O localhost do seu notebook não aponta para o VPS, e abrir a porta sem HTTPS não resolve o problema de verdade.
Cursor: Compatibilidade Não É Suporte Oficial
O README do FreeLLMAPI inclui o Cursor entre os clientes que podem usar o endpoint compatível com OpenAI e explica que as requisições do Cursor são verificadas e enviadas pelos servidores do próprio Cursor. Portanto, uma instância presa ao localhost não serve para esse caso: você precisaria de um endpoint remoto acessível pela internet, com HTTPS e controles de acesso.
A documentação atual do Cursor sobre Bring Your Own API Key, por outro lado, documenta chaves próprias para OpenAI, Anthropic, Google, Azure e AWS Bedrock. Ela não apresenta uma URL OpenAI arbitrária de terceiros como configuração estável nem promete que qualquer proxy compatível vai funcionar. O Cursor também informa que as requisições passam pelos servidores dele para montar o prompt final, então as políticas de retenção e o comportamento não são equivalentes a uma chamada local direta.
Por isso, não vou inventar um passo universal do tipo “cole esta variável no Cursor”. Se a sua versão do Cursor mostrar um campo de base URL ou de provedor OpenAI personalizado, você pode testar com https://seu-dominio/v1, a chave unificada e auto, seguindo a interface que realmente aparece para você. Se esse campo não existir, a sua instalação não oferece uma integração direta documentada. Nesse caso, use o FreeLLMAPI localmente com OpenCode ou Claude Code, ou publique um gateway bem protegido e aceite que o Cursor continuará processando a requisição pela própria infraestrutura.
As Cotas Gratuitas Têm Prazo
O FreeLLMAPI não remove os limites dos provedores. Uma cota pode ser por minuto, por dia ou por tokens; um modelo pode desaparecer, mudar de capacidade ou deixar de ser gratuito; e um provedor pode responder com 429, demorar demais ou passar a exigir cartão. O fallback ajuda a requisição a continuar, mas pode acabar usando um modelo mais lento ou menos capaz. A disponibilidade também muda conforme o horário e conforme as chaves que você adicionou.
O modo fusion multiplica o consumo porque chama vários modelos e um juiz. Ao misturar provedores, também mudam a latência, a janela de contexto, o suporte a ferramentas e a qualidade das respostas. Isso é ótimo para aprender, experimentar, automatizar tarefas pessoais e montar um ambiente de testes.
Eu não usaria isso como base de um serviço crítico, de um produto multiusuário, de atendimento ao cliente com SLA ou de qualquer fluxo que não possa tolerar um 429. O próprio projeto se apresenta como local-first, para um único usuário e sem autenticação multi-tenant. Se você precisa de disponibilidade garantida, suporte e limites previsíveis, use um provedor pago com um contrato adequado.
A Segurança Continua Importando
A ENCRYPTION_KEY criptografa as chaves dos provedores em repouso. Gere uma nova durante a instalação, mantenha-a fora do repositório e preserve o mesmo valor junto do volume ao atualizar. Se você perder essa chave, as credenciais criptografadas podem deixar de ser recuperáveis mesmo que o volume SQLite continue existindo.
Não faça commit de .env, da chave unificada ou das chaves originais. Use variáveis de ambiente ou um gerenciador de segredos, confira quais arquivos estão ignorados e faça a rotação das chaves se o host, o painel ou algum log puder ter sido exposto. A chave unificada deve ter o menor escopo possível e nunca deve aparecer em código de frontend, capturas de tela ou configurações compartilhadas.
Em uma instalação importante, fixe uma tag da imagem em vez de depender sempre de latest, atualize de forma controlada e faça backups criptografados do volume. Mantenha o painel fora da internet, coloque HTTPS na frente do serviço remoto e limite o acesso pela rede. A criptografia do SQLite não protege uma máquina comprometida e não impede que o FreeLLMAPI precise descriptografar uma chave na memória para chamar o provedor.
Conclusão
O FreeLLMAPI é uma forma prática de colocar várias cotas gratuitas atrás de interfaces conhecidas. O Docker simplifica a instalação, e o endpoint /v1 permite que o OpenCode e outros clientes compatíveis com OpenAI conversem com o router sem integrar cada provedor separadamente. Para o Claude Code, o caminho correto é a interface Anthropic em /v1/messages; para o Cursor, tudo depende de a sua versão permitir uma base URL personalizada e de você conseguir expor o serviço com segurança.
Comece localmente com um provedor, uma requisição com curl e uma configuração do OpenCode. Observe o que acontece quando os limites e os fallbacks entram em ação antes de adicionar mais chaves ou mover o serviço para um VPS. A vantagem real não é ter IA grátis e ilimitada, porque isso não existe; é experimentar com um endpoint único sem esquecer quem controla seus dados, suas cotas e suas chaves.
O que você achou?
Deixe sua opinião, pergunta ou sugestão. Os comentários são sincronizados com GitHub Discussions .