Cursor / Cherry Studio

Cursor、Cherry Studio 和其他桌面客户端通常通过 OpenAI-compatible API 接入 ZCloudAPI。虽然不同版本的菜单名字可能略有变化，但核心都只有三个值：Base URL、API Key 和模型名。

配置前先准备

登录 https://console.zcloudapi.com。
在「API 密钥」创建一条客户端专用 Key，例如 cursor-macbook 或 cherry-windows。
确认账户有可用余额。
查询 /v1/models，复制准备使用的模型名。
先用 curl 完成一次 Chat Completions 请求。

只有基础 API 已经成功，才进入客户端排查。否则你无法判断错误来自客户端设置还是账号权限。

通用填写模板

配置项	填写内容
Provider	`OpenAI Compatible`、`Custom OpenAI` 或类似项
Base URL	`https://api.zcloudapi.com/v1`
API Key	个人控制台创建的 `sk-...` Key
Model	从当前 Key 的 `/v1/models` 结果复制

注意：Base URL 只填到 /v1，不要再添加 /chat/completions，除非客户端明确要求填写完整接口地址。

第一步：在终端验证同一组配置

先把 YOUR_TEXT_MODEL_ID 占位符替换为当前 Key 的 /v1/models 返回结果中支持 Chat Completions 的完整文本模型 ID。

curl "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-你的-ZCloudAPI-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

curl 返回 200 和 OK 后，再把完全相同的地址、Key 和模型填进客户端。目录中可见并不保证当前上游调用成功，还需核对使用日志。

Cursor 一步一步配置

Cursor 的设置入口会随版本变化，常见路径是「Cursor Settings -> Models」或「Settings -> AI」。

打开 Cursor。
点击右上角设置图标，或者按快捷键打开 Settings。
在设置搜索框输入 OpenAI、API Key 或 Base URL。
找到 OpenAI API Key 或自定义 Provider 区域。
如果有 Provider 类型，选择 OpenAI Compatible 或 Custom OpenAI，不要选择只能走官方账号登录的入口。
在 Base URL 填入 https://api.zcloudapi.com/v1。
在 API Key 填入 ZCloudAPI 下游 Key。
打开模型列表，新增从本人 Key 的 /v1/models 返回结果复制的完整模型 ID，不要填入教程占位符。
保存设置。如果页面有「Verify」「Test」或刷新模型按钮，先点击一次。
新建一个空聊天，选择刚才添加的模型。
发送「只回复 OK」。
返回 ZCloudAPI 控制台「使用日志」，确认模型和请求时间一致。

如果 Cursor 把 Base URL 自动拼成重复的 /v1/v1 或 /chat/completions/chat/completions，说明填写层级不对。把地址恢复为 https://api.zcloudapi.com/v1 后重新测试。

Cherry Studio 一步一步配置

打开 Cherry Studio。
点击左下角或侧边栏的「设置」。
进入「模型服务」或「模型提供商」。
点击「添加」或「新增服务商」。
选择 OpenAI-compatible 类型；如果需要名称，可以填写 ZCloudAPI。
API 地址填 https://api.zcloudapi.com/v1。
API Key 填个人控制台创建的 Key。
点击「获取模型」或刷新按钮。
如果模型列表自动出现，只启用准备使用的模型；如果自动获取失败，手动添加 /v1/models 返回的完整模型名。
保存服务商设置。
新建会话，在顶部模型选择器中选择 ZCloudAPI 下的目标模型。
发送「只回复 OK」，然后到控制台使用日志核对。

其他 OpenAI-compatible 客户端

对于其他客户端，先寻找以下任一菜单名称：

Custom Provider
OpenAI Compatible
API Endpoint
Base URL
Custom OpenAI

然后填写：

Base URL: https://api.zcloudapi.com/v1
API Key: sk-你的-ZCloudAPI-Key
Model: 从 /v1/models 复制

如果客户端要求完整接口地址，才填写：

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

如果客户端只允许官方 OpenAI 登录、没有自定义 Base URL，则它不能直接使用 ZCloudAPI OpenAI-compatible 接口。

如何确认客户端真的接入 ZCloudAPI

客户端请求能返回正文。
ZCloudAPI「使用日志」出现同一时间的请求。
日志中的模型与你在客户端选择的模型相同。
暂时停用这条测试 Key 后，客户端请求应返回鉴权错误。
重新启用或换成新 Key 后恢复正常。

第 4 步只适合专门创建的测试 Key，不要停用仍被生产服务使用的 Key。

模型切换流程

重新查询 /v1/models。
在客户端 Provider 设置中添加新模型名。
新建会话并选择新模型。
发送最小测试。
在使用日志核对模型和扣费。
确认稳定后，再删除客户端里的旧模型项。

常见误填

现象	检查内容
`401`	Key 是否完整，前后是否带空格，是否误粘贴整段 JSON
`404`	Base URL 是否缺少或重复 `/v1`，是否错误填写完整接口
模型列表为空	当前 Key 是否有模型权限，客户端是否支持自动获取模型
客户端显示模型但调用失败	用相同模型做 curl 请求，检查余额和模型状态
请求成功但使用日志没有记录	客户端可能仍连接其他 Provider，重新检查 Base URL
企业网络超时	允许访问 `api.zcloudapi.com:443`，检查 VPN 和系统代理
Cursor 只显示官方登录	当前入口不支持自定义地址，寻找 OpenAI-compatible 或 Custom Provider

联系支持时提供的信息

请隐藏完整 Key，只提供：

客户端名称和版本。
使用的 Base URL。
模型名。
完整错误文字和状态码。
请求发生的大概时间和时区。
控制台使用日志是否有对应记录。

发送到 support@zcloudapi.com，不要发送完整 API Key、密码或敏感对话正文。