Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

OpenAI-compatible API

mirmir serve listens on http://127.0.0.1:8080 by default. The 0.6.2 public HTTP contract contains:

MethodPathPurpose
GET/healthLiveness, server and private protocol versions.
GET/readySame body as /health, or 503 until startup model restoration completes.
GET/v1/modelsModels ready in the shared runtime.
POST/v1/chat/completionsText or single-image chat, JSON or SSE.
POST/v1/embeddingsSingle or batched text embeddings.
POST/v1/rerankTEI-style document relevance scoring.
POST/v1/decideManual 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"
  }
}
Statustype / codeMeaning
400invalid_request_error / invalid_requestInvalid or unsupported request, including a prompt that exceeds the model context or can never fit the K/V cache.
401authentication_error / invalid_api_keyMissing or invalid bearer token.
404invalid_request_error / not_foundUnknown or unloaded model.
408request_error / cancelledThe operation was cancelled.
409invalid_request_error / conflictModel lifecycle conflict, such as a model that is loading or in use.
422model_output_error / invalid_model_outputThe model produced output that violates the request contract, such as a missing, undeclared, malformed, or truncated tool call.
429rate_limit_error / rate_limit_exceededThe request fits the model but not the currently available memory or vision resources; retry later.
503server_error / service_unavailableThe runtime is not ready, for example while restoring models at startup.
500server_error / runtime_errorUnexpected 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.