OpenAI-compatible REST API

Arona exposes an OpenAI-compatible REST surface under /v1/* for LLM chat, embeddings, model listing, health probing and async video generation. Any OpenAI SDK pointed at the base URL works for chat and embeddings; the video endpoints follow OpenAI's task-style submit/poll convention.

All request and response bodies are JSON. Errors use a uniform shape (see Errors); authentication failures at the middleware layer are the one exception and are returned as plain text (see Authentication).

Endpoints at a glance

/api/health, /healthz and /readyz are additional readiness probes (Kubernetes-style aliases of /v1/health).

Authentication

Chat, embeddings and video endpoints authenticate with an API key in the Authorization: Bearer header. API keys are created through the management plane (keys.create, see the JSON-RPC API) and look like arona-<uuid>. They are stored server-side as SHA-256 hashes.

Authorization: Bearer arona-CHANGE_ME

• Missing header → 401 plain text: Missing Authorization header. Use: Bearer <api_key>.
• Invalid or revoked key → 401 plain text: Invalid API key.
• GET /v1/models additionally accepts a JWT access token (issued by `auth.login` / `auth.register`) so the web dashboard can list models with the same token it uses for the RPC plane. For that endpoint the messages are `Missing Authorization header. Use: Bearer <api_key_or_jwt>` and `Invalid API key or JWT`.

Middleware-level rejections are plain-text bodies, not the JSON error shape described in Errors — the JSON shape is produced only once a request reaches a handler.

Every authenticated /v1 request also passes an in-memory per-key rate limiter (default 60 RPM, 60-second window, configurable via ARONA_API_RATE_LIMIT_RPM). Exceeding it returns 429 plain text: Rate limit exceeded. Try again later. Tier-level quota and rate limits are enforced separately and return JSON 429s with a Retry-After header (see 429 and Retry-After).

Managing API keys, projects and their scoping is covered in Authentication & Security.

POST /v1/chat/completions

The core OpenAI-compatible chat endpoint, with streaming support and arona-specific extensions (conversation_id, memory, extra, provider).

Request body

messages entries are { "role": "user" | "assistant" | "system", "content": "..." }. Two extensions are forwarded upstream for multimodal / agent workloads:

• images — attached images for vision requests (an array of `{ "media_type", "data", "position" }` objects; the external backend renders them as OpenAI `image_url` content parts).
• tool_calls — function-call payloads produced by the upstream model, to be echoed back on follow-up turns. The external backend MUST forward these or agent pipelines (e.g. scepter skill chains) lose every tool invocation.

extra merge rules: every extra key is merged into the upstream request payload at the top level, with two hard guarantees — the reserved keys model, messages, stream, temperature, max_tokens and options are never overridden, and neither is any key the gateway itself already set. Non-object extra values are ignored.

tools entries are { "type": "function", "function": { "name", "description"?, "parameters"? } } and are forwarded verbatim.

Non-streaming response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "Qwen/Qwen3-1.7B",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 2, "total_tokens": 14 }
}

• choices[].message may carry tool_calls for function-calling turns.
• The memory state of the request is echoed in the X-Arona-Memory response header: `enabled` | `disabled` | `offline`.

Streaming

Set "stream": true. The response is a text/event-stream SSE stream — one data: line per chunk, each carrying a single JSON ChatChunk:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1720000000,"model":"Qwen/Qwen3-1.7B","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"},"finish_reason":null}]}

• choices[].delta carries content (and tool_calls deltas with `index`/`id`/`type`/`function` for function-calling streams).
• On OpenAI-compatible upstreams the terminal chunk carries a usage field with the real token counts; the gateway records it (falling back to a local tokenizer estimate for upstreams that never report usage, e.g. ollama / ws_engine).
• The stream terminates with data: [DONE].
• A stream error is delivered as a data: event carrying `{"error": {"message": "...", "type": "server_error", "code": "stream_error"}}`; the `[DONE]` event still follows, and usage recording plus assistant persistence are skipped for the failed stream.
• The X-Arona-Memory header is present on the SSE response as well.

Example

curl http://192.0.2.10:8080/v1/chat/completions \
  -H "Authorization: Bearer arona-CHANGE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-1.7B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

POST /v1/embeddings

Response: { "object": "list", "data": [ { "object": "embedding", "embedding": [...], "index": 0 } ], "model": "...", "usage": { "prompt_tokens", "completion_tokens", "total_tokens" } }.

GET /v1/models

Lists the models routable today: every healthy registered backend's model listing, merged with the built-in quick-start models (always advertised, even before a backend is registered): Qwen/Qwen3-0.6B, Qwen/Qwen3-1.7B, HuggingFaceTB/SmolLM2-1.7B-Instruct, google/gemma-3-1b-it, microsoft/Phi-4-mini-instruct, deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B.

{
  "object": "list",
  "data": [
    { "id": "Qwen/Qwen3-0.6B", "object": "model", "owned_by": "huggingface" }
  ]
}

Quick-start models appear with owned_by set to their provider; router models carry the owning backend's name.

Video generation

Task-style video endpoints for video-capable backends (e.g. minimax-cloud, see Backends). Jobs progress asynchronously; poll the status endpoint until done.

POST /v1/video/generations

Success → 200:

{
  "id": "3f2d...-uuid",
  "object": "video.generation",
  "model": "minimax-h3",
  "status": "queued",
  "created_at": 1720000000
}

Errors: 400 missing_fields when model or prompt is absent; 503 video_backend_error / no_backend when no healthy video-capable backend serves the model; 429 quota_error / quota_exceeded when the monthly quota is exhausted.

GET /v1/video/generations/{id}

Returns the task status:

{
  "id": "3f2d...-uuid",
  "object": "video.generation",
  "model": "minimax-h3",
  "status": "running",
  "progress": 40,
  "result": null,
  "error": null,
  "cost": 0.0,
  "created_at": 1720000000
}

• status: queued | running | done | failed | cancelled; progress advances 0–90 while running and reaches 100 on `done`.
• result (on done): `{ "url", "duration_seconds"?, "width"?, "height"?, "format"? }` — `url` points at the generated artifact served by the backend.
• error (on failed / cancelled) and cost are populated when applicable.
• Errors: 400 bad_id for a non-UUID id; 404 no_job when the job does not exist or belongs to another API key.

Video jobs also fan progress out over the RPC SSE sidecar (video.progress / video.done / video.failed, see Events & Notifications).

Errors

Gateway-level errors use one shape (json_error_response):

{
  "error": { "message": "...", "type": "...", "code": "..." }
}

429 and Retry-After

429 responses include a Retry-After header (seconds) so OpenAI-compatible clients back off:

Tiers, quota scoping and usage accounting are described in Billing & Usage.

Usage recording

Every /v1 request records a usage row under the API-key prefix (arona-XX) when it completes (non-streaming chat, streaming chat at the terminal chunk, embeddings, and video jobs on completion with their computed cost). See Billing & Usage for the recording model and how quota is enforced.