本服务面向非中国大陆地区 · ZetaAPI.AI 的网站与控制台主要面向非中国大陆市场，注册与开通功能在你当前地区不可用。

API Reference

ZetaAPI 端点、认证、兼容格式、错误码与速率限制。OpenAI 与 Anthropic 双格式透传，无需改 SDK。

更新于 2026-04-17

Base URL

https://api.staging.cosmos-router.com

认证

所有请求需携带 Authorization: Bearer sk-xxxxx：

curl https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}'

Anthropic 格式也支持 x-api-key（与官方一致）：

curl https://api.staging.cosmos-router.com/v1/messages \
  -H "x-api-key: sk-xxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "hi"}]}'

端点概览

端点协议说明
POST /v1/chat/completionsOpenAI对话补全，支持 SSE 流式
POST /v1/completionsOpenAI传统文本补全（旧版模型用）
POST /v1/embeddingsOpenAI向量嵌入
POST /v1/messagesAnthropicClaude 原生格式，支持 prompt cache
GET /v1/modelsOpenAI当前账户可用模型列表
GET /api/v1/key/quotaZetaAPI查询这把 Key 的剩余额度与可用状态

支持的模型族

模型与价格随部署更新，上表仅为代表性示例；完整型号列表与最新价格倍率以 价格页 为准。

流式响应（SSE）

在请求里设置 "stream": true 即可：

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "写一段 Python 快排"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

SSE 返回 data: {...}\n\n 格式，最后以 data: [DONE] 结束。与 OpenAI / Anthropic 官方完全一致。

Prompt Cache

OpenAI 模型

自动缓存，无需额外参数。重复前缀会自动按 cache hit 计费（输入价的 50% 或更低，取决于模型）。

Claude（Anthropic 格式）

需在 system 或 messages 的 block 上显式标注：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "长系统提示...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [...]
}

缓存命中费率为输入价的 10%，与官方一致。详见 Prompt Cache 成本实测。

查询额度

用 Key 本身即可查询它还能花多少钱、以及当前能不能用：

curl https://api.staging.cosmos-router.com/api/v1/key/quota \
  -H "Authorization: Bearer sk-xxxxx"
{
  "success": true,
  "data": {
    "available_usd": 12.5,
    "available_quota": 6250000,
    "usable": true,
    "blockers": [],
    "message": "可用。",
    "account_balance_usd": 12.5,
    "key": {
      "name": "生产环境",
      "unlimited_quota": false,
      "remaining_usd": 50.0,
      "used_usd": 3.2,
      "status": "enabled",
      "expires_at": null
    }
  }
}

该看哪个字段

判断和展示都用 available_usd。 它是「这把 Key 实际还能花多少钱」，已经同时考虑了账户余额和该 Key 的独立额度上限，取两者中较小的那个。

字段含义
available_usd实际还能花的金额（账户余额与 Key 剩余额度取小）
available_quota同一个数的整数形式（500000 = $1），用于精确比较，不受浮点误差影响
account_balance_usd账户钱包余额，所有 Key 共享
key.remaining_usd这把 Key 的独立额度剩余；未设上限时为 null

上面的例子里账户有 $12.5、Key 上限还剩 $50，实际能花的是 $12.5 —— 只看 key.remaining_usd 会高估。

不可用时

usable 为 false 时，blockers 会列出全部原因（不止第一个，避免你修好一个仍然发不出请求）：

blocker含义怎么办
insufficient_account_balance账户余额不足前往控制台充值
key_quota_exhausted这把 Key 的独立额度用尽在控制台调高该 Key 的额度上限
key_expiredKey 已过期调整有效期或新建 Key
key_disabledKey 已被禁用在控制台启用，或改用其它 Key
account_suspended账号被停用联系客服

额度耗尽、已过期、已禁用的 Key 依然能调用本接口查询原因 —— 最需要知道「为什么不能用」的时候正是它不能用的时候。只有 Key 不存在或已删除才返回 401。

限流：每把 Key 120 次/分钟。建议轮询间隔不低于 30 秒。

⚠️ 不要用 /v1/dashboard/billing/subscription 查余额。 那是 OpenAI 兼容的历史端点，hard_limit_usd 表示「已授予额度总量」而非剩余额度，且对未设上限的 Key 返回一个固定占位值；它也不反映账户余额。查余额请用本节的 /api/v1/key/quota。

错误码

HTTPCode说明建议
400invalid_request_error参数错误（缺字段、格式错、模型名错）检查请求体
401authentication_errorKey 无效或已吊销重新生成 Key
402insufficient_quota账户余额不足前往控制台充值；可用 GET /api/v1/key/quota 程序化查询剩余额度
403permission_error该 Key 无权访问该模型检查 Key 限权
404not_found_error模型名拼写错误参考 /v1/models
429rate_limit_error触发速率限制指数退避重试
500internal_error平台内部异常计入服务异常统计，可按规则申请赔付
502 / 503upstream_error上游故障，正在切换渠道客户端可立即重试
504timeout_error上游超时客户端可立即重试

错误响应体格式与 OpenAI 一致：

{
  "error": {
    "type": "invalid_request_error",
    "message": "model 'gpt-4-vision' not found",
    "code": null
  }
}

速率限制

故障自动切换

当上游渠道可用率异常下跌，平台会自动将流量切换到备用渠道，绝大多数场景客户端无感知。

SLA 赔付按自然月 + SKU 大类计算；当前为申请制（人工审核核算），申请方式与档位见 服务补偿申请（设计背景：赔付规则作为产品）。

SDK 支持

更多