登录
文档导航
开始使用

核心概念

理解控制台、API Key、分组、模型、协议和日志之间的关系。

本页目录
  1. 控制台与 API 网关
  2. API Key
  3. 分组
  4. 模型
  5. 渠道与上游
  6. Base URL 与接口路径
  7. 协议
  8. 使用日志
  9. 对象之间的关系
  10. 一次请求的生命周期
  11. 最小验证闭环
  12. 公开页面访问统计

理解下面几个对象后，接入 ZCloudAPI 只剩下三个动作：用 API Key 请求正确的地址、选择有权限的模型、在使用日志核对结果。

控制台与 API 网关

ZCloudAPI 分为管理入口和模型调用入口：

平面 地址 负责内容
控制台 https://console.zcloudapi.com 账号、钱包、API Key、模型价格、使用日志
API 网关 https://api.zcloudapi.com 鉴权、模型路由、协议适配、用量计算、返回响应

浏览器中的控制台会管理账户，但不会替你的 SDK 发模型请求。SDK 和客户端必须连接 API 网关。

API Key

API Key 是一次调用归属于哪个账号、可以使用哪些模型和最多消耗多少额度的凭据。它通常以 sk- 开头，但文档中的示例永远只是占位符：

sk-你的-ZCloudAPI-Key

一条 Key 可以有自己的名称、有效期、额度、模型范围和分组。推荐按“设备或服务 + 环境 + 用途”拆分，例如 order-api-prod、macbook-codex，不要让所有应用共用一条万能 Key。

分组

分组同时影响两件事：

  1. 这条请求可以进入哪些模型路由和渠道。
  2. 基础价格应用什么分组倍率。

因此，同一个模型对不同分组可能有不同可用性和实际价格。分组不是模型名，也不是上游服务商名称；客户端仍然在请求体的 model 字段中填写模型名。

auto 是自动路由入口。它会根据模型和当前路由配置选择实际可用分组，最终以使用日志中记录的实际命中分组和计费结果为准。详细规则见「计费与分组」。

模型

模型名是请求体中 model 的完整字符串，例如 GPT、Claude、Gemini 或国产模型的具体版本。模型名大小写、短横线和版本号都属于标识的一部分。

有两个不同的模型列表：

列表 表示什么
模型广场 平台公开展示的模型、能力和价格目录
GET https://api.zcloudapi.com/v1/models 当前 API Key 在当前分组和限制下真正可见的模型

配置客户端时，以 /v1/models 返回的 data[].id 为准。模型“可见”仍不等于任意协议和参数都支持，第一次使用还要发送对应协议的最小真实请求。

渠道与上游

渠道是网关内部连接模型供应商的路由。普通用户通常不需要选择渠道：网关会根据模型、分组、状态、优先级、权重和重试策略选择可用渠道。

请求失败时，不要把渠道 Key 或上游地址写进客户端。应保留请求时间、模型、分组、状态码和请求标识，由使用日志定位实际命中的渠道。

Base URL 与接口路径

https://api.zcloudapi.com 是 API 根地址，https://api.zcloudapi.com/v1 是在根地址后加入 /v1 的 OpenAI-compatible Base URL。

API 根地址: https://api.zcloudapi.com
OpenAI Base URL: https://api.zcloudapi.com/v1
完整 Chat Completions 地址: https://api.zcloudapi.com/v1/chat/completions

SDK 通常需要 Base URL，curl 通常需要完整接口地址。不同客户端会不会自行追加 /v1 不一致，不能只看配置项名称猜测。完整判断表见「接入地址选择」。

协议

协议决定请求路径、认证 Header、请求体和响应结构。常用协议包括：

协议 常用路径 典型用途
OpenAI Chat Completions /v1/chat/completions 普通文本、兼容客户端、国产模型
OpenAI Responses /v1/responses Codex、Agent、GPT 工具调用
Anthropic Messages /v1/messages Claude SDK、Claude Code
Gemini native /v1beta/models/{model}:generateContent Gemini 原生客户端或 SDK
OpenAI Images /v1/images/generations、/v1/images/edits GPT、Gemini、Grok 图片模型

一个模型出现在 /v1/models 中，不代表它支持表中每一种协议。按模型详情页标注的接口类型或对应教程选择协议。

使用日志

使用日志是一次调用在 ZCloudAPI 内的事实记录，通常可以核对：

  • 请求时间和模型名。
  • 用户分组或实际命中分组。
  • 输入、输出、缓存等用量。
  • 请求耗时、错误状态和请求标识。
  • 按基础价格和分组倍率计算的扣费。

当客户端显示成功但日志中没有请求，最常见的原因是客户端仍在连接另一个 Provider 或错误的 Base URL。当日志中有失败记录时，说明请求已经到达网关，可以继续从权限、模型、余额、渠道和上游排查。

对象之间的关系

Account Account APIKey APIKey Model Model Client Client Protocol Protocol Gateway Gateway Channel Channel Log Log Billing Billing 创建并设置额度、模型和分组 /v1/models 计算可见范围 按客户端选择请求格式 请求发往对应 Base URL 和路径 按模型、分组和健康状态路由 记录实际命中、用量、耗时和状态 按基础价格和分组倍率扣费

可以把它概括为：Key 决定身份和边界，模型决定能力，协议决定格式，分组决定路由与价格，日志证明实际发生了什么。

一次请求的生命周期

  1. 客户端把 API Key、模型名和请求体发到对应接口。
  2. 网关验证 Key 是否有效、过期、停用或超出额度。
  3. 网关检查用户分组、Key 模型限制和模型可用性。
  4. 网关按协议解析请求并选择匹配的可用渠道。
  5. 上游处理请求，网关转换并返回响应。
  6. 网关记录实际模型、分组、渠道、用量、耗时和错误。
  7. 系统根据模型基础价格、实际分组倍率和用量计算扣费。

理解失败发生在哪一步，可以直接缩小排查范围。状态码判断见「错误码与重试」。

最小验证闭环

任何新 Key、新模型或新客户端都按同一闭环验证：

  1. 用该 Key 请求 /v1/models。
  2. 从返回值复制模型名。
  3. 使用目标协议发送最小非流式请求。
  4. 在使用日志核对模型、分组、状态、用量和扣费。
  5. 再把完全相同的地址、Key 和模型配置到客户端或业务服务。

不要同时改变地址、Key、模型、协议和复杂参数。一次只验证一个变量，失败时才能准确定位原因。

公开页面访问统计

公开访问统计启用时，ZCloudAPI 使用运行在自有新加坡服务器上的 Umami，观察首页、公开模型价格和当前已发布文档的匿名访问与站内导航。api 与 console 按域名分别配置站点，不用账户 ID 或共享用户标识跨域拼接访问。现有 Cloudflare 观测与此统计分别看数，不相加，也不据此补出历史访问数据。

处理哪些字段

  • 站点域名、规范的公开页面路径和固定公开标题；不保存查询参数、fragment、UTM、授权 code 或 token。
  • 来源信息：外部来源只保留 origin（协议、域名及必要端口），不保存外部路径和查询；同站来源只保留允许的公开路径，私有前页和空来源均记为空。
  • 服务端 UTC 时间、浏览器/操作系统/设备分类，以及 Umami 按日轮换的匿名会话标识。这些统计不等于实名用户数，跨日用户数和访问次数也有不同口径。

Umami 会处理访问 IP 和 User-Agent，用于匿名标识、设备分类和机器人判断；这不等于“完全不接触 IP”。本次公开访问统计不保留国家、地区或城市，不采精确屏幕分辨率、账户 ID、邮箱、API Key、账户分组、表单内容、聊天或模型请求正文，不启用 identify、任意事件数据、热图或会话回放。访问统计请求不携带业务 Cookie 或 Authorization。

登录、注册、找回密码、OAuth 回调、账户、密钥、钱包、日志、管理页、API、错误页、未审核模型详情和隐私条款页不属于这份采集白名单。访问这些页面时停止公开页面统计，返回公开页面后重新检查是否允许采集。

保存时间和数据去向

本统计服务使用自托管的独立在线统计数据库，访问明细默认保留 180 天。清理任务每小时执行；正常执行时，到期记录最迟约在下一个小时清理周期删除。清理失败会记录并处理，不能据配置值声称已经完成删除。本统计服务不配置访客明细备份；180 天保留适用于在线统计数据库，逻辑删除也不等于对磁盘介质的安全擦除。

上述范围和期限仅针对这份公开页面访问统计，不覆盖或改变业务 API 的调用记录、计费记录、账户安全审计等日志政策。这些记录的用途与保留边界仍以现有隐私条款和业务规则为准。完整条款见「隐私政策」。

如何停止公开访问统计

我们尊重浏览器提供的 Do Not Track（DNT）和 Global Privacy Control（GPC）信号，也尊重当前浏览器已有的 umami.disabled 退出设置。任一信号生效时，不发出新增统计的配置或采集请求。

也可在需要退出的站点域名下，通过浏览器开发者工具控制台执行，然后刷新页面：

localStorage.setItem('umami.disabled', '1')

需要恢复时执行以下命令后刷新：

localStorage.removeItem('umami.disabled')

这一选择保存在当前浏览器的当前站点中，不跨域、跨浏览器或跨设备同步。广告拦截或统计请求失败造成的缺失如实保留，不换成隐藏入口重试。现有教程链接的 noreferrer 不变；被浏览器抑制的跨域来源仍为空，不通过额外用户标识补齐。停止公开访问统计不影响正文、导航、登录、模型调用或依法依约保留的业务记录。