Cherry Studio API 调用怎么配置？从 API Key 到首次对话
简答：Cherry Studio API 调用的最短流程是：在设置→模型服务中添加服务商，填写 API Key 和根地址，按服务商文档选择协议，先同步或手动添加模型，再执行连接检测并启用服务商。runapi.cfd 的实际 Base URL、模型 ID 和兼容协议目前未从公开一手资料核实，不能直接套用未经确认的地址；应以当前账户控制台或服务商文档为准。
定义：Cherry Studio API 调用，是在 Cherry Studio 的模型服务设置中配置外部 API 的密钥、根地址、协议和模型，使桌面客户端能够发送对话请求并接收模型响应。
先按这张表配置，别把完整接口路径粘进 Base URL
Cherry Studio 官方文档说明，API Host 通常填写服务商提供的根地址，而不是直接粘贴 /v1/chat/completions 这样的完整请求路径；客户端会根据配置自动补充常见路径。若服务商明确要求特殊路径，再按其文档使用末尾 / 或 # 的规则。可先按下面的最小配置表核对。
| 配置项 | 应填写什么 | 不要怎么填 | 核验方法 |
|---|---|---|---|
| 服务商类型 | 与服务商实际协议一致 | 没有依据就随意选 Anthropic 或 Responses | 查看服务商当前文档 |
| API Key | 服务商签发的密钥或令牌 | 带多余空格、引号或完整 Bearer 前缀 | 重新复制并保存 |
| API Host | 通常是根地址，例如 https://api.example.com | 直接填写完整的 /chat/completions 路径 | 以服务商文档的地址格式为准 |
| 模型 ID | 服务商返回或文档列出的真实模型标识 | 把展示名称猜成模型 ID | 同步模型或手动添加后检测 |
| 启用状态 | 完成检测后打开服务商开关 | 只保存配置但没有启用 | 回到对话页确认模型可选 |
Cherry Studio 官方快速开始流程也是先进入模型服务设置，填写密钥、同步模型、添加聊天模型并启用服务商，随后在对话页选择模型发送消息；收到回复即可证明基础配置成功。参考 Cherry Studio 官方快速开始 和 官方模型服务设置说明。
Cherry Studio 接入 runapi.cfd 的操作步骤
- 先确认服务商资料。准备当前账户可用的 API Key、API Host、协议类型和至少一个模型 ID。runapi.cfd 的公开资料目前不足以核实其具体接口路径、模型名称、是否支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages，因此不要根据搜索结果或他人截图猜参数。
- 打开模型服务设置。在 Cherry Studio 中进入“设置→模型服务”。如果列表中已有对应服务商，优先使用内置项；如果没有，再选择自定义服务商或兼容协议入口。
- 选择协议。只有当服务商文档明确说明协议时才选择对应类型。若明确写的是 OpenAI 兼容接口，通常选择 OpenAI；如果明确提供 Anthropic Messages 或 OpenAI Responses，再选择相应协议。Cherry Studio 文档也说明，自定义服务商可使用 OpenAI 兼容、Anthropic 兼容或 Gemini 兼容协议，但不能把不同协议混用。
- 填写 API Key。粘贴密钥本身即可，不要重复添加
Bearer。密钥不要放进截图、公开仓库、聊天记录或调试日志。若一个服务商支持多个密钥，Cherry Studio 的官方说明支持用英文逗号分隔多个 Key，但是否适合当前服务商仍应结合账户规则使用。 - 填写 API Host。优先填写服务商文档给出的根地址，例如
https://api.example.com。不要自行添加/v1/chat/completions。如果文档明确要求版本路径或非标准路径，才按其要求填写；Cherry Studio 官方文档说明，末尾/和#会影响客户端是否继续拼接请求路径。 - 同步或手动添加模型。点击“同步模型”。如果列表为空，先确认 Key、地址和协议无误；仍无法同步时，使用加号手动填写 Model ID、模型名称和分组名称。Model ID 必须是服务商真实接受的标识，不能只填写宣传名称。
- 执行模型检测并启用。点击“模型检测”或“连接检查”。成功后打开右上角服务商开关，再回到对话页选择刚添加的模型，发送一句短文本，例如“请只回复：连接成功”。Cherry Studio 官方说明指出，检测通常会使用已添加模型列表中的模型，模型列表里若存在错误或不支持的模型，也可能导致检测失败。
本站是独立的接入指南，不是 Cherry Studio 或 runapi.cfd 的官方页面。有关 Cherry Studio 的配置逻辑，以其官方文档为准；有关 runapi.cfd 的密钥、地址、模型和协议，以当前账户页面或服务商文档为准。
先用最小请求判断问题在哪一层
如果 Cherry Studio 中一直失败，可以先把问题拆成“凭证、地址、模型、网络”四层。由于 runapi.cfd 的实际端点未能从公开一手资料核实，下面只提供验证结构，不把占位地址当成可用地址。
占位模板：
curl -X POST "https://YOUR_API_HOST/v1/chat/completions" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"请只回复：连接成功"}]}'
- 将
YOUR_API_HOST替换为服务商文档中的地址；如果文档要求客户端自动拼接路径，不要在 Cherry Studio 的 Host 字段重复填写完整路径。 - 将
YOUR_API_KEY和YOUR_MODEL_ID替换为当前账户实际值，不要把真实密钥提交到脚本仓库。 - 返回正常文本，说明密钥、地址、模型和基本网络链路至少能完成一次请求；再回到 Cherry Studio 检查协议和字段。
- 返回 HTML、网关页面或非 JSON 内容，优先怀疑地址、代理、反向代理路径或协议不匹配，而不是立即重复生成密钥。
如果服务商只支持 Responses 或 Anthropic Messages，上面的 Chat Completions 模板不能作为兼容性证明，必须改用服务商文档对应的请求格式。不要把某个兼容网关的行为归因于 Cherry Studio 或上游模型官方接口。
401、403、404、429 和超时怎么分流
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
| 401 Unauthorized | Key 是否复制完整、是否多了引号或 Bearer、服务商是否启用 | 重新粘贴 Key，确认使用的是当前账户的密钥，再做连接检测 |
| 403 Forbidden | 账户权限、地区或网络策略、协议权限 | 查看服务商返回正文和账户权限，不要仅靠更换模型解决 |
| 404 Not Found | Base URL 层级、版本路径、模型 ID 或协议 | 删除重复的 /v1 或完整接口路径，按服务商文档重填 |
| 429 Too Many Requests | 限流、并发、余额或账户额度 | 查看响应头和账户用量；临时限流时再按服务商要求重试，不要无限自动重试 |
| 模型不存在 | Model ID 拼写、模型是否已启用、协议是否匹配 | 同步模型或手动添加真实 ID，并删除列表中的错误模型 |
| 连接超时或无法连接 | 网络代理、防火墙、DNS、地址协议和端口 | 先用同一地址做最小请求，再检查 Cherry Studio 的代理设置和本机网络 |
Cherry Studio 官方常见问题建议先确认服务商已启用、API 地址正确、默认模型可用，并使用连接检查；企业代理或防火墙环境还需要检查网络代理。参考 Cherry Studio 官方常见问题。
不要把 Cherry Studio API 网关和外部服务商配置混为一谈
“让 Cherry Studio 调用 runapi.cfd”和“让其他程序调用 Cherry Studio”是两件不同的事。
- 外部服务商模式：在 Cherry Studio 的“模型服务”中填写 runapi.cfd 或其他服务商提供的 Key、Host、协议和模型，Cherry Studio 作为客户端向外部 API 发请求。
- Cherry Studio API 网关模式：在“设置→API 网关”启动本机网关，让其他本机程序调用 Cherry Studio 已配置的模型。此时使用的是 Cherry Studio 网关页面显示的 URL 和密钥，不是外部服务商的 Key。
Cherry Studio 官方文档说明，API 网关会把已配置的模型能力通过 OpenAI 和 Anthropic 兼容 HTTP API 提供给本机程序；外部程序通常使用 Authorization: Bearer <API 密钥>。官方还建议先确认网关运行、读取模型列表并发送短文本，且不要在没有访问控制时开放给其他设备。参考 Cherry Studio API 网关文档。
完成配置前的安全检查清单
- 只从当前账户页面或服务商文档复制 API Host、协议和模型 ID。
- 不要把真实 API Key 写入公开代码、截图、Issue、共享日志或命令历史。
- 如果怀疑密钥泄露，立即在服务商后台撤销或重新生成，并同步更新 Cherry Studio 配置。
- 不要因为 401、403 或 429 就反复重试；先保存状态码、响应正文摘要和时间，再判断是认证、权限还是限流。
- 首次接入只发送短文本，确认成功后再测试长上下文、工具调用、图片或 Agent 能力。
- 如果模型列表为空，优先检查协议、地址和模型权限，不要直接把任意模型名称手动填入。
常见问题
Cherry Studio 的 API 地址应该填 Base URL 还是完整接口地址？
通常填服务商提供的根地址，不要直接填完整的 /v1/chat/completions。Cherry Studio 会按协议补充常见路径；只有服务商明确要求特殊路径时，才按其文档填写版本路径或使用末尾 # 的规则。
runapi.cfd 在 Cherry Studio 里应该选择 OpenAI 还是 Anthropic？
目前无法仅凭公开一手资料核实 runapi.cfd 的具体协议，因此不能直接断言。若其当前账户文档明确写 OpenAI 兼容 Chat Completions，就选择 OpenAI；若明确写 Anthropic Messages，再选择 Anthropic，不能凭模型名称猜协议。
模型同步失败，但 API Key 看起来没有问题，怎么办？
依次检查服务商是否启用、API Host 是否为根地址、协议是否匹配、网络代理是否可用，以及账户是否有权访问模型。仍失败时，按服务商文档手动添加真实 Model ID，再执行模型检测。
Cherry Studio 提示 404，最常见的原因是什么？
优先检查地址层级和请求路径是否重复，例如 Host 已包含 /v1，客户端又自动追加 /v1；同时检查模型 ID 和协议。不要直接把完整接口路径粘贴到 API Host 字段。
Cherry Studio API 网关能替代外部 API 服务商吗？
不能直接替代。API 网关只是把 Cherry Studio 已经配置好的模型能力提供给本机程序调用，仍需要至少一个可用的模型服务商和模型。它与在 Cherry Studio 中配置外部 API 是两条不同链路。
相关阅读
- Cherry Studio 身份验证失败：排查 API Key、Host 与模型
- Cherry Studio 403 status code no body：逐项检查地址和代理
- Open WebUI 配置 OpenAI 兼容 API 的方法
- runapi.ai、runapi.cfd 与 API 地址如何核验
参考资料
- Cherry Studio Docs：NewAPI 配置说明
- Cherry Studio Docs：API 网关
- Cherry Studio Docs：常见问题（cherryai.com.cn）
- Cherry Studio Docs：Quick Start（cherryai.com）
- Cherry Studio Docs：Model Service Settings（cherryai.com）
- Cherry Studio Docs：All Providers Quick Reference（cherryai.com）