Magpie

Magpie 支持通过供应商配置接入第三方 API。SoleAPI 当前在 API Key 管理页提供 Magpie 快捷导入入口，也保留手动配置的扩展位置。

准备工作

开始前请确认：

• 已安装可用的 Magpie 客户端；
• 已在 SoleAPI 控制台创建 API Key；
• 目标 API Key 处于可用状态；
• API Key 的调度分组包含你准备调用的模型。

第 1 步：从 API Key 页面快捷导入

入口 A：创建 API Key 成功后的弹窗

创建 API Key 成功后，在成功弹窗中点击「导入 Magpie」。

入口 B：已有 API Key 卡片

在 API Key 管理页面找到目标 Key 卡片，确认名称、可用状态和调度分组后，点击「导入 Magpie」。

第 2 步：在统一导入弹窗中确认配置

无论从成功弹窗还是 API Key 卡片点击「导入 Magpie」，都会先进入 SoleAPI 网页内的「导入到 Magpie」弹窗此时还没有向 Magpie 提交配置。

这个窗口与 CC Switch 的流程不同：它将当前 Key 整体作为一个供应商导入，供 Magpie 中的各个 Agent 选用模型；不需要在网页中先选一个目标工具，也没有单独选择默认模型的步骤。

1. 核对 Key 和供应商名称

先检查顶部的 Key 名称、调度分组和密钥末四位，确认是要导入的那把 Key。完整密钥由导入流程带入，无需在这个表单中手动粘贴。

在「确认导入」中的「供应商名称」输入框，默认值形如 SoleAPI · Key名称。可以保留默认名称，也可以改为容易辨认的名称；导入后用这个名称在 Magpie 供应商列表中查找。

2. 选择接入地址，核对三类协议地址

展开「接入地址」下拉框，选择需要使用的线路。当前提供「API 端点 · https://soleapi.com」和「API 端点2 · https://api.soleapi.com」，实际以页面选项为准。

下方会同时展示三类协议的地址。选择默认线路时：

切换线路后，这三项地址的域名会一起自动更新。它们是自动生成的预览，不需要逐项填写，也不是让你从中只选一种协议。 旁边的复制按钮仅用于复制对应地址，不会提交导入。展示三类地址也不表示每个模型都可从任意协议调用，具体仍以平台可用入口为准。

3. 检查「可用模型」预览

继续向下查看「可用模型（N）」，其中会列出本次导入的模型 ID。此处是模型列表预览，不是单选默认模型；数量和条目以当前 Key 和页面结果为准，不要照抄截图中的数字。

如果目标模型没有出现在列表中，先确认选对 Key、调度分组包含目标模型，再检查当前平台是否有可用入口。不要为了补一项模型而反复导入同一把 Key。

模型列表本身较长时可以在列表内滚动查看更多条目；若要找到最终操作按钮，则继续向下滚动，直到出现底部提示和按钮。

4. 核对后再点击右下角「导入到 Magpie」

提交前检查 Key、供应商名称、接入线路和可用模型是否正确。窗口底部会提示：Magpie 会先展示将要添加的内容，确认后才保存。

准备好后，点击右下角「导入到 Magpie」，留意浏览器是否提示打开应用。按窗口说明，Magpie 会先展示待添加内容，核对无误后再在客户端内确认保存；网页端填写完成不等于 Magpie 已经保存供应商。不想继续时，可点击网页窗口的「关闭」退出，而不是点击最终导入按钮。

5. 确认导入结果

拉起 Magpie 后，应用会有一个遮罩弹窗展示即将导入的供应商。可再次浏览信息，确认无误后点击右下角添加按钮。

第 3 步：确认 Magpie 中的导入状态

回到 Magpie 的供应商列表，确认 SoleAPI 已添加。若客户端要求手动启用，请选中该供应商并完成启用。

手动配置 Magpie（备选）

如果快捷导入不可用，可以在 Magpie 中手动添加供应商。不同版本的字段名称可能不同，以下结构先作为配置框架：

1. 打开 Magpie 的供应商管理页面，点击【添加供应商】；

2. 选择【自定义供应商】；

3. 填写相关信息；

4. 添加并启用供应商。

第 4 步：启用并验证

保存后确认供应商处于启用状态，再自行添加到Agent中发送一条简单请求进行验证。建议先验证普通文本，再单独验证流式输出、工具调用和其他高级能力。

常见问题

• 点击「导入 Magpie」没有打开弹窗：确认点击的是当前 API Key 卡片或创建成功弹窗中的正确按钮，并检查浏览器是否拦截了页面行为。
• 浏览器没有拉起 Magpie：确认 Magpie 已安装并至少启动过一次；如果客户端使用自定义 Deeplink，还需要确认协议已注册。
• 在导入窗口找不到目标工具或默认模型选择：这是正常的。Magpie 将 Key 作为一个供应商整体导入，网页只展示可用模型预览；具体 Agent 使用哪个模型应在 Magpie 中选择。
• 导入后没有出现 SoleAPI：确认已经点击网页右下角「导入到 Magpie」，并在 Magpie 的待添加内容预览中确认保存；按填写的「供应商名称」查找，不一定只叫 SoleAPI。
• 「可用模型」中没有目标模型：核对顶部 Key 和调度分组，检查该 Key 当前是否有目标模型的可用入口，不需要在网页中重新手填一遍模型 ID。
• 重新导入会不会重复添加：同一把 Key 再次导入会替换原有配置；重新导入前先确认是否需要保留客户端中已经做过的修改。
• 返回 401：检查 API Key 是否完整、已停用或已过期。
• 返回 403：检查 API Key 的模型分组权限和 IP 白名单。
• 普通文本成功但高级功能失败：先确认基础协议可用，再单独检查流式、工具调用、思考或其他扩展能力是否被目标模型支持。