API de oMLX: endpoints, clave, puerto y códigos de error

La API de oMLX imita dos que ya existen, la de OpenAI y la de Anthropic, así que cualquier cliente escrito contra ellas apunta a tu Mac cambiando la dirección base. Esta referencia recoge los endpoints de la versión 0.7.2, cómo se envía la clave, qué significa cada código de error y cómo cambiar el puerto 8000 sin que el servidor siga escuchando en el viejo. Está comprobada contra el código de la etiqueta v0.7.2 y contra un servidor en marcha el 27 de octubre de 2026.

Puntos clave

• El servidor escucha en 127.0.0.1:8000. Con esa dirección no hace falta clave; en cualquier otra, oMLX se niega a arrancar sin ella.
• La clave viaja en Authorization: Bearer o en x-api-key. La segunda existe para el SDK de Anthropic.
• Ocho claves erróneas seguidas desde otro equipo bloquean a ese cliente 30 segundos con un 429; la siguiente tanda, 5 minutos.
• Los errores de las rutas /v1/ llegan en el formato de OpenAI, también los de /v1/messages.
• Los ajustes se resuelven en cascada: banderas de la orden, variables OMLX_*, ~/.omlx/settings.json y valores por defecto.

Qué endpoints expone oMLX 0.7.2

oMLX sirve en el mismo puerto la API de OpenAI, la Messages API de Anthropic y unas rutas propias para gestionar modelos. Esta es la lista de rutas públicas de la 0.7.2, sacada del esquema OpenAPI que el propio servidor publica en /openapi.json:

Que /v1/chat/completions y /v1/messages convivan en el mismo servidor permite que una biblioteca de OpenAI y Claude Code usen el mismo modelo cargado sin duplicar memoria. Las rutas de audio solo aparecen si el paquete mlx-audio está instalado; sin él devuelven 404.

Las rutas /admin/... son del panel de administración y aceptan la clave principal o una sesión del panel, nunca una subclave. El panel y su línea de comandos están en el panel de administración de oMLX.

Cómo se autentica una petición

oMLX comprueba la clave en cada ruta de inferencia salvo que el servidor escuche solo en loopback, es decir, en 127.0.0.1 o ::1. Hay tres credenciales distintas:

• Clave principal: abre la API y el panel de administración. La fijas al arrancar o en los ajustes globales.
• Subclaves: solo sirven para llamar a la API. Repártelas entre las aplicaciones y guarda la principal para ti.
• Sesión del panel: una cookie firmada que dura 24 horas, o 30 días si marcas la casilla de recordar.

Las dos cabeceras siguientes son equivalentes para el servidor. Usa la primera con bibliotecas de OpenAI y la segunda con el SDK de Anthropic:

curl http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer tu_clave_de_api"

curl http://127.0.0.1:8000/v1/models \
  -H "x-api-key: tu_clave_de_api"

La clave tiene que tener al menos cuatro caracteres ASCII imprimibles y ningún espacio. La comparación se hace en tiempo constante y los registros solo guardan una huella de la clave, nunca la clave en claro.

Cuándo puedes prescindir de la clave

Con el servidor en 127.0.0.1, los ajustes globales permiten saltarse la verificación, y si no hay ninguna clave configurada oMLX tampoco la pide. En cuanto cambias host a 0.0.0.0 o a la IP del Mac, la 0.7.2 cambia de reglas: no arranca sin clave y no deja saltarse la verificación. El mensaje es literal: "An API key is required when binding to a non-loopback host".

Ese candado importa porque los orígenes CORS vienen abiertos (["*"]), así que sin clave cualquier página abierta en un navegador de tu red podría usar el servidor. Existe un ajuste aparte, allow_unauthenticated_inference, que abre solo las rutas de inferencia y deja el panel protegido. Actívalo únicamente en una red en la que confíes.

Restablecer o rotar la clave

No hay una orden dedicada: la clave vive en ~/.omlx/settings.json, en la sección auth. Cámbiala desde los ajustes globales del panel, edítala en el fichero con el servidor parado o arranca con --api-key. La variable OMLX_API_KEY también la fija y gana al fichero.

Si has perdido la clave y no puedes entrar al panel, detén el servidor, borra o cambia auth.api_key en settings.json y vuelve a arrancar. Rotar una subclave solo afecta a la aplicación que la usaba.

Ejemplos con curl: OpenAI y Anthropic

Los dos ejemplos siguientes se ejecutaron contra un servidor oMLX en un Mac con el modelo Qwen3.6-35B-A3B-oQ4e-mtp cargado. Cambia el nombre por uno que devuelva tu /v1/models. Primero, el formato de OpenAI:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tu_clave_de_api" \
  -d '{
    "model": "Qwen3.6-35B-A3B-oQ4e-mtp",
    "messages": [{"role": "user",
                  "content": "Responde en una frase: que es MLX?"}],
    "max_tokens": 200,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

La respuesta trae el texto en choices[0].message.content y, en usage, campos que OpenAI no tiene: time_to_first_token, prompt_tokens_per_second y generation_tokens_per_second. Sirven para medir sin instrumentar el cliente. chat_template_kwargs desactiva el razonamiento en los modelos Qwen que lo admiten.

La misma pregunta por la Messages API de Anthropic:

curl http://127.0.0.1:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: tu_clave_de_api" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "Qwen3.6-35B-A3B-oQ4e-mtp",
    "max_tokens": 1024,
    "messages": [{"role": "user",
                  "content": "Answer in one sentence: what is MLX?"}]
  }'

Con un modelo que razona, el primer bloque de content es de tipo thinking y el texto llega después. En la prueba, con max_tokens a 200, el modelo agotó el presupuesto pensando y la respuesta terminó con "stop_reason": "max_tokens" sin bloque de texto. Deja margen o desactiva el razonamiento en los ajustes del modelo.

/v1/messages/count_tokens acepta el mismo cuerpo sin max_tokens y devuelve el recuento sin generar nada: {"input_tokens": 20} para esa pregunta.

Códigos de error de la API de oMLX

Las rutas que empiezan por /v1/ devuelven los errores en el formato de OpenAI, con message, type, param y code dentro de un objeto error. Este es el 422 real de una petición con max_tokens a 0:

{"error": {
  "message": "body -> max_tokens: Input should be greater than 0",
  "type": "invalid_request_error",
  "param": "max_tokens",
  "code": null}}

Ese formato se aplica también a /v1/messages, así que un cliente de Anthropic que espere {"type": "error"} recibirá la forma de OpenAI. Los códigos que define el servidor de la 0.7.2 son estos:

El 507 y el error de prefill que aparece cuando el contexto no cabe vienen del vigilante de memoria. Qué significa cada uno y cómo medir cuánto contexto cabe está en cómo medir oMLX y su techo de memoria.

Cómo cambiar el puerto 8000

El puerto por defecto es el 8000 y se cambia por cuatro vías que se pisan en un orden fijo. De más fuerte a más débil:

1. Las banderas de la orden: --port, --host, --api-key.
2. Las variables de entorno: OMLX_PORT, OMLX_HOST, OMLX_API_KEY, OMLX_MODEL_DIR.
3. El fichero ~/.omlx/settings.json.
4. Los valores por defecto del código.

Para una prueba puntual, usa una bandera o una variable:

omlx serve --port 8080

OMLX_PORT=8080 omlx serve

Para un cambio permanente, edita el fichero con el servidor parado. Los ajustes de red van dentro de la sección server; un "port" suelto en la raíz del JSON se ignora sin aviso:

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  }
}

El panel también guarda host y port, pero los cambios de red solo se aplican al reiniciar el servidor. La aplicación de la barra de menús lee el puerto de ese mismo fichero y lo pasa como --port al arrancar, así que cámbialo en su pantalla del servidor con el servidor parado.

Si lo instalaste con Homebrew, el servicio ejecuta omlx serve sin argumentos, de modo que el fichero es lo único que cuenta. Reinicia con omlx restart y comprueba el puerto con curl http://127.0.0.1:8080/health. El resto del ciclo del servicio está en la guía de Homebrew para oMLX.

Preguntas frecuentes

¿Cuál es el puerto por defecto de oMLX?

El 8000, en 127.0.0.1. La API queda en http://127.0.0.1:8000/v1 y el panel en http://127.0.0.1:8000/admin. Se cambia con --port, con OMLX_PORT o en la sección server de ~/.omlx/settings.json.

¿Dónde está la clave de API de oMLX?

En ~/.omlx/settings.json, en auth.api_key, o en OMLX_API_KEY si la defines en el entorno. El panel la muestra en los ajustes globales. Si nunca configuraste una y el servidor escucha en 127.0.0.1, no hay clave y no se pide.

¿Por qué oMLX responde "API key required"?

Porque la petición no lleva ni Authorization: Bearer ni x-api-key y el servidor exige clave. Pasa siempre que escucha fuera de loopback, y en loopback si hay clave configurada y la verificación no está desactivada.

¿Qué valor de max_tokens usa oMLX si no lo envío?

El de los ajustes de muestreo, que por defecto es 32.768 tokens; cada modelo puede tener el suyo en el panel. El campo acepta también el alias max_completion_tokens, y un valor de 0 o negativo devuelve 422.

¿Cómo conecto Claude Code a oMLX?

La vía corta es omlx launch claude, que exporta ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN y los modelos por ti. A mano, apunta ANTHROPIC_BASE_URL a http://127.0.0.1:8000 y pon la clave en ANTHROPIC_AUTH_TOKEN. La receta completa está en la guía para instalar oMLX en un M5 Max.

Conclusión

La API de oMLX no tiene un formato propio que aprender: si tu código ya habla con OpenAI o con Anthropic, el cambio se reduce a la dirección base y la clave. La decisión que sí hay que tomar es dónde escucha el servidor, porque la 0.7.2 exige clave en cuanto sale de 127.0.0.1. Y si cambias el puerto en el fichero, hazlo dentro de server.

Todas las guías de oMLX, ordenadas de la instalación a los benchmarks, están en la página de oMLX. La versión inglesa de esta referencia está en the oMLX API reference.

Fuentes: [1] jundot/omlx, código de la etiqueta v0.7.2^[1], [2] Notas de la versión 0.7.2 de oMLX^[2], [3] Referencia de la API de chat de OpenAI^[3], [4] Messages API de Anthropic^[4], [5] Especificación de Model Context Protocol^[5].

Fuentes

1. jundot/omlx, código de la etiqueta v0.7.2
2. Notas de la versión 0.7.2 de oMLX
3. Referencia de la API de chat de OpenAI
4. Messages API de Anthropic
5. Especificación de Model Context Protocol