开始使用

API 密钥与身份验证

每个请求都需携带 API 密钥。密钥归属于工作区，费用从该工作区余额中扣除；每个密钥都可单独设置预算、可用模型和允许访问的地址。

传递密钥

所有端点均支持以下任一请求头:

请求头

Authorization: Bearer zr_live_your_key_here
# or, as Anthropic's SDKs send it:
x-api-key: zr_live_your_key_here

密钥以 zr_live_ 开头。完整密钥仅在创建时显示一次；我们只保存哈希值，因此任何人（包括我们）都无法再次向你展示。密钥丢了？撤销后重新创建即可。

接入 AI 智能体

智能体（OpenClaw、Hermes、Manus 或你自行开发的智能体）可以获取专属密钥，无需手动复制：智能体先申请授权链接，用户在 zurelay.com 上批准并设置每日限额，随后智能体领取密钥。流程类似于在电视上登录（OAuth 设备授权流程，RFC 8628）。这两次调用都无需密钥。

POST/connect

namestring: 智能体的名称，显示在授权页面上，也用作密钥名称。可选。

申请授权链接

curl -X POST https://api.zurelay.com/connect \
  -H "Content-Type: application/json" \
  -d '{"name": "OpenClaw"}'
{
  "status": "pending",
  "device_code": "zr_dc_…",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://zurelay.com/connect",
  "verification_uri_complete": "https://zurelay.com/connect?code=WDJB-MJHT",
  "expires_in": 900,
  "interval": 2
}

向用户展示 verification_uri_complete 和验证码。用户登录后，核对验证码，选择工作区和每日限额，并在 15 分钟内批准授权。device_code 仅供智能体保管：智能体需要用它领取密钥。

POST/connect/key

device_codestring必填: 来自 POST /connect。
waitseconds: 返回 pending 前等待用户批准的时长，范围为 0 到 25，默认 25.

领取密钥

curl -X POST https://api.zurelay.com/connect/key \
  -H "Content-Type: application/json" \
  -d '{"device_code": "zr_dc_…"}'
{
  "status": "approved",
  "api_key": "zr_live_…",
  "key_name": "OpenClaw",
  "workspace": "Acme",
  "daily_limit_usd": 10,
  "base_url": "https://api.zurelay.com/v1"
}

HTTP	status	含义
202	`pending`	尚未批准。请再次调用；每次调用最多等待 25 秒。
200	`approved`	已返回密钥。批准后 30 分钟内再次请求会返回同一密钥，以便在响应丢失时重试。
403	`denied`	用户已拒绝。
410	`expired`	未在 15 分钟内批准，或领取时间过晚。请重新发起请求。
410	`revoked`	密钥已在 API 密钥页面撤销。
404	`unknown`	没有与此设备码对应的请求。

该密钥是 API 密钥页面中的普通密钥，以智能体命名，并采用用户选择的每日限额。你可以在该页面修改规则，或撤销密钥以断开智能体连接。智能体也会从 zurelay.com/skill.md 读取配置步骤。

保护密钥安全

将密钥保存在密钥管理服务或环境变量中，切勿写入代码或代码仓库。
从服务端调用 Zurelay。放在浏览器或移动应用中的密钥，任何拥有该应用的人都能读取。
为每个应用或环境单独使用一个密钥（例如 production 和 staging），这样撤销某个密钥时不会影响其他密钥。
只授予每个密钥必要的权限：设置预算、可调用的模型和允许的来源地址。参见密钥限额与规则。
如果密钥泄露，请在 API 密钥页面撤销。使用该密钥的请求将在 15 秒内停止。

密钥可设置的限制

Monthly budgetUSD: 每个自然月允许的支出（UTC）。
Daily budgetUSD: 每天允许的支出（UTC）。
Rate limit请求数 / 分钟: 每分钟请求数；超出后返回 429.
Expirydate: 超过该时间后，密钥将失效。
Allowed modelslist: 仅允许调用这些模型；调用其他模型将返回 403.
Allowed IP addresseslist: 仅允许来自这些地址或地址段的请求。
Smart routingsetting: 模型不可用时的处理方式：参见智能路由。

身份验证错误

状态	代码	含义
401	`missing_api_key`	请求中未提供密钥。
401	`invalid_api_key`	密钥不存在或已撤销。
401	`expired_api_key`	密钥已过期。
403	`ip_not_allowed`	此密钥仅允许从其他地址使用。
403	`model_not_allowed`	此密钥无权使用该模型。
402	`insufficient_quota`	工作区余额扣除进行中请求预留的金额后，不足以支付本次请求。

每个对话、图像和视频响应都带有 x-request-id 响应头。联系支持时请提供该响应头，我们就能在几秒内定位请求。

有疑问，或发现内容缺失？联系我们的支持团队，我们会通过邮件回复，通常只需一分钟。