oMLX no inventa su propia API: imita dos que ya existen, la de OpenAI y la de Anthropic, para que cualquier cliente escrito contra ellas apunte a tu Mac cambiando una dirección. Esta guía cubre los ocho endpoints que expone, cómo funciona la clave de API con sus subclaves, cuál es el puerto por defecto y cómo cambiarlo sin romper el servicio.

Puntos clave

  • El servidor escucha en 127.0.0.1 puerto 8000. Solo acepta conexiones locales mientras no cambies host.
  • La clave viaja en Authorization: Bearer o en x-api-key; la segunda existe por compatibilidad con el SDK de Anthropic.
  • Hay tres credenciales distintas: clave principal, subclaves de solo API y tokens de sesión del panel.
  • Los ajustes se resuelven en cascada: banderas de la orden, luego variables OMLX_*, luego ~/.omlx/settings.json, luego los valores por defecto.
  • Los cambios hechos desde el panel se aplican sin reiniciar el servidor. Los que escribas a mano en el fichero, no.

Los ocho endpoints que expone el servidor

oMLX habla tres dialectos a la vez sobre el mismo puerto. La mayoría de las rutas son la API de OpenAI tal cual, hay una de Anthropic y hay una tercera pensada para Codex.

Método Ruta Para qué sirve
POST /v1/chat/completions Chat con streaming, el formato de OpenAI
POST /v1/completions Compleción de texto plano
POST /v1/messages Messages API de Anthropic
POST /v1/responses Compatibilidad con Codex
POST /v1/embeddings Embeddings
POST /v1/rerank Reordenación de documentos
POST /v1/mcp/tools Herramientas de Model Context Protocol
GET /v1/models Catálogo de modelos disponibles

Que existan /v1/chat/completions y /v1/messages sobre el mismo servidor es lo que permite que Claude Code y una biblioteca de OpenAI trabajen contra el mismo modelo cargado sin duplicar memoria. Los dos endpoints entran al mismo grupo de motores.

/v1/rerank y /v1/embeddings son los que convierten esto en algo utilizable para búsqueda semántica. Con un modelo de embeddings y un reordenador cargados, tienes las dos mitades de una tubería de recuperación sin salir del Mac. Si vienes de montar esto con otras herramientas, la comparación con las optimizaciones de llama.cpp es instructiva.

La clave de API y las subclaves

oMLX distingue tres credenciales, y la diferencia importa más de lo que parece:

  • Clave principal. Da acceso a los endpoints de inferencia y también al panel de administración. Es la que fijas al arrancar.
  • Subclaves. Sirven solo para llamar a la API. No permiten entrar al panel ni cambiar ajustes. Son las que reparte a las aplicaciones que consumen el servidor.
  • Tokens de sesión. Los genera el panel tras iniciar sesión con la clave principal. Viven en la cookie omlx_admin_session, firmada con itsdangerous.URLSafeTimedSerializer. Duran 24 horas, o 30 días si marcas la casilla de recordar.

La forma más directa de fijar la clave principal es al arrancar el servidor:

omlx serve --model-dir ~/models --api-key tu-clave-secreta

La validación es deliberadamente laxa: mínimo cuatro caracteres, sin espacios y solo caracteres imprimibles. Eso significa que el servidor aceptará 1234 sin protestar. La comprobación se hace con secrets.compare_digest, es decir, en tiempo constante, para que no se pueda deducir la clave midiendo cuánto tarda en rechazarla.

Un detalle que agradece cualquiera que haya perseguido una fuga de credenciales: en los registros la clave aparece como una huella SHA-256 truncada, nunca en claro.

Restablecer o rotar la clave

No hay una orden dedicada. La clave vive en la configuración, así que se cambia por los mismos tres caminos que cualquier otro ajuste: desde los ajustes globales del panel, editando ~/.omlx/settings.json, o rearrancando con otra --api-key. Rotar la principal invalida las sesiones abiertas del panel; rotar una subclave solo afecta a la aplicación que la usaba.

Si has perdido la clave y no puedes entrar al panel, la salida es detener el servicio, editar el fichero de configuración a mano y volver a arrancar.

Cuando no quieres clave

En una máquina de escritorio en la que el servidor solo escucha en 127.0.0.1, exigir clave añade fricción sin ganar seguridad real. Los ajustes globales del panel permiten omitir la verificación para conexiones locales. Es razonable mientras host siga siendo 127.0.0.1.

En el momento en que cambies host a 0.0.0.0 para llegar desde otro equipo, esa decisión se invierte: el servidor pasa a ser alcanzable desde la red y una clave deja de ser opcional. Y como los orígenes de CORS vienen por defecto en ["*"], cualquier página web abierta en un navegador de esa red podría hablarle. Ajusta las dos cosas juntas o no ajustes ninguna.

Cómo se envía la clave

Las dos cabeceras son equivalentes para el servidor:

curl http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer tu-clave-secreta"

curl http://127.0.0.1:8000/v1/models \
  -H "x-api-key: tu-clave-secreta"

La segunda existe porque el SDK de Anthropic envía x-api-key y no Authorization. Si vas a hablarle con una biblioteca de OpenAI, usa la primera y no tendrás que tocar nada.

Una llamada de chat completa, para comprobar que el modelo responde:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tu-clave-secreta" \
  -d '{
    "model": "qwen3-8b",
    "messages": [{"role": "user", "content": "Responde en una frase: que es MLX?"}],
    "max_tokens": 128,
    "stream": false
  }'

El campo model acepta tanto el nombre del directorio del modelo como el alias que le hayas puesto en el panel. /v1/models devuelve el alias, así que si el catálogo te enseña un nombre y las peticiones fallan con otro, es que estás mezclando ambos.

El puerto por defecto y cómo cambiarlo

El puerto es el 8000 y hay tres formas de cambiarlo, que se pisan en un orden concreto:

omlx serve --model-dir ~/models --port 8080

OMLX_PORT=8080 omlx serve --model-dir ~/models

O de forma permanente, en ~/.omlx/settings.json:

{
  "host": "127.0.0.1",
  "port": 8080,
  "log_level": "info",
  "cors_origins": ["*"],
  "max_concurrent_requests": 8
}

El fichero es el que importa si gobiernas oMLX como servicio de Homebrew, porque ese servicio ejecuta omlx serve sin argumentos: las banderas no llegan nunca. Lo cuento con más detalle en la guía de instalación con Homebrew.

El orden de precedencia

Cuatro capas, de más fuerte a más débil:

  1. Los argumentos de la orden (--port, --api-key, --model-dir).
  2. Las variables de entorno OMLX_* (OMLX_PORT, OMLX_MODEL_DIR, OMLX_BASE_PATH, OMLX_SECRET_KEY).
  3. El fichero ~/.omlx/settings.json.
  4. Los valores por defecto del código.

Esto explica el fallo más común al cambiar de puerto: editas el fichero, reinicias y el servidor sigue en el 8000 porque hay una bandera o una variable de entorno por encima. Comprueba con brew services info omlx con qué argumentos arrancó realmente.

OMLX_SECRET_KEY merece una nota aparte. Si no la defines, el servidor genera un valor aleatorio en cada arranque, lo que invalida todas las sesiones del panel cada vez que lo reinicias. Fijarla en el entorno del servicio es lo que hace que no tengas que volver a iniciar sesión después de cada actualización.

Preguntas frecuentes

¿Necesito una clave de API para usar oMLX en mi propio equipo?

No. Si el servidor escucha solo en 127.0.0.1, los ajustes globales del panel permiten omitir la verificación de clave para conexiones locales. Fija una clave en cuanto expongas el servidor a la red cambiando host, porque los orígenes de CORS vienen abiertos por defecto.

¿Qué diferencia hay entre la clave principal y una subclave?

La principal abre los endpoints de inferencia y además permite entrar al panel de administración y cambiar ajustes. Una subclave solo sirve para llamar a la API. Reparte subclaves a las aplicaciones y guarda la principal para ti.

¿Por qué mi cliente de Anthropic no autentica contra oMLX?

Casi siempre porque envía la clave en x-api-key y esperas que llegue en Authorization, o al revés. oMLX admite las dos, así que si falla revisa antes la dirección base: Claude Code necesita ANTHROPIC_BASE_URL apuntando a tu servidor y ANTHROPIC_AUTH_TOKEN con la clave.

Conclusión

La API de oMLX es deliberadamente aburrida, y eso es lo mejor que se puede decir de ella. No hay formato propio que aprender: si tu código ya habla con OpenAI o con Anthropic, cambiar la dirección base y la clave basta. Las decisiones que sí hay que tomar son dos, y van juntas: si el servidor escucha fuera de 127.0.0.1 y si exiges clave. Cambiar la primera sin cambiar la segunda es el único error de configuración que puede dolerte.

El siguiente paso natural es el panel de administración, donde se cargan los modelos y se ajusta cada uno: lo cubro en el panel y la línea de comandos de oMLX. La versión inglesa de este artículo está en The oMLX API key, port and endpoints.

Fuentes

  1. jundot/omlx, repositorio y documentación oficiales
  2. DeepWiki: autenticación y seguridad de oMLX
  3. Referencia de la API de chat de OpenAI
  4. Messages API de Anthropic
  5. Especificación de Model Context Protocol
  6. MLX, el framework de Apple sobre el que corre oMLX