Cherry Studio API完整参考手册（实操版）

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桌面客户端

1. 访问Cherry Studio官方项目地址或官方网站，下载对应操作系统的最新版本客户端（Windows可下载exe安装包，Mac可下载dmg镜像）；
2. 双击安装包，按照引导完成安装（默认安装路径即可，无需手动修改）；
3. 安装完成后，桌面将生成快捷方式，双击启动客户端，进入服务配置环节。

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多平台发布