Cherry Studio API完整参考手册（实操版）
Cherry Studio 是一款功能强大的桌面客户端，核心优势在于支持多类大语言模型（LLM）提供商接入，为开发者提供统一的API接口，无需单独适配不同AI服务的接口规范，大幅降低集成成本。Cherry Studio 作为桌面客户端，核心价值是“统一AI服务入口”——开发者通过其提供的标准化API，可快速访问DeepSeek、OpenAI、Anthropic等多家厂商的大语言模型，无需关注不同厂
Cherry Studio API完整参考手册（实操版）
Cherry Studio 是一款功能强大的桌面客户端，核心优势在于支持多类大语言模型（LLM）提供商接入，为开发者提供统一的API接口，无需单独适配不同AI服务的接口规范，大幅降低集成成本。本文基于Cherry Studio最新版本，整合完整API参考、安装配置、实操示例、错误处理及最佳实践，全程贴合开发者实际使用场景，既是入门指南，也是日常开发的实用参考手册。
本文档适配所有支持Cherry Studio的操作系统（Windows、Mac、Linux），所有代码示例可直接复制使用，仅需替换对应密钥及参数，适合各类技术水平的开发者快速上手。
一、概述与核心功能特性
1.1 核心定位
Cherry Studio 作为桌面客户端，核心价值是“统一AI服务入口”——开发者通过其提供的标准化API，可快速访问DeepSeek、OpenAI、Anthropic等多家厂商的大语言模型，无需关注不同厂商接口的差异，实现“一次集成，多模型复用”。
项目地址：https://gitcode.com/GitHub_Trending/ch/cherry-studio，可从该地址获取最新版本客户端及源码。
1.2 核心功能特性（附支持状态）
Cherry Studio 的功能模块按“已支持”“开发中”分类，开发者可根据需求规划集成方案，具体如下表所示：
| 功能模块 | 支持状态 | 详细描述 |
| --- | --- | --- |
| 多LLM提供商集成 | ✅ 已支持 | 提供统一API接口，可接入DeepSeek、OpenAI、Anthropic等主流厂商，无需单独适配 |
| DeepSeek-R1支持 | ✅ 已支持 | 深度集成DeepSeek-R1模型，可直接通过API调用该模型完成对话生成等操作 |
| 对话管理 | ✅ 已支持 | 自动维护多轮对话上下文，无需开发者手动处理会话记忆，提升开发效率 |
| 流式响应 | ✅ 已支持 | 支持实时流式文本生成，可实现“边生成边展示”的交互效果，优化用户体验 |
| 文件处理 | 🔄 开发中 | 后续将支持文档上传、解析与分析功能，目前暂不开放相关API |
| 插件系统 | 🔄 开发中 | 将支持插件扩展，开发者可通过插件新增功能，目前暂不支持自定义插件集成 |
二、快速开始：安装与基础配置（3步上手）
Cherry Studio 的安装与配置流程极简，无需复杂环境依赖，完成以下3步即可启动服务并调用API，适合新手快速入门。
2.1 步骤1：安装Cherry Studio桌面客户端
-
访问Cherry Studio官方项目地址或官方网站，下载对应操作系统的最新版本客户端（Windows可下载exe安装包，Mac可下载dmg镜像）；
-
双击安装包，按照引导完成安装（默认安装路径即可，无需手动修改）；
-
安装完成后，桌面将生成快捷方式，双击启动客户端，进入服务配置环节。
2.2 步骤2：启动服务（核心指令）
启动Cherry Studio服务需通过命令行执行指令，指定端口和API密钥（自定义密钥，用于后续API认证），具体指令如下：
cherry-studio start --port 8080 --api-key your-api-key
参数说明：
-
--port 8080：指定服务运行端口，默认端口为8080，若该端口被占用，可替换为其他空闲端口（如8081、9000）；
-
--api-key your-api-key：自定义API认证密钥，后续调用所有API时需携带该密钥，建议设置复杂密钥，提升安全性；
-
补充：若启动失败，可检查端口是否被占用，或重新安装客户端重试。
2.3 步骤3：基础请求示例（JavaScript）
服务启动后，可通过简单的API请求测试服务可用性，以下是JavaScript语言的基础聊天请求示例，可直接复制使用（替换your-api-key即可）：
// JavaScript示例：调用聊天补全接口
const API_BASE = 'http://localhost:8080/api/v1';
async function chatWithAI(message) {
const response = await fetch(`${API_BASE}/chat/completions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-api-key' // 替换为启动服务时设置的API密钥
},
body: JSON.stringify({
model: 'deepseek-r1', // 指定调用的模型，此处以DeepSeek-R1为例
messages: [{ role: 'user', content: message }], // 对话内容，user表示用户输入
stream: false // 是否开启流式响应，false表示同步响应
})
});
return await response.json(); // 返回AI响应结果
}
// 调用函数测试
chatWithAI('Hello, Cherry Studio!')
.then(result => console.log('AI响应：', result))
.catch(error => console.error('请求失败：', error));
运行说明：将上述代码保存为.js文件，通过node命令运行，若控制台输出AI响应结果，说明服务启动正常，API可正常调用。
三、核心API端点参考（重点必看）
Cherry Studio 提供标准化API端点，所有请求均需携带认证信息，核心支持3类常用端点：聊天补全、模型列表、流式聊天，以下是详细参考（含请求参数、响应结构）。
3.1 通用认证方式
所有API请求都必须在请求头（Header）中包含认证信息，否则将返回401认证失败错误，认证格式如下：
Authorization: Bearer your-api-key
说明：your-api-key 即为启动服务时设置的API密钥，大小写敏感，请勿泄露或误写。
3.2 端点1：聊天补全接口（最常用）
用于调用指定模型生成对话响应，支持多轮对话，适用于大部分聊天、问答类场景。
-
端点地址：POST /api/v1/chat/completions
-
请求方式：POST
-
请求参数（JSON格式，必填参数标注）：
{
"model": "string (必填)", // 模型ID，如deepseek-r1、gpt-4
"messages": [ // 对话历史，必填，支持多轮
{
"role": "system|user|assistant", // 角色，system（系统提示）、user（用户）、assistant（AI）
"content": "string" // 角色对应的内容
}
],
"temperature": 0.7, // 可选，生成多样性，0-1之间，值越大越随机
"max_tokens": 2048, // 可选，最大生成 tokens 数，默认2048
"top_p": 1.0, // 可选，采样阈值，0-1之间，无需修改默认值即可
"stream": false, // 可选，是否开启流式响应，默认false
"provider": "deepseek|openai|anthropic" // 可选，指定模型提供商，默认自动匹配模型所属厂商
}
-
响应结构（JSON格式，成功返回）：
{
"id": "chatcmpl-123", // 对话ID，唯一标识
"object": "chat.completion", // 对象类型，固定值
"created": 1677652288, // 创建时间戳（秒）
"model": "deepseek-r1", // 调用的模型ID
"choices": [ // 响应结果列表，默认返回1个结果
{
"index": 0, // 索引，默认0
"message": {
"role": "assistant", // 角色，固定为assistant
"content": "Hello! How can I help you today?" // AI生成的响应内容
},
"finish_reason": "stop" // 结束原因，stop表示正常结束
}
],
"usage": { // tokens 消耗统计
"prompt_tokens": 9, // 提示词 tokens 数
"completion_tokens": 12, // 生成内容 tokens 数
"total_tokens": 21 // 总 tokens 数
}
}
3.3 端点2：模型列表接口
用于查询当前Cherry Studio支持的所有模型列表，可快速获取模型ID、所属厂商等信息，方便开发者选择合适的模型。
-
端点地址：GET /api/v1/models
-
请求方式：GET
-
请求参数：无（仅需携带认证头）
-
响应示例（JSON格式）：
{
"object": "list", // 对象类型，固定为list
"data": [
{
"id": "deepseek-r1", // 模型ID，调用时需填写该值
"object": "model", // 子对象类型，固定为model
"created": 1677652288, // 模型添加时间戳
"owned_by": "deepseek", // 模型所属厂商
"permissions": [], // 权限列表，默认空
"root": "deepseek-r1", // 根模型ID，与id一致
"parent": null // 父模型，无父模型则为null
},
{
"id": "gpt-4",
"object": "model",
"created": 1677652288,
"owned_by": "openai",
"permissions": [],
"root": "gpt-4",
"parent": null
}
]
}
3.4 端点3：流式聊天接口
与普通聊天补全接口功能一致，核心区别在于开启流式响应（stream=true），可实现实时返回生成内容，适用于需要即时交互的场景（如在线聊天界面）。
-
端点地址：POST /api/v1/chat/completions（与普通聊天接口一致，通过stream参数区分）
-
请求方式：POST
-
核心差异：请求参数中stream设为true，其他参数与普通聊天接口一致；
-
使用示例（JavaScript）：
async function streamChat(message) {
const response = await fetch(`${API_BASE}/chat/completions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-api-key'
},
body: JSON.stringify({
model: 'deepseek-r1',
messages: [{ role: 'user', content: message }],
stream: true // 开启流式响应
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break; // 流式响应结束，退出循环
const chunk = decoder.decode(value);
const lines = chunk.split('\n'); // 按行解析流式数据
for (const line of lines) {
if (line.startsWith('data: ')) {
const data = line.slice(6); // 截取data: 后面的内容
if (data === '[DONE]') break; // 接收完毕，退出循环
const parsed = JSON.parse(data);
// 打印实时生成的内容（可替换为页面渲染逻辑）
console.log(parsed.choices[0].delta.content || '');
}
}
}
}
// 调用流式聊天函数
streamChat('请详细介绍Cherry Studio的核心功能');
四、配置管理（config.yaml + 环境变量）
Cherry Studio 支持通过配置文件和环境变量两种方式管理服务参数，可根据实际部署需求灵活配置，以下是详细说明。
4.1 配置文件结构（config.yaml）
配置文件位于Cherry Studio安装目录下，名为config.yaml，可手动修改参数，重启服务后生效，核心结构如下（含注释说明）：
# config.yaml 核心配置
api:
port: 8080 # 服务端口，与启动指令中的--port一致，指令优先级高于配置文件
cors_origins: ["http://localhost:3000"] # 允许跨域的地址，前端项目需添加对应地址
rate_limit: 1000 # 接口请求频率限制，每分钟最多1000次请求
providers: # 模型提供商配置，需填写对应厂商的API密钥
deepseek:
api_key: ${DEEPSEEK_API_KEY} # 环境变量引用，也可直接填写密钥字符串
base_url: "https://api.deepseek.com" # DeepSeek接口地址，无需修改
openai:
api_key: ${OPENAI_API_KEY} # OpenAI API密钥，需自行申请
anthropic:
api_key: ${ANTHROPIC_API_KEY} # Anthropic API密钥，需自行申请
logging: # 日志配置
level: "info" # 日志级别，可选info、warn、error、debug
file: "cherry-studio.log" # 日志文件名称，默认存储在安装目录下
4.2 环境变量配置
为避免密钥明文暴露在配置文件中，推荐通过环境变量配置各类密钥，Cherry Studio支持的环境变量如下，可根据需要配置：
| 环境变量名称 | 详细描述 | 默认值 |
| --- | --- | --- |
| CHERRY_API_KEY | Cherry Studio服务认证密钥（启动服务时的--api-key） | 无（必填） |
| DEEPSEEK_API_KEY | DeepSeek模型提供商的API密钥，需自行申请 | 无 |
| OPENAI_API_KEY | OpenAI模型提供商的API密钥，需自行申请 | 无 |
| ANTHROPIC_API_KEY | Anthropic模型提供商的API密钥，需自行申请 | 无 |
| CHERRY_PORT | Cherry Studio服务运行端口，与启动指令--port一致 | 8080 |
| CHERRY_LOG_LEVEL | 日志级别，可选info、warn、error、debug | info |
五、错误处理与故障排除（避坑必看）
开发过程中调用API可能出现各类错误，本节整理了常见错误代码、响应格式及故障排查方法，帮助开发者快速定位并解决问题。
5.1 错误响应格式
所有API错误均返回统一格式的JSON响应，包含错误代码、错误信息和错误类型，便于解析处理：
{
"error": {
"code": "invalid_api_key", // 错误代码，关键定位依据
"message": "Invalid API key provided", // 错误详细信息
"type": "invalid_request_error" // 错误类型
}
}
5.2 常见错误代码及解决方案
| 错误代码 | HTTP状态码 | 错误描述 | 解决方案 |
| --- | --- | --- | --- |
| invalid_api_key | 401 | API密钥无效或未携带 | 1. 检查请求头中Authorization是否携带正确密钥；2. 确认密钥与启动服务时的--api-key一致；3. 检查密钥大小写是否正确 |
| rate_limit_exceeded | 429 | 请求频率超过限制 | 1. 优化代码，减少请求频率；2. 调整config.yaml中的rate_limit参数（需重启服务）；3. 实现请求重试机制，避免集中请求 |
| model_not_found | 404 | 指定的模型不存在 | 1. 调用GET /api/v1/models接口，查询支持的模型ID；2. 确认模型ID填写正确，无拼写错误；3. 检查模型提供商是否已配置API密钥 |
| provider_unavailable | 503 | 模型提供商服务不可用 | 1. 检查对应厂商的API密钥是否有效；2. 访问厂商官网，确认服务是否正常；3. 切换其他可用模型 |
| invalid_parameters | 400 | 请求参数格式错误或缺失必填参数 | 1. 检查请求参数是否完整（如model、messages是否填写）；2. 确认参数格式符合JSON规范；3. 检查参数值是否符合要求（如temperature范围0-1） |
5.3 常见故障排查方法
故障1：服务启动失败
可能原因：端口被占用、客户端安装不完整、命令行指令错误；
解决方案：1. 更换服务端口（--port 8081）；2. 重新安装Cherry Studio客户端；3. 检查指令拼写，确保指令格式正确。
故障2：API请求连接超时
可能原因：服务未启动、网络连接异常、防火墙拦截端口；
解决方案：1. 确认Cherry Studio服务已正常启动；2. 检查本地网络连接，确保可访问localhost；3. 关闭防火墙或开放对应服务端口。
故障3：流式响应无返回
可能原因：stream参数未设为true、模型响应过慢、代码解析逻辑错误；
解决方案：1. 确认请求参数中stream: true；2. 更换响应速度较快的模型（如deepseek-r1）；3. 检查流式解析代码，确保未遗漏data: 前缀的处理。
故障4：日志分析方法
可通过日志文件定位详细错误信息，常用日志操作指令（bash）：
# 查看实时日志（实时监控服务运行状态）
tail -f cherry-studio.log
# 搜索错误日志（定位具体错误原因）
grep "ERROR" cherry-studio.log
# 监控API性能（查看API调用耗时）
grep "API_CALL" cherry-studio.log | awk '{print $NF}'
六、最佳实践（提升开发效率与稳定性）
结合实际开发场景，整理3个核心最佳实践，帮助开发者优化API调用逻辑，提升系统稳定性和开发效率。
6.1 实践1：连接池管理（避免频繁创建连接）
频繁创建和关闭HTTP连接会降低性能，建议使用连接池管理请求连接，以下是Node.js环境的连接池示例：
// 建议使用连接池避免频繁创建连接
const { Pool } = require('pg');
const apiPool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 20, // 最大连接数
idleTimeoutMillis: 30000, // 空闲连接超时时间（30秒）
connectionTimeoutMillis: 2000, // 连接超时时间（2秒）
});
6.2 实践2：请求重试机制（提升接口稳定性）
面对网络波动、服务临时不可用等场景，实现重试机制可提升接口调用成功率，以下是通用重试函数示例：
async function withRetry(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn(); // 执行API请求函数
} catch (error) {
if (i === maxRetries - 1) throw error; // 最后一次重试失败，抛出错误
// 指数退避重试，每次重试间隔翻倍（1秒、2秒、4秒...）
await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
}
}
}
// 使用示例：调用聊天接口并添加重试机制
withRetry(() => chatWithAI('查询今天的天气'))
.then(result => console.log(result))
.catch(error => console.error('最终请求失败：', error));
6.3 实践3：性能监控（实时掌握API运行状态）
添加API调用性能监控，可实时掌握接口响应时间、成功率等指标，便于及时优化，示例如下：
// 添加性能监控
const startTime = Date.now();
try {
const result = await chatWithAI(message);
const duration = Date.now() - startTime; // 计算API调用耗时
console.log(`API调用耗时: ${duration}ms`);
monitor.recordApiCall('success', duration); // 记录成功调用（需自行实现monitor）
} catch (error) {
monitor.recordApiCall('error', Date.now() - startTime); // 记录失败调用
throw error;
}
七、扩展功能：WebSocket实时通信与自定义提供商
7.1 WebSocket实时通信
Cherry Studio 支持WebSocket连接，可实现更高效的实时通信（比流式响应更轻量），适用于实时聊天、消息推送等场景，核心使用示例如下：
// WebSocket连接建立
const ws = new WebSocket('ws://localhost:8080/ws/chat');
ws.onopen = () => {
console.log('WebSocket连接已建立');
// 连接成功后，发送认证信息
ws.send(JSON.stringify({
type: 'auth',
api_key: 'your-api-key'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// 接收AI返回的消息
if (data.type === 'message') {
console.log('收到消息:', data.content);
}
};
// 发送聊天消息
ws.send(JSON.stringify({
type: 'message',
model: 'deepseek-r1',
content: 'Hello, WebSocket!'}
));
WebSocket消息格式（JSON）：
{
"type": "message|error|ping|pong", // 消息类型
"content": "消息内容", // 消息主体
"timestamp": 1677652288, // 时间戳
"message_id": "msg_123" // 消息唯一ID
}
7.2 自定义提供商集成
若需接入Cherry Studio未默认支持的模型提供商，可通过自定义提供商功能实现，核心示例如下（JavaScript）：
// 自定义模型提供商类
class CustomProvider {
constructor(config) {
this.config = config; // 配置信息（如API密钥、接口地址）
}
// 实现聊天补全逻辑
async chatCompletions(params) {
// 自定义调用逻辑（对接第三方模型接口）
return {
id: `chatcmpl-${Date.now()}`,
choices: [{
message: {
role: 'assistant',
content: 'Custom response' // 自定义响应内容
}
}]
};
}
}
// 注册自定义提供商到Cherry Studio
cherryStudio.registerProvider('custom', CustomProvider);
说明：自定义提供商需实现chatCompletions方法，确保返回格式与Cherry Studio标准响应一致，注册后即可通过provider: "custom"调用该提供商的模型。
八、版本历史与技术支持
8.1 版本历史
| 版本号 | 发布日期 | 主要变更 |
| --- | --- | --- |
| v1.0.0 | 2024-01-15 | 初始版本发布，支持基础聊天补全、模型列表接口 |
| v1.1.0 | 2024-02-01 | 新增流式响应支持，优化API响应速度 |
| v1.2.0 | 2024-03-15 | 多提供商集成优化，新增WebSocket实时通信 |
8.2 技术支持
如需技术支持或报告问题，请提供以下信息，以便快速定位并解决问题：
-
Cherry Studio 版本号（可通过客户端关于页面查看）；
-
操作系统和运行环境信息（如Windows 11、Node.js 16.x）；
-
详细的错误日志（可从cherry-studio.log中提取）；
-
问题复现步骤（清晰描述如何操作出现的问题）。
注意：本文档基于Cherry Studio最新版本编写，API接口可能随版本更新而变化。建议定期查看官方项目地址，获取最新文档和版本更新信息。
九、总结
Cherry Studio 的核心价值在于“统一AI接口入口”，通过标准化的API设计，帮助开发者快速集成多厂商大语言模型，无需关注不同厂商接口的差异，大幅降低开发成本。本文档覆盖了从安装配置、API调用、错误处理到最佳实践的全流程内容，所有代码示例可直接复制使用，适合各类开发者快速上手。
随着Cherry Studio的不断更新，后续将支持文件处理、插件系统等更多功能，开发者可持续关注官方动态，充分发挥其在AI集成开发中的优势，提升开发效率和产品体验。
本文由 mdnice 多平台发布
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
8
0- 0
已为社区贡献17条内容
所有评论(0)