Cherry Studio API 调用指南（本地部署版）

Cherry Studio API 调用指南（本地部署版）

Cherry Studio 提供了一个兼容 OpenAI 标准的本地 API 接口。你可以用 requests 或任何 OpenAI 客户端来调用它。调用流程和 OpenAI 几乎一致，只是地址和模型名称不同。

1. 启动和基础信息

• 本地服务地址（默认）：

http://localhost:23333/v1

• 常用接口：

  功能	URL	方法
  获取模型列表	/v1/models	GET
  聊天对话	/v1/chat/completions	POST

• 鉴权方式：
  所有请求都必须带上 Authorization 头：

"Authorization": "Bearer <你的 Cherry Studio API Key>"

2. 获取可用模型

示例代码：

import requests

url = "http://localhost:23333/v1/models"
headers = {
    "Authorization": "Bearer cs-sk-xxxxxx",
    "Content-Type": "application/json"
}

resp = requests.get(url, headers=headers)
print(resp.json())

响应示例：

{
  "object": "list",
  "data": [
    {
      "id": "openrouter:tencent/hunyuan-a13b-instruct:free",
      "object": "model",
      "created": 1720000000,
      "owned_by": "tencent"
    }
  ]
}

这意味着你可以用 "model": "openrouter:tencent/hunyuan-a13b-instruct:free" 来发起对话。

3. 聊天对话调用示例

import requests
import json

url = "http://localhost:23333/v1/chat/completions"
headers = {
    "Authorization": "Bearer cs-sk-xxxxxx",
    "Content-Type": "application/json"
}

payload = {
    "model": "openrouter:tencent/hunyuan-a13b-instruct:free",
    "messages": [
        {"role": "system", "content": "你是一个文本分析助手"},
        {"role": "user", "content": "这款耳机音质很好，就是有点贵"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
}

resp = requests.post(url, headers=headers, json=payload)
print(json.dumps(resp.json(), indent=2, ensure_ascii=False))

响应示例：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1720001234,
  "model": "openrouter:tencent/hunyuan-a13b-instruct:free",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "标准表达：音质出色，但价格偏高。\n评价分类：轻微负面"
      },
      "finish_reason": "stop"
    }
  ]
}

📦 数据结构（Schemas）解释

Cherry Studio 遵循 OpenAI 的标准结构，以下是主要的对象含义：

1. Error

错误响应的标准结构：

{
  "error": {
    "message": "Provider not found",
    "type": "invalid_request_error",
    "code": "provider_not_found"
  }
}

• message: 错误说明
• type: 错误类型（如 invalid_request_error）
• code: 可用于判断错误原因

2. ChatMessage

单条对话消息对象：

{
  "role": "user",            // 可选: system, user, assistant, tool
  "content": "你好",          // 消息内容
  "name": "optional_name",   // 可选：消息来源的名称
  "tool_calls": []           // 可选：工具调用（高级功能）
}

3. ChatCompletionRequest

发送到 /v1/chat/completions 的请求体：

{
  "model": "openrouter:tencent/hunyuan-a13b-instruct:free", // 必填：模型ID
  "messages": [                                             // 必填：消息列表
    {"role": "system", "content": "你是助手"},
    {"role": "user", "content": "推荐一款耳机"}
  ],
  "temperature": 0.7,     // 可选：回答的随机性
  "max_tokens": 512,      // 可选：最大返回字数
  "stream": false,        // 可选：是否流式输出
  "tools": []             // 可选：工具调用扩展
}

4. Model

模型信息对象（来自 /v1/models）：

{
  "id": "openrouter:tencent/hunyuan-a13b-instruct:free",
  "object": "model",
  "created": 1720000000,
  "owned_by": "tencent"
}

5. MCPServer

Cherry Studio 内部 MCP 插件服务器的信息（如果你扩展了 MCP 功能才会用到）：

{
  "id": "mcp-01",
  "name": "商品分析插件",
  "command": "python plugin.py",
  "args": ["--fast"],
  "env": {
    "API_KEY": "xxxx"
  },
  "disabled": false
}

• id: 插件 ID
• name: 插件名称
• command: 启动命令
• args: 启动参数
• env: 环境变量
• disabled: 是否禁用

✅ 常见问题排查

📌 快速调用流程总结

1. 启动 Cherry Studio 并确认本地端口（默认 23333）
2. 使用 /v1/models 获取可用模型 ID
3. 用 /v1/chat/completions 发送消息和参数
4. 解析 choices[0].message.content 获取回复
5. （可选）用正则清洗模型输出再 json.loads 解析

🧭 可选增强方案

• 异常重试机制：在网络波动或 JSON 出错时自动重试 2~3 次
• 批量调用控制：每条消息之间 time.sleep(1) 防止被限流
• 流式输出支持：stream=True 可边生成边处理
• 工具调用：通过 tools 字段接入本地函数或外部 API