Si has probado varias APIs de inteligencia artificial, ya conoces el lío: una clave para cada proveedor, límites distintos y una forma diferente de fallar en cada servicio. FreeLLMAPI intenta poner orden en todo eso con un router que expone una API compatible con OpenAI y también una superficie compatible con Anthropic.
La palabra importante es agrupar, no regalar. El proyecto no convierte una API de pago en ilimitada ni ejecuta modelos grandes en tu ordenador. Reúne las cuotas gratuitas que configures, controla su uso y prueba otro proveedor cuando el actual esté limitado. En este post vamos a montarlo con Docker y a conectarlo con OpenCode y Claude Code sin publicar las claves upstream.
Qué hace FreeLLMAPI
FreeLLMAPI funciona como un proxy y router local. Añades en su panel las claves de los proveedores que quieras utilizar y el servicio las guarda cifradas en SQLite. Después, tus clientes usan una única clave freellmapi-... y el router decide qué modelo disponible atiende cada petición.
La API OpenAI-compatible usa rutas como GET /v1/models y POST /v1/chat/completions. También incluye POST /v1/responses, /v1/completions para clientes de autocompletado, embeddings y una API Anthropic en POST /v1/messages. El catálogo de modelos se actualiza y cambia con frecuencia, así que conviene consultar el catálogo actual de FreeLLMAPI en vez de copiar una lista de nombres en un tutorial.
Cuando un proveedor responde con un 429, un error 5xx o agota el tiempo de espera, el router puede pasar al siguiente modelo de la cadena de fallback. El encabezado X-Routed-Via permite comprobar quién ha servido realmente la respuesta. El modo virtual fusion envía la consulta a varios modelos y deja que otro sintetice los borradores. Es interesante para comparar respuestas, pero una pregunta consume varias llamadas y agota antes las cuotas.
Instalación con Docker
La documentación de Docker del proyecto recomienda Docker, Docker Compose y OpenSSL. En macOS o Linux, la instalación manual queda así:
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 -dLa imagen oficial es ghcr.io/tashfeenahmed/freellmapi:latest. Compose publica el servicio en el puerto 3001 y guarda SQLite en el volumen freellmapi-data. La publicación está ligada a 127.0.0.1 por defecto, una decisión sensata para una herramienta personal.
Comprueba que el contenedor está funcionando y mira sus logs con los comandos que aparecen en la guía oficial de Docker:
docker compose ps
docker compose logs -f freellmapiAbre http://localhost:3001, crea la cuenta del panel y añade las claves de los proveedores desde Keys. La clave que utilizarán tus clientes es la unificada que aparece en esa página, no la clave de Google, Groq, OpenRouter o cualquier otro proveedor.
Si quieres instalar la versión más sencilla que ofrece el proyecto, su script oficial de instalación prepara ~/freellmapi, genera la clave de cifrado y arranca el contenedor. Aun así, leería el script antes de ejecutarlo y mantendría la instalación manual si necesitas controlar exactamente qué se lanza.
Servidor remoto
En un VPS o en una Raspberry Pi puedes arrancar Compose con HOST_BIND=0.0.0.0 para acceder desde una red de confianza:
HOST_BIND=0.0.0.0 docker compose up -dEsto solo cambia dónde escucha Docker; no añade seguridad. El proyecto está pensado para un único usuario y su documentación avisa de que no debe exponerse directamente a internet. Para acceder desde fuera, utiliza una red privada, un túnel o un reverse proxy con HTTPS y autenticación, y restringe el firewall. La instancia local y la instancia remota son escenarios distintos: una URL http://127.0.0.1:3001 solo funciona en la máquina donde corre FreeLLMAPI.
Primera prueba con la API
Guarda la clave unificada en una variable del shell para no pegarla en cada comando ni dejarla escrita en un archivo del repositorio:
export FREELLMAPI_KEY="freellmapi-tu-clave-unificada"
curl http://localhost:3001/v1/models \
-H "Authorization: Bearer $FREELLMAPI_KEY"Después prueba una conversación sencilla. auto permite que el router elija entre los modelos habilitados; también puedes usar un identificador concreto que aparezca en /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": "Explica qué hace Docker en tres frases."}
]
}'No uses fusion como modelo por defecto. La propia documentación del proyecto deja claro que ese modo hace varias llamadas y aplica las cuotas normales a cada una.
OpenCode: integración local o remota
OpenCode puede utilizar un proveedor compatible con OpenAI. En opencode.json, la URL base debe terminar en /v1, porque el SDK añade las rutas OpenAI sobre ese prefijo:
{
"$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"
}
}
}
}
}Configura la clave unificada mediante el mecanismo de credenciales de tu versión de OpenCode. No la pegues en opencode.json si ese archivo va a Git. La documentación de proveedores de OpenCode explica el formato de los proveedores personalizados, que puede cambiar entre versiones.
Con FreeLLMAPI y OpenCode en el mismo ordenador, 127.0.0.1 es la opción correcta. Si OpenCode está en otro equipo, sustituye esa dirección por una IP privada o por el hostname de una red segura. En ese caso ya no estás haciendo una integración local: el tráfico cruza la red y debes proteger el endpoint.
Claude Code: usa la superficie Anthropic
Aquí hay una diferencia que merece atención. Claude Code no espera una API OpenAI; utiliza el formato Anthropic Messages. FreeLLMAPI implementa /v1/messages, por lo que el valor de ANTHROPIC_BASE_URL debe ser el origen del servidor, sin añadir /v1/messages. Claude Code construye esa ruta internamente.
Con Claude Code y FreeLLMAPI en la misma máquina, prueba primero desde la misma terminal en la que vas a ejecutar claude:
export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
export ANTHROPIC_AUTH_TOKEN="$FREELLMAPI_KEY"
claudeFreeLLMAPI recomienda ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY: el primero se envía como Authorization: Bearer. La documentación oficial actual de conexión de Claude Code a un gateway confirma esas dos variables y también permite guardarlas en ~/.claude/settings.json dentro de env, o en .claude/settings.local.json para un proyecto concreto. El segundo archivo debe estar ignorado por Git si lo creas manualmente.
Para comprobar el endpoint sin abrir Claude Code puedes hacer una petición Anthropic directa:
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": "Responde solo: funciona"}]
}'El nombre claude-sonnet-4-5 es un ejemplo de la capa Anthropic. La pestaña Keys → Anthropic de FreeLLMAPI decide cómo se mapean las familias default, opus, sonnet y haiku al catálogo gratuito que tengas activado. Si falla porque el modelo no existe, comprueba el mapeo del panel y el catálogo actual; no asumas que el nombre de Claude implica que estás ejecutando un modelo de Anthropic.
Si FreeLLMAPI está en un servidor remoto, utiliza una URL https:// accesible desde la máquina donde se ejecuta Claude Code y protege ese servidor. Un localhost del portátil no apunta al VPS, y abrir el puerto sin HTTPS para salvar esa confusión es una mala solución.
Cursor: no confundas compatibilidad con soporte oficial
El README de FreeLLMAPI incluye Cursor entre los clientes que pueden usar su endpoint OpenAI-compatible y explica que las peticiones de Cursor se verifican y salen desde servidores de Cursor. Eso significa que una instancia ligada a localhost no les sirve: necesitarías un endpoint remoto accesible por internet, con HTTPS y controles de acceso.
La documentación oficial actual de Bring your own API key en Cursor, sin embargo, documenta las claves propias para OpenAI, Anthropic, Google, Azure y AWS Bedrock. No presenta una URL OpenAI arbitraria de terceros como una configuración estable ni promete que cualquier proxy compatible funcione. Además, Cursor indica que las peticiones pasan por sus servidores para construir el prompt final y que las claves propias no se conservan después de la petición; sus políticas de retención y sus funciones no son equivalentes a una llamada local directa.
Por eso no voy a inventar un paso universal de “pega esta variable en Cursor”. Si tu versión de Cursor muestra un campo de base URL o proveedor OpenAI personalizado, puedes probar con https://tu-dominio/v1, la clave unificada y auto, siguiendo la interfaz que realmente tengas delante. Si no aparece ese campo, Cursor no ofrece una integración directa documentada para esta instalación. En ese caso, utiliza FreeLLMAPI localmente con OpenCode o Claude Code, o publica un gateway correctamente protegido y acepta que Cursor seguirá procesando la petición desde su infraestructura.
Las cuotas gratuitas tienen fecha de caducidad
FreeLLMAPI no elimina los límites de sus proveedores. Una cuota puede ser por minuto, por día o por tokens; un modelo puede desaparecer, cambiar de capacidad o dejar de ser gratuito; y un proveedor puede responder con 429, tardar demasiado o exigir una tarjeta más adelante. El fallback ayuda a seguir funcionando, pero puede acabar usando un modelo más lento o menos capaz. La disponibilidad también cambia según la hora y según las claves que hayas añadido.
El modo fusion multiplica el consumo porque llama a varios modelos y a un juez. Y cuando se mezclan proveedores, también cambian la latencia, la ventana de contexto, el soporte de herramientas y la calidad de las respuestas. Esto está muy bien para aprender, experimentar, automatizar tareas personales y montar un entorno de pruebas.
No lo trataría como la base de un servicio crítico, un sistema multiusuario, atención al cliente con SLA ni un flujo que no pueda tolerar un 429. El propio proyecto se presenta como local-first, de usuario único y sin autenticación multi-tenant. Si necesitas disponibilidad garantizada, soporte y límites previsibles, utiliza un proveedor de pago con un contrato adecuado.
Seguridad que sí importa
La ENCRYPTION_KEY cifra las claves de proveedores en reposo. Genera una nueva al instalar, guárdala fuera del repositorio y conserva la misma junto al volumen al actualizar. Si pierdes esa clave, las credenciales cifradas pueden dejar de ser recuperables aunque siga existiendo el volumen SQLite.
No comitees .env, la clave unificada ni las claves upstream. Usa variables de entorno o un gestor de secretos, revisa qué archivos están ignorados y rota las claves si el host, el panel o un log pueden haber quedado expuestos. La clave unificada debe tener el alcance mínimo posible y nunca debe acabar en código frontend, capturas ni configuraciones compartidas.
En una instalación importante, fija una etiqueta de imagen en lugar de depender siempre de latest, actualiza de forma controlada y haz copias cifradas del volumen. Mantén el panel fuera de internet, pon HTTPS delante del servicio remoto y limita el acceso por red. El cifrado de SQLite no protege una máquina comprometida ni impide que FreeLLMAPI tenga que descifrar una clave en memoria para llamar al proveedor.
Conclusión
FreeLLMAPI es una pieza práctica para juntar varias cuotas gratuitas detrás de interfaces conocidas. Docker simplifica la instalación y el endpoint /v1 permite que OpenCode y otros clientes OpenAI-compatible hablen con el router sin integrar cada proveedor por separado. Para Claude Code, la ruta correcta es la superficie Anthropic en /v1/messages; para Cursor, la compatibilidad depende de que tu versión permita una base URL personalizada y de que puedas exponer el servicio de forma segura.
Empieza en local con un proveedor, una prueba con curl y una configuración de OpenCode. Observa qué ocurre con los límites y los fallbacks antes de añadir más claves o mover el servicio a un VPS. La ventaja real no es tener IA gratis e ilimitada, porque eso no existe: es poder experimentar con un único endpoint sin perder de vista quién controla tus datos, tus cuotas y tus claves.
¿Qué te ha parecido?
Déjame tu opinión, pregunta o sugerencia. Los comentarios se sincronizan con GitHub Discussions .