Every call goes to https://api.airuntime.dev with a Workspace API key. The Pool you name decides
which interface can answer.
Interfaces
| Capability | Interface |
|---|---|
text, structured |
POST /v1/responses, POST /v1/chat/completions |
embedding |
POST /v1/embeddings |
image-embedding |
POST /v1/image/embeddings |
transcription |
POST /v1/audio/transcriptions |
speech |
POST /v1/audio/speech |
image |
POST /v1/images/generations |
ocr |
POST /v1/ocr |
privacy-filter |
POST /v1/privacy/filter |
realtime-* |
wss://api.airuntime.dev/v1/realtime?model=YOUR_POOL_SLUG |
| discovery | GET /v1/models |
/v1/responses is the canonical text interface; /v1/chat/completions is the OpenAI-SDK-compatible
shape for existing clients.
Headers
| Header | Required | Meaning |
|---|---|---|
Authorization: Bearer <key> |
yes | The Workspace API key |
X-AIRuntime-Route: <pool slug> |
yes | The Pool that serves the call |
Idempotency-Key: <your key> |
recommended | Retrying with the same value replays the first result instead of double-spending |
Content-Type: application/json |
for JSON bodies | — |
The response carries x-airuntime-request-id. That value identifies the invocation in error bodies,
in the console, and in support threads.
Streaming
OpenAI-compatible interfaces accept stream: true and the upstream event stream is passed through
as text/event-stream. Real-time audio uses the WebSocket interface with the airuntime.voice.v1
subprotocol: configure the session, wait for session.ready, append base64 PCM16 mono 24 kHz audio,
then close the session and wait for session.closed. Do not replay audio automatically on
reconnect.
Errors
Failures use one envelope:
{
"error": {
"message": "The Runtime Route hard budget has insufficient remaining capacity.",
"type": "rate_limit_error",
"param": null,
"code": "quota_hard_budget_exceeded"
}
}typeisinvalid_request_error,rate_limit_errororserver_error.401responses also setWWW-Authenticate: Bearer.429covers both rate limiting (quota_runtime_rate_limit_exceeded) and a Pool whose remaining budget cannot cover the request (quota_hard_budget_exceeded).
Retry a 429 only after the limit resets or the budget changes. Retry a 5xx with the same
Idempotency-Key so a replay cannot be billed twice.