OpenAI-compatible API
mirmir serve listens on http://127.0.0.1:8080 by default. The 0.6.2 public
HTTP contract contains:
| Method | Path | Purpose |
|---|---|---|
GET | /health | Liveness, server and private protocol versions. |
GET | /ready | Same body as /health, or 503 until startup model restoration completes. |
GET | /v1/models | Models ready in the shared runtime. |
POST | /v1/chat/completions | Text or single-image chat, JSON or SSE. |
POST | /v1/embeddings | Single or batched text embeddings. |
POST | /v1/rerank | TEI-style document relevance scoring. |
POST | /v1/decide | Manual Laya decisions on CPU or macOS Metal; a MiRMiR extension. |
The dashboard management API under /api/mirmir/v1 is private to the embedded
web application. It is versioned separately and is not an OpenAI client API.
Quick start
mirmir serve
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
Bearer authentication is optional on loopback unless an API key has been
configured. When configured, send it on every /v1 request:
curl http://127.0.0.1:8080/v1/models \
-H "Authorization: Bearer $MIRMIR_HTTP_API_KEY"
Errors
Errors use an OpenAI-style envelope:
{
"error": {
"message": "model is not loaded",
"type": "invalid_request_error",
"param": null,
"code": "not_found"
}
}
| Status | type / code | Meaning |
|---|---|---|
400 | invalid_request_error / invalid_request | Invalid or unsupported request, including a prompt that exceeds the model context or can never fit the K/V cache. |
401 | authentication_error / invalid_api_key | Missing or invalid bearer token. |
404 | invalid_request_error / not_found | Unknown or unloaded model. |
408 | request_error / cancelled | The operation was cancelled. |
409 | invalid_request_error / conflict | Model lifecycle conflict, such as a model that is loading or in use. |
422 | model_output_error / invalid_model_output | The model produced output that violates the request contract, such as a missing, undeclared, malformed, or truncated tool call. |
429 | rate_limit_error / rate_limit_exceeded | The request fits the model but not the currently available memory or vision resources; retry later. |
503 | server_error / service_unavailable | The runtime is not ready, for example while restoring models at startup. |
500 | server_error / runtime_error | Unexpected runtime failure. |
/v1/chat/completions, /v1/embeddings, and /v1/rerank return 503 until
startup restoration finishes. Use GET /ready as a readiness probe and
GET /health as a liveness probe.