Skip to content

Requests

Interfaces, headers, streaming and the error envelope for api.airuntime.dev.

Updated View as Markdown
For humans

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"
  }
}
  • type is invalid_request_error, rate_limit_error or server_error.
  • 401 responses also set WWW-Authenticate: Bearer.
  • 429 covers 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.

Type to search…

↑↓ navigate↵ selectEsc close