文档 · 接入指南

Cherry Studio 接入 TopxAI：首次对话与端点设置

2026-09-19

按密钥路由选择模型，区分 Cherry Studio 各版本的地址设置，排查首次调用。

先选一个模型，并创建包含该模型的路由密钥。例如，使用 Claude 路由密钥调用 claude-sonnet-5-5。OpenAI 兼容接口不代表一把密钥能调用所有模型。

按版本选择端点地址

旧版 Cherry Studio 使用单个 API 地址 字段并补充版本路径；当前 v2 源码按端点分别保存基础地址。应以安装版本的字段和最终请求路径为准。

端点	v2 端点配置的基础地址	示例模型
OpenAI Chat Completions	`https://ai.topxea.com/v1`	Claude 密钥的 `claude-sonnet-5-5`；GPT 密钥的 `gpt-6.1-sol`
OpenAI Responses	`https://ai.topxea.com/v1`	对应路由的 `gpt-6.1-sol`、`grok-4.7`
Anthropic Messages	`https://ai.topxea.com`	`claude-sonnet-5-5`、`claude-opus-5-5`

最终 POST 路径应分别为 /v1/chat/completions、/v1/responses、/v1/messages。Kimi、GLM 选择 Chat Completions；Jev 使用独立协议，不适用本指南。

如果旧版单个地址字段明确自动补 /v1，从 https://ai.topxea.com 开始。不要将旧版规则套用到 v2 端点字段，也不要笼统认为含 /v1 的地址一定错误。首次配置先不使用高级 # 路径覆盖。

在 设置 → 模型服务 添加自定义服务商 TopxAI，选择 OpenAI 兼容 Chat Completions，或使用 Anthropic 原生 Claude 接口；具体标签可能随版本不同。
填写对应地址，在本地输入 TopxAI 密钥。截图和导出配置中不要包含密钥。
获取模型列表，或手动添加密钥有权调用的模型。模型列表成功只验证发现接口，不代表生成成功。
在新对话中选中该服务商和模型，发送“请用一句话打招呼”。若客户端允许，设置较小的输出上限。会生成文本的连通性检测也会消耗余额。
收到响应后，到 TopxAI 用量核对模型、路由和费用，再增加其他模型。

新账户目前获得 $0.50 欢迎余额，先检查钱包再决定是否充值。密钥自身的额度也需要覆盖预扣。

图像生成需要独立的配置和路由。文本请求成功不代表图像请求已启用。

2026 年 9 月 19 日核对了 Cherry Studio 当前源码的端点解析、基础地址选择和注册表说明。这是经过源码核对的自定义服务商配置，不代表 TopxAI 已成为官方内置预设，也不代表所有桌面版本都完成了端到端实测。

最小对照请求见连接 SDK，错误细节见常见错误。