Cherry Studio 综合配置 | 青云TOP API 文档

融合 Cherry Studio 基础聊天、MCP、推理模型、图像生成以及 Claude Code、Gemini CLI、OpenCode 工具配置。

本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

只想聊天：先看桌面端的基础配置。
要接入 MCP、知识库或工作流：看 Agent/自动化章节。
要在终端写代码：看 CLI、Provider 和环境变量章节。
遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

Cherry Studio（融合自原文档）

Cherry Studio 教程 — 将桌面 AI 客户端对接青云 TOP API，一键填入 API Key。内置 30+ 专业 AI 助手，覆盖多种工作场景。

聊天设置选项

在青云 TOP API 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 Cherry Studio：

{ "Cherry Studio": "cherrystudio://providers/api-keys?v=1&data={cherryConfig}" }

🍒 Cherry Studio 是一款功能强大的桌面 AI 客户端，专为专业用户设计，集成了 30+ 行业智能助手，能够满足各种工作场景的需求，显著提升工作效率。

青云 TOP API 接入方法

参数填写

提供商类型：青云 TOP API 支持的类型
API 密钥：于青云 TOP API 获取
API 地址：青云 TOP API 站点地址

请使用您自己部署的青云 TOP API，或确认服务方具备合法上游授权和合规义务的青云 TOP API 服务。不要将来源不明的 API 地址或密钥接入生产环境。

图文指引

在青云 TOP API 中复制 API key !复制 API 密钥

添加提供商 !添加供应商

添加模型 !添加模型

返回聊天页面 !切换聊天页面

切换青云 TOP API 模型 !切换模型

在 Cherry Studio 中画图

首先添加支持画图的模型 !画图模型

画图 !画图

接入检查

API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode（融合自原文档）

客户端下载地址: https://www.cherry-ai.com/
请保证你是最新版本,老版本不兼容

1、安装后，在设置-模型服务-New api：按下图设置你的密匙、API地址、添加最新模型。
API地址为：https://top.qingyuntop.ai/dashboard/

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 1

2、选择code工具

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 2

3、选择你需要的编程工具以及模型，点击启动，就可以愉快的编程了

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 3

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

Cherry Studio 配置 Banana 生图（4K）（融合自原文档）

客户端下载地址: https://www.cherry-ai.com/
请保证你是最新版本,老版本不兼容

1、安装后，在设置-模型服务-添加：按下图设置模型提供商

2、按下图，设置你的密匙、API地址、添加 gemini-3-pro-image-preview 模型
API地址为：https://top.qingyuntop.ai/dashboard/

3、在对话框中选择gemini-3-pro-image-preview 进行生成图片

4、如果要生成4K图片，请按下图进行设置。

首先，点击添加自定义参数
其次，按图配置以下数据
imageConfig
类型 json
{ "aspectRatio": "9:16", "imageSize":"4K" }
另外，选择非流

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

CherryStudio 配置 o4 推理级别（融合自原文档）

配置额外参数 reasoning\_effort ,o系列模型目前支持的值为 low 、 medium 和 high

然后就可以发起请求啦

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

CherryStudio 调用 Claude MCP（融合自原文档）

1.CherryStudio下载地址 :

https://docs.cherry-ai.com/cherry-studio/download

2.mcp 配置教程

https://docs.cherry-ai.com/advanced-basic/mcp

3.配置中转

4.配置key

_API地址填写： [https://top.qingyuntop.ai/dashboard/](https://top.qingyuntop.ai/dashboard/)_

5.配置模型

6.开启mcp

发送

mcp调用成功

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

CherryStudio 配置教程（融合自原文档）

青云API拥有260+全球最新模型，全网低价，高速稳定。AI接口聚合管理服务介绍
欢迎各大企业高校咨询定制，大额优惠，可开发票！联系客服&企业高校定制

小白用户建议结合CherryStudio等开源工具，不用会代码，通过简单几步即可调用全球顶尖大模型，以下以CherryStudio为例：
首先，下载并安装CherryStudio：https://cherry-ai.com/download
然后，安装完成软件并打开，按照下图一步步进行配置，就可以和各个大模型进行聊天。同时CherryStudio也支持本地知识库和MCP服务器，是AI时代不可或缺的工具。

一、在下图中，设置里添加青云API，选择openai类型

二、下图中

在API密匙栏中：输入您获得的密匙（通常是以sk-开头）
获取密匙方法：API密钥（令牌）获取

在API地址中输入：https://top.qingyuntop.ai/dashboard/
接口地址详细说明API地址（根据不同应用建议依次测试）

之后点击“管理”将弹出模型选择界面
注：如果上方两项设置正确，会自动加载到模型列表。如果没有显示请检查上方两项的设置是否正确。

三、在模型选择界面中添加你要使用的模型，添加完后关闭即可。
注：不同模型的token价格不一样，具体请查看https://top.qingyuntop.ai/dashboard//pricing
在青云API，价格约为官网的十分之一

如果在管理中没有找到你要的模型，请点击“管理”旁的“添加按钮，在模型id中输入模型名称，点击添加模型，即可将此模型添加到你的模型列表了

四、点击软件左上角的聊天图标，进入聊天界面，在中间顶部点击选择你要使用的模型，然后就可以与这个模型对话了。

如果目标模型要求 Responses API，请在客户端选择 OpenAI Responses；是否支持该协议以模型列表和服务端能力为准。

——————————————————
您也可以下载chatbox工具，他支持桌面和手机端，但功能较少。
点击查看ChatBox(推荐使用)使用教程。

还有其他许多开源工具，这些工具的设置方法与CherryStudio基本一致。
点击查看左侧“各种插件/软件使用教程”

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

统一接入检查与故障排查

401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。