登录
文档导航
开始使用

获取 API Key

创建、限制、轮换并安全保存自己的 ZCloudAPI API Key。

本页目录
  1. 第一步：进入 API 密钥页面
  2. 第二步：创建一条新 Key
  3. 第三步：复制并识别内容
  4. 第四步：保存到当前终端
  5. 第五步：验证 Key 和模型权限
  6. 第六步：发起最小真实请求
  7. 推荐命名和隔离方式
  8. 如何轮换 Key
  9. 如何处理丢失或泄露
  10. 安全规则
  11. 创建完成检查

API Key 是程序访问 ZCloudAPI 的凭据。每台设备、每个客户端和每个生产服务都建议使用独立 Key，这样可以分别控制权限、额度和停用范围。

第一步：进入 API 密钥页面

  1. 打开 https://console.zcloudapi.com 并登录。
  2. 点击顶部「控制台」。
  3. 在左侧个人菜单中找到「API 密钥」。
  4. 确认当前页面显示的是你自己的 Key 列表，而不是管理员的上游渠道页面。

如果看不到「API 密钥」，先确认账号已经登录，并刷新控制台页面。

第二步：创建一条新 Key

  1. 点击页面右上方的「创建 API 密钥」。
  2. 在名称中写清用途。推荐格式是 设备-工具-环境，例如 macbook-codex-dev、office-cursor 或 server-order-prod。
  3. 如果页面提供过期时间：个人长期设备可以按需要设置；临时测试建议设置较短有效期。
  4. 如果页面提供额度上限：生产服务建议设置可承受的最大损失额度；第一次测试只需保留足够完成几次小请求的额度。
  5. 如果页面提供模型限制：只勾选该客户端需要的模型。Codex 需要 GPT Responses 模型，Claude Code 需要 Claude 模型。
  6. 如果页面提供分组选择：选择与目标模型匹配的分组。不确定时先查询该账号默认分组可见的模型。
  7. 点击确认创建，等待新 Key 出现在列表中。

需要自行决定分组的使用顺序时，先到「自定义 Auto 分组」创建配置，再将 Key 的分组选为 auto 并选择这份配置。选择「官方 Auto」则保留平台默认路由。完整步骤见 自定义 Auto 分组教程。

第三步：复制并识别内容

点击 Key 右侧的主复制按钮，会直接得到一段连接 JSON：

{
  "base_url": "https://api.zcloudapi.com/v1",
  "anthropic_base_url": "https://api.zcloudapi.com",
  "api_key": "sk-你的-ZCloudAPI-Key"
}
  • base_url 给 OpenAI-compatible SDK、Codex、Cursor 等客户端使用，结尾带 /v1。
  • anthropic_base_url 给 Claude Code 和 Anthropic SDK 使用，不能带 /v1，客户端会自行请求 /v1/messages。
  • api_key 是完整 Key。图形安装器只需要填写这一项，不要粘贴整段 JSON。
  • 官网与控制台地址是 https://console.zcloudapi.com，不能当作模型 Base URL。

如果某个客户端只接受纯 Key，可以从 JSON 的 api_key 字段复制，或打开该行菜单选择「复制密钥」。

第四步：保存到当前终端

macOS / Linux：

export ZHICLOUD_BASE_URL="https://api.zcloudapi.com/v1"
export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

Windows PowerShell：

$env:ZHICLOUD_BASE_URL="https://api.zcloudapi.com/v1"
$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

不要把真实 Key 直接写进教程示例或提交到 Git。团队项目应使用 GitHub Actions Secrets、CI Secret、Docker Secret 或云厂商密钥管理服务。

第五步：验证 Key 和模型权限

macOS / Linux：

curl -i "$ZHICLOUD_BASE_URL/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

Windows PowerShell：

curl.exe -i "$env:ZHICLOUD_BASE_URL/models" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY"

按结果处理：

结果 说明与下一步
200 且有 data Key 有效，从 data[].id 选择模型
200 但 data 为空 检查用户分组、Key 的模型限制和模型启用状态
401 Key 不完整、已停用、过期，或者 Header 没有正确发送
403 当前账号或 Key 没有对应分组权限

第六步：发起最小真实请求

将下面的 YOUR_TEXT_MODEL_ID 替换为刚才由本人 Key 查询到、且支持 Chat Completions 的完整文本模型 ID。它是占位符，不是可直接调用的模型名；不要照抄旧教程中已经下线的模型。

curl "$ZHICLOUD_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

成功后打开控制台「使用日志」，确认刚才的请求、模型和用量已经记录。

推荐命名和隔离方式

使用场景 Key 名称示例 推荐限制
个人 Codex macbook-codex 只开放需要的 GPT 模型
Claude Code office-claude 只开放 Claude 模型
Cursor desktop-cursor 设置个人可接受的额度上限
临时测试脚本 dev-script-aug 短有效期、低额度
生产后端 prod-order-agent 独立 Key、明确模型、额度和监控

不要让开发、测试和生产共用同一条 Key。一个环境泄露时，应该能够只停用受影响的 Key。

如何轮换 Key

怀疑泄露或需要定期轮换时，按下面顺序操作，避免直接停用导致业务中断：

  1. 创建一条名称带日期的新 Key。
  2. 用 /v1/models 和最小请求验证新 Key。
  3. 把客户端或服务端 Secret 更新为新 Key。
  4. 重启应用并检查真实请求成功。
  5. 在「使用日志」确认请求已经来自新配置。
  6. 回到 API 密钥页面停用旧 Key。
  7. 观察一段时间，确认没有服务继续使用旧 Key 后再删除。

如何处理丢失或泄露

  1. 立即在 API 密钥列表停用对应 Key。
  2. 检查「使用日志」中是否有异常模型、异常时间或突增用量。
  3. 创建新 Key，并只开放必要模型和额度。
  4. 更新受影响设备或服务的配置。
  5. 如果异常调用仍在继续，联系 support@zcloudapi.com，提供请求时间和日志标识，但不要发送完整 Key。

安全规则

  • 不要在群聊、工单截图或录屏中展示完整 Key。
  • 不要把 Key 写进浏览器前端、移动端安装包或公开仓库。
  • 不要把 Key 放在命令行参数中长期运行，因为系统进程列表可能记录参数。
  • 服务端只从环境变量或 Secret 读取 Key。
  • 每个客户、设备和生产服务使用独立 Key。
  • 给 Key 设置合理的模型范围、额度和有效期。

创建完成检查

  • Key 名称能看出用途和设备。
  • /v1/models 返回目标模型。
  • 最小真实请求返回 200。
  • 使用日志出现对应记录。
  • Key 已保存在安全位置，没有进入源码或公开消息。