获取 API Key 与首次调用

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

文档复核：2026-10-18。真实调用证据来自 2026-10-16：Python OpenAI SDK 2.44.0 的 Chat Completions 请求完整返回 OK、finish_reason=stop，并有对应站内使用日志。这是已有受限 Key 的调用验证，不等于在所有系统重新完成新建 Key 全流程；本页的模型占位符必须按本人当前权限替换。

本页负责创建、限制和保存 Key。已有 Key 但不知道地址怎么填，转到接入地址选择；准备配置工具，转到 Codex CLI、Claude Code或 Python / Node.js SDK。

第一步：进入 API 密钥页面

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

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

第二步：创建一条新 Key

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

最小 Chat Completions 请求需要返回可用的回复正文，且正常结束；本页“只回复 OK”的非流式示例应检查 choices 中的消息和 finish_reason。仅有 HTTP 200、空正文、length 截断或错误对象都不能当作完成。如果模型把输出额度用于推理、没有留下可见回复，检查返回状态并适当提高输出上限，或改用支持该最小示例的文本模型。

随后打开控制台「使用日志」，按时间、模型和用量核对同一次请求。有网关 X-Oneapi-Request-Id 时可以辅助关联；不要把其他上游响应 ID 或列表中的展示序号当作同一个标识。

上面的 curl 片段使用 macOS / Linux shell 语法。Windows 用户先完成前面的 PowerShell 模型列表检查，再按 Codex、Claude Code中的 PowerShell 请求或 SDK 示例完成真实调用，不要把多行 Bash 命令原样贴进 PowerShell。

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

如何轮换 Key

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

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

如何处理丢失或泄露

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

安全规则

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

创建完成检查

Key 名称能看出用途和设备。
/v1/models 返回目标模型。
最小真实请求返回可用正文，并按所选协议正常完成，而不只是 200。
使用日志出现对应记录。
Key 已保存在安全位置，没有进入源码或公开消息。

下一步：核对费用或处理失败

先看模型价格与计费及分组，再用自己的使用日志核对费用；不要仅凭 Key 能列出模型推断所有协议都能调用。遇到 401、空列表或模型无权限，按排障手册处理；公共异常可参考 ZCloudAPI 状态页，不需要为排障发送完整 Key。

返回文档中心，按使用目标选择其他接入路径。