登录
文档导航
开始使用

文档中心

按使用目标找到最短接入路径，并完成第一次调用。

文档更新:

本页目录
  1. 服务说明与支持
  2. Claude Code / Codex 接入路径
  3. 按目标选择入口
  4. 先认识调用链路
  5. 三个地址怎么用
  6. 十分钟完成第一次调用
  7. 按协议继续阅读
  8. 上线前检查
  9. 文档分工与下一步

ZCloudAPI 文档按实际任务组织。第一次使用时，先确定你要接入的工具或协议，再沿对应路径完成 API Key、模型查询、最小请求和用量核对。

只想接入 Codex 或 Claude Code：先选下面的手动配置教程；图形安装器的系统与安全检查限制见「ZCloud Setup 安装与配置」。准备自己写代码或配置第三方客户端：从本页继续。

服务说明与支持

ZCloudAPI 是 AI API 中转与聚合平台，本组文档面向需要接入 Claude Code、Codex CLI 或业务 SDK 的开发者。ZCloudAPI 提供接入与使用说明；各客户端和模型的产品名称归各自厂商所有，本文档不表示官方合作或授权关系。

账号、接入和模型可用性问题可通过联系页面或 support@zcloudapi.com咨询。数据处理范围见隐私政策，使用约定见服务条款。分享排障材料时不要提供完整 Key 或私有请求正文。

页面上的“文档更新”表示内容维护日期。真实调用验证的日期、客户端版本与系统范围在相关教程内另行列明；没有记录的能力或系统不视为已验证。

本文档由 ZCloudAPI 维护。发现说明与实际行为不一致时，可通过上述支持入口反馈页面地址、工具版本和脱敏现象，不需要提供完整 Key。

Claude Code / Codex 接入路径

  1. 选择 Claude Code或 Codex CLI手动教程；不确定时先看 AI 编程入门。
  2. 按接入矩阵确认历史实测版本与未覆盖环境，准备专用 Key 并查询自己的可用模型。
  3. 按教程完成最小请求，检查正文、正常结束和对应使用日志；发生错误时进入排障手册。
  4. 核对模型价格与用量后，再逐步验证自己的代码任务、流式输出和工具调用。

按目标选择入口

你的目标 建议先读 完成标准
第一次调用 API 核心概念 -> 获取 API Key 模型列表可见、最小文本请求返回可用正文并完整结束
使用 Codex 客户端接入矩阵 -> 配置 Codex Codex 返回正文，使用日志出现同一请求
使用 Claude Code 客户端接入矩阵 -> 配置 Claude Code Claude Code 返回正文，使用日志出现同一请求
配置 Cursor 或 Cherry Studio 接入地址选择 -> Cursor / Cherry Studio 客户端与 curl 使用同一模型均成功
接入自己的服务 API 参考 -> Python / Node.js SDK 服务端通过 Secret 注入 Key 并记录请求标识
生成语音或转写录音 语音生成与转写 使用目标模型对应接口并核对返回内容与用量
生成并下载视频 视频生成 任务完成、转存就绪，并成功下载 MP4
核对价格和扣费 计费与分组 能从基础价格和分组倍率解释日志扣费
处理调用失败 错误码与重试 -> 排障手册 能确定错误发生在网络、配置、权限还是上游

先认识调用链路

ZCloudAPI 客户端、网关与模型服务的接入路径
User User Console Console Gateway Gateway Channel Channel Upstream Upstream 创建 API Key 并设置分组、模型、额度 使用 Key 请求模型 API 按模型和分组选择可用渠道 使用匹配协议调用上游 返回内容和用量 返回响应并写入使用日志

这条链路中最容易混淆的是三个地址和六个对象。先阅读「核心概念」，可以避免把控制台地址、API Base URL、分组和模型权限混在一起。

三个地址怎么用

地址 用途 不应该用于
https://console.zcloudapi.com 注册、登录、充值、创建 Key、查看模型价格和使用日志 模型 API 请求
https://api.zcloudapi.com 不带 /v1 的 API 根地址；适合会自行拼接版本路径的客户端 直接作为 OpenAI SDK 的 Base URL
https://api.zcloudapi.com/v1 已包含 /v1 的 OpenAI-compatible Base URL 再手工追加一个 /v1

具体到 Codex、Claude Code、OpenAI SDK 和 Gemini 原生协议的填写方式，见「接入地址选择」。

十分钟完成第一次调用

1. 创建专用 API Key

登录 https://console.zcloudapi.com，进入「控制台 -> API 密钥」，创建一条名称能说明用途的 Key，例如 macbook-api-test。测试 Key 建议限制模型、额度和有效期。

把纯 Key 值放入当前终端：

export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

Windows PowerShell：

$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

完整的创建、限制和轮换方法见「获取 API Key」。

2. 查询这条 Key 的真实模型权限

curl -i "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

成功时从 data[].id 复制一个模型名。不要只根据模型广场或教程示例猜测权限；模型广场展示公开目录，/v1/models 才表示当前 Key 此刻可见的模型。

3. 发送最小非流式请求

将 model 替换为上一步实际返回的文本模型：

curl -i "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 复制的模型名",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

第一次验证不要加入工具调用、图片、超长上下文或复杂采样参数。检查 HTTP 状态、可用正文和正常结束状态，避免把 200、空输出或截断当作完成，再按业务需要增加参数。

4. 回到控制台核对同一次请求

打开 https://console.zcloudapi.com 的「使用日志」，按刚才的时间查找记录，并核对：

  • 模型名与请求中的 model 一致。
  • 分组与这条 Key 的预期路由一致。
  • 输入、输出和缓存 Token 有合理记录。
  • 扣费与模型基础价格、分组倍率一致。
  • 错误或响应状态与客户端看到的结果一致。

API 返回成功且使用日志也出现记录，才表示地址、Key、模型权限、路由和计费整条链路都已接通。

按协议继续阅读

模型或客户端 常用协议 文档
普通文本、国产模型、兼容桌面客户端 Chat Completions Chat Completions
Codex、GPT Agent、Responses SDK Responses API Responses API
Claude SDK、Claude Code Anthropic Messages Claude Messages
GPT Image、Gemini、Grok 图片模型 Images API 图片生成与编辑
Veo、Kling、MiniMax 视频模型 异步 Videos API 视频生成
其他接口和 Gemini 原生路径 对应原生或兼容协议 API 参考

上线前检查

  • 开发、测试、生产分别使用独立 API Key。
  • Key 只保存在环境变量或 Secret 管理器中，没有进入源码、浏览器前端、截图或公开日志。
  • 模型名来自目标 Key 的 /v1/models，并已完成真实最小请求。
  • 客户端使用正确的 https://api.zcloudapi.com 或 https://api.zcloudapi.com/v1，没有遗漏或重复 /v1。
  • 已阅读目标模型在价格页中的基础价格、分组倍率和计费单位。
  • 对 429 和可恢复 5xx 使用有限退避，对 400、401、403 不盲目重试。
  • 使用日志能够关联模型、时间、分组、用量和请求标识。

完成这些检查后，再逐步增加并发、流式输出、工具调用、多模态输入和生产流量。

文档分工与下一步

需要理解完整链路时，阅读核心概念与模型及可用性；选编程工具可先看 AI 编程入门，了解团队系统集成可看企业工作流。各篇教程的固定入口汇总在本文档中心，避免重复维护近似教程。

需要判断状态页与个人请求结果的关系时，阅读状态页与请求成功验证，分开核对探测、日志、客户端结束和任务产物。