ZCloudAPI 的控制台、API 根地址和 OpenAI Base URL 分工不同。地址选错通常会表现为 404、重复 /v1、客户端跳转登录，或者请求成功但 ZCloudAPI 使用日志没有记录。

平台统一使用 https://api.zcloudapi.com 作为模型 API 入口，无需再按所在地区切换域名。控制台复制按钮会同时给出 OpenAI / Codex 所需的 https://api.zcloudapi.com/v1、Claude Code 所需的 https://api.zcloudapi.com 和完整 API Key。

地址速查

名称	当前运行时值	用途
控制台 URL	https://console.zcloudapi.com	注册、登录、钱包、API Key、价格和日志
API Origin	https://api.zcloudapi.com	不带 /v1 的网关根地址
OpenAI Base URL	https://api.zcloudapi.com/v1	已带 /v1 的 OpenAI-compatible 地址

它们之间的结构是：

https://api.zcloudapi.com
https://api.zcloudapi.com/v1
https://api.zcloudapi.com/v1/chat/completions

文档中的 https://api.zcloudapi.com/v1 会在页面加载时替换为第二行，不需要再添加 /v1。

按客户端选择

客户端或 SDK	配置值	客户端最终请求路径
OpenAI Python / Node SDK	https://api.zcloudapi.com/v1	自动追加 /chat/completions、/responses 等
Codex 自定义 Provider	https://api.zcloudapi.com/v1	自动追加 /responses
Cursor / Cherry Studio	https://api.zcloudapi.com/v1	通常自动追加 /chat/completions
Anthropic SDK	https://api.zcloudapi.com	自动追加 /v1/messages
Claude Code	https://api.zcloudapi.com	自动追加 /v1/messages
Gemini native	https://api.zcloudapi.com 或客户端要求的 Gemini 根地址	使用 /v1beta/models/...
原始 curl	完整接口 URL	不再自动追加任何路径

客户端版本可能改变配置项含义。最可靠的方法是查看它实际请求的完整 URL，或用同一地址、Key 和模型先完成 curl 测试。

OpenAI-compatible 接口

SDK Base URL 填：

https://api.zcloudapi.com/v1

curl 请求完整接口：

curl "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
  }'

常见完整路径：

API	完整地址
模型列表	https://api.zcloudapi.com/v1/models
Chat Completions	https://api.zcloudapi.com/v1/chat/completions
Responses	https://api.zcloudapi.com/v1/responses
Images	https://api.zcloudapi.com/v1/images/generations
Embeddings	https://api.zcloudapi.com/v1/embeddings

Anthropic Messages 与 Claude Code

直接使用 Anthropic SDK 时，Base URL 填不带 /v1 的 https://api.zcloudapi.com，SDK 会自行追加 /v1/messages。原始 curl 不会自动拼路径，所以完整地址是：

https://api.zcloudapi.com/v1/messages

Claude Code 的 ANTHROPIC_BASE_URL 行为不同，它会自行拼接 /v1/messages，所以必须只填：

export ANTHROPIC_BASE_URL="https://api.zcloudapi.com"

填成 https://api.zcloudapi.com/v1 会产生重复版本路径：

错误: https://api.zcloudapi.com/v1/v1/messages
正确: https://api.zcloudapi.com/v1/messages

完整环境变量见「配置 Claude Code」。

Gemini native 路径

Gemini 原生协议不使用 OpenAI 的 /v1/chat/completions 结构。典型非流式路径是：

https://api.zcloudapi.com/v1beta/models/{model}:generateContent

流式路径通常使用 streamGenerateContent。只有模型详情标注支持 Gemini 原生协议、并且当前 API Key 能看到该模型时，才使用这类路径。

最小结构示例：

curl "https://api.zcloudapi.com/v1beta/models/从模型列表复制的名称:generateContent?key=$ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "只回复 OK"}]}]
  }'

不要把真实 Key 直接写在脚本、截图或工单中。生产服务使用客户端支持的 Header 或 Secret 注入方式，并避免记录带 key 查询参数的完整 URL。

curl、SDK 与配置框的区别

三种场景需要的地址层级不同：

场景	填写到哪一层
curl	完整接口，例如 https://api.zcloudapi.com/v1/chat/completions
SDK 的 base_url / baseURL	API 版本层，例如 https://api.zcloudapi.com/v1
会自行拼 /v1 的客户端	根域名层，例如 https://api.zcloudapi.com

不要把 curl 的完整接口地址直接粘贴到 SDK Base URL。否则 SDK 还会追加自己的路径，形成：

错误: .../chat/completions/chat/completions

不带凭据的连通性检查

先检查 DNS、TLS、重定向和基本耗时，不发送 API Key：

curl -I --connect-timeout 10 --max-time 20 "https://api.zcloudapi.com"

API 根地址可能返回 200、301、302、404 或其他网页状态，这不代表模型调用成功；这一步只确认网络和 TLS 能建立连接。

然后使用自己的受限测试 Key 查询模型列表：

curl -i --connect-timeout 10 --max-time 30 "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

/v1/models 成功说明地址和鉴权基本正确，但仍需用目标协议做一次最小真实请求。

判断 /v1 是否重复或遗漏

现象	可能的实际 URL	修正
404 且路径含 /v1/v1	客户端已拼 /v1，配置又带 /v1	改填 https://api.zcloudapi.com
404 且请求直达 /chat/completions	客户端未拼 /v1，配置也没带	改填 https://api.zcloudapi.com/v1
路径重复 /responses/responses	Base URL 误填了完整接口	Base URL 只保留到 https://api.zcloudapi.com/v1
客户端打开官方登录	Provider 不是自定义兼容模式	选择 Custom / OpenAI Compatible 并重新填地址
请求成功但 ZCloudAPI 无日志	客户端仍在使用其他 Provider	检查当前会话实际选择的 Provider 和 URL

代理和企业网络

• 允许访问 API 域名的 HTTPS 443 端口。
• 代理必须正确处理 HTTPS CONNECT、SSE 长连接和较长请求超时。
• 不要用服务器 IP 替换 HTTPS 域名，证书、路由和 Host 可能不匹配。
• 排障时分别测试直连和代理，记录 DNS、TLS、首字节和总耗时。
• 流式失败但非流式成功时，检查代理是否缓冲或提前关闭 SSE。

地址确认闭环

1. 确定客户端使用 OpenAI、Anthropic 还是 Gemini 协议。
2. 确定配置框需要根地址、版本 Base URL 还是完整接口。
3. 不带凭据检查 https://api.zcloudapi.com 的网络和 TLS。
4. 使用受限 Key 请求 https://api.zcloudapi.com/v1/models。
5. 用目标协议发送最小非流式请求。
6. 在使用日志确认请求到达 ZCloudAPI，模型和时间一致。

仍然失败时，保留实际完整 URL，但将 Key 和查询参数脱敏，再按「错误码与重试」处理。