所有调用都发往 https://api.airuntime.dev,并带上一个 Workspace API Key。你指定的 Pool 决定哪个
接口可以回答。
接口
| 能力 | 接口 |
|---|---|
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 |
| 发现 | GET /v1/models |
/v1/responses 是文本的标准接口;/v1/chat/completions 是给现有 OpenAI SDK 客户端用的兼容形态。
请求头
| 请求头 | 是否必需 | 含义 |
|---|---|---|
Authorization: Bearer <key> |
必需 | Workspace API Key |
X-AIRuntime-Route: <pool slug> |
必需 | 服务这次调用的 Pool |
Idempotency-Key: <your key> |
建议 | 用同一个值重试会重放第一次结果,而不会重复计费 |
Content-Type: application/json |
JSON 请求体必需 | — |
响应头里有 x-airuntime-request-id。这个值同时出现在错误体、控制台和客服沟通里,用来定位同一次调用。
流式
OpenAI 兼容接口接受 stream: true,上游事件流会以 text/event-stream 透传。实时音频走 WebSocket
接口,子协议是 airuntime.voice.v1:先配置会话,等 session.ready,再追加 base64 PCM16、单声道
24 kHz 音频,最后关闭会话并等待 session.closed。重连时不要自动重放音频。
错误
失败统一使用一种格式:
{
"error": {
"message": "The Runtime Route hard budget has insufficient remaining capacity.",
"type": "rate_limit_error",
"param": null,
"code": "quota_hard_budget_exceeded"
}
}type取invalid_request_error、rate_limit_error或server_error。401响应同时会带WWW-Authenticate: Bearer。429同时覆盖限流(quota_runtime_rate_limit_exceeded)和剩余预算不足以覆盖这次请求 (quota_hard_budget_exceeded)。
429 要等限额重置或预算变化后再重试。5xx 重试时请用同一个 Idempotency-Key,这样重放不会被
计费两次。