登录
文档导航
开始使用

文档中心

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

本页目录
  1. 按目标选择入口
  2. 先认识调用链路
  3. 三个地址怎么用
  4. 十分钟完成第一次调用
  5. 按协议继续阅读
  6. 上线前检查

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

只想安装 Codex 或 Claude Code：直接使用「一键安装 AI Coding 工具」。准备自己写代码或配置第三方客户端：从本页继续。

按目标选择入口

你的目标 建议先读 完成标准
第一次调用 API 核心概念 -> 获取 API Key /v1/models 和最小文本请求均返回 200
使用 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 不盲目重试。
  • 使用日志能够关联模型、时间、分组、用量和请求标识。

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