Cherry Studio 接入
适合第一次接触 API 的用户。按顺序做完每一步，每一步都说明了填什么、为什么，卡住时先看文末常见错误。
https://api.reniuniu.win/v1先认识三个词
| 名词 | 通俗解释 | 从哪里获得 |
|---|---|---|
| API Key | 相当于密码，证明“这个请求是你发的”，谁拿到谁就能花你的余额 | 牛API控制台创建，见 API Key 与分组 |
| Base URL | 服务器地址，告诉客户端把请求发到哪里 | 本页直接复制，不用记 |
| 模型 ID | 告诉服务器用哪个模型，必须和控制台显示的一字不差 | 控制台模型列表，见模型与渠道 |
准备工作
- 下载 Cherry Studio：从 Cherry Studio 官网 下载对应系统版本。Windows 和 macOS 界面基本一致，本页步骤两者通用；手机端配置不在本页范围。
- 创建专用 Key：在牛API控制台创建一个只给 Cherry Studio 用的 Key（不要和其他客户端混用）。
- 复制一个模型 ID：在控制台模型列表里选一个模型，复制它的 ID 备用。
第一步：打开模型服务设置
打开 Cherry Studio，进入设置中的“模型服务”（或“服务商管理”）页面。
截图需记录客户端版本、系统与日期，并隐藏完整 Key。
第二步：新增自定义服务商
点击“添加”或“新增服务商”，选择自定义 / OpenAI 类服务商。
不得使用其他服务商的截图。
第三步：填写名称
名称只是给自己看的备注，建议填 牛API，方便以后识别。名称不影响任何功能。
第四步：选择协议类型
- 优先选 OpenAI Responses；
- 如果当前版本没有这个选项，选 OpenAI Compatible（也叫“OpenAI 兼容”）。
两个选项的区别见文末协议对比。选错不会损坏配置，报协议类错误时换另一个再测即可。
第五步：填写 API Key
把第二步准备好的专用 Key 完整粘贴进去。注意三件事：
- 只粘贴 Key 本身，不要手动加
Bearer前缀； - 检查首尾不要多带空格；
- 这一栏通常显示为密码样式，粘贴后建议点“显示”核对一遍。
第六步：填写 Base URL
https://api.reniuniu.win/v1直接复制粘贴即可。只有一种情况例外：界面明确写着“API 根地址，会自动拼接 /v1”时，才填 https://api.reniuniu.win。遇到 404 时，九成是这里重复或遗漏了 /v1，对照拼接规则检查。
第七步：添加模型
服务商保存后，在它的模型列表里手动添加模型：把第三步复制的模型 ID 逐字粘贴进去（区分大小写，不要填模型的展示名称）。
截图中只保留脱敏后的模型 ID 示例。
第八步：保存并完全重启
保存配置后完全退出 Cherry Studio 再打开（不是只关窗口）。这一步能避免旧配置残留导致的认证失败。
第九步：发一条测试消息
新建对话，选择刚添加的模型，发送：
请只回复：牛API连接正常收到预期回复后，回牛API控制台核对这条请求的用量记录。确认无误后再开启流式、联网或工具类功能。
Responses 与 OpenAI Compatible
| 选项 | 常见请求端点 | 适用情况 | 牛API状态 |
|---|---|---|---|
| OpenAI Responses | /v1/responses | 支持 Responses 的 Agent/新式交互 | 待验证 |
| OpenAI Compatible | /v1/chat/completions | 传统聊天兼容接口 | 待按模型验证 |
若 Chat Completions 报请求格式或协议不匹配，可在确认模型支持后切换 Responses 再测试；反向切换同理。切换恢复只说明该组合能运行，不代表全部模型共享同一协议。
常见错误
| 现象 | 检查项 |
|---|---|
| Chat Completions 报错 | 模型是否支持该协议，尝试经矩阵确认的 Responses 组合 |
| 模型不存在 | 模型 ID 拼写、大小写、权限和状态 |
| 401 | Key 是否完整、有效，是否粘贴了多余空格或手动加了 Bearer |
| 402 | 余额、额度或资源状态 |
| 429 | 并发、重试频率，是否多个客户端共用 Key |
| 502 | 记录时间、模型和请求 ID，短请求复现 |
更多场景见常见错误。
保护你的 Key
不要在截图、导出配置或同步服务中暴露完整 API Key；分享截图时只露出前后几位。Key 泄露后立即在控制台删除并重建。