文档客户端配置通用客户端配置

通用客户端配置

根据客户端支持的协议，将通用 AI 客户端接入 SoleAPI。

通用客户端配置

只要客户端支持 Anthropic Messages、OpenAI Responses 或 OpenAI Chat Completions 协议，就可以按照本页接入 SoleAPI。不同客户端的设置名称可能不同，但核心是选择正确的协议，并让客户端将请求发送到对应的入口。当前平台通过 OpenAI Chat Completions 提供的货源较少，已确认支持 OpenAI（GPT）和 xAI（Grok）。

开始前，请在控制台创建一个 API Key，确认该 Key 已包含目标模型所在的分组，再从模型广场复制模型 ID。

协议兼容只表示请求和响应遵循相应的格式，不表示所有模型都支持该协议下的全部功能。普通文本请求能够成功，也不代表工具调用、图片、思考或缓存等扩展功能一定可用。

先确认客户端的字段类型

在客户端的自定义模型、供应商或连接设置中，找到协议类型、Base URL（或 API Endpoint）、API Key 和模型 ID。不同客户端可能要求填写基础地址，也可能要求填写完整请求地址，请先区分这两种字段。

客户端拼接方式Anthropic MessagesOpenAI ResponsesOpenAI Chat Completions
客户端自动拼接 /v1/messageshttps://soleapi.com不适用不适用
客户端自动拼接 /messages、/responses 或 /chat/completionshttps://soleapi.com/v1https://soleapi.com/v1https://soleapi.com/v1
客户端不会再拼接路径，要求完整请求地址https://soleapi.com/v1/messageshttps://soleapi.com/v1/responseshttps://soleapi.com/v1/chat/completions
API KeySoleAPI API KeySoleAPI API KeySoleAPI API Key
模型 ID模型广场中的模型 ID模型广场中的模型 ID模型广场中的模型 ID

基础地址和完整请求地址只能选择一种填写方式。不要把 https://soleapi.com/v1/messages、https://soleapi.com/v1/responses 或 https://soleapi.com/v1/chat/completions 填入会自动追加对应路径的 Base URL 字段，也不要把 https://soleapi.com/v1 填入要求完整请求地址的字段，否则会出现重复 /v1 或重复协议路径。具体以客户端或 provider 的路径拼接规则为准。

方式一：Anthropic Messages

在客户端选择 Anthropic、Anthropic Messages 或同名协议选项：

  • 如果客户端自动拼接 /v1/messages：填写 https://soleapi.com。
  • 如果客户端自动拼接 /messages：填写 https://soleapi.com/v1。
  • 完整请求地址模式：填写 https://soleapi.com/v1/messages。
  • API Key：填写 SoleAPI 控制台创建的 Key。
  • 模型 ID：填写模型广场中的模型 ID。
  • 鉴权方式：如果客户端允许选择，使用 Anthropic API Key 或 x-api-key 对应的选项。

客户端通常会自动发送 x-api-key、anthropic-version 等请求头。API Key 输入框中只填写 Key 本身，不要手动添加 Bearer 前缀。

该配置对应 SoleAPI 的 POST /v1/messages 入口，字段和请求示例请参阅 Messages API。

方式二：OpenAI Responses

在客户端选择 OpenAI Responses、Responses API 或同名协议选项：

  • 如果客户端自动拼接 /responses：填写 https://soleapi.com/v1。
  • 完整请求地址模式：填写 https://soleapi.com/v1/responses。
  • API Key：填写 SoleAPI 控制台创建的 Key。
  • 模型 ID：填写模型广场中的模型 ID。
  • 鉴权方式：如果客户端允许选择，使用 OpenAI Bearer Token 或等效选项。

客户端应自动发送 Authorization: Bearer <API Key> 请求头。API Key 输入框中通常只填写 Key 本身，具体以客户端字段说明为准。

该配置对应 SoleAPI 的 POST /v1/responses 入口，字段和响应示例请参阅 Responses API。

方式三：OpenAI Chat Completions

在客户端选择 OpenAI Chat Completions、OpenAI Compatible 或同名协议选项。部分客户端把它简称为 OpenAI，请确认它实际使用的是 Chat Completions，而不是 Responses：

  • 如果客户端自动拼接 /chat/completions：填写 https://soleapi.com/v1。
  • 如果客户端自动拼接 /v1/chat/completions：填写 https://soleapi.com。
  • 完整请求地址模式：填写 https://soleapi.com/v1/chat/completions。
  • API Key：填写 SoleAPI 控制台创建的 Key。
  • 模型 ID：填写模型广场中的模型 ID。
  • 鉴权方式：选择 OpenAI Bearer Token 或等效选项，由客户端自动发送 Authorization: Bearer <API Key>。

该配置对应 SoleAPI 的 POST /v1/chat/completions 入口。目前本平台已确认有 OpenAI（GPT）和 xAI（Grok）货源；许多国产模型本身也支持该协议，但本平台当前尚未引入它们对应的货源。

按供应商选择协议

不同供应商当前在本平台可用的协议入口不同。请查看 API 兼容协议中的供应商与协议表，根据目标模型当前可用的入口选择客户端协议。

该表是供应商与协议关系的权威说明；本页不重复维护。实际配置时，还应以模型广场显示的模型 ID 和当前 API Key 的可用模型列表为准。

OpenCode 的特别检查

OpenCode 的内置 Anthropic provider 使用 baseURL 作为 /v1 前缀，然后由 provider 拼接 /messages。因此，在 OpenCode 的原生 Anthropic 配置中应使用：

json
{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://soleapi.com/v1"
      }
    }
  }
}

不要仅根据设置界面上的“OpenAI”或“兼容”字样判断协议。若 OpenCode 使用的是 @ai-sdk/openai-compatible，实际请求通常会发往 /v1/chat/completions；这不是 Anthropic Messages。要调用 /v1/messages，应使用 OpenCode 的 Anthropic provider 或其他明确使用 Anthropic Messages 的 provider。

可以从实际请求地址快速判断：

  • 请求发往 /v1/messages：使用的是 Anthropic Messages，接下来检查请求体中的工具和扩展字段。
  • 请求发往 /v1/responses：使用的是 OpenAI Responses，接下来检查客户端是否确实使用了 Responses provider。
  • 请求发往 /v1/chat/completions：使用的是 OpenAI Chat Completions；目前本平台已确认该入口有 GPT 和 Grok 货源，国产模型对应货源尚未引入。
  • 请求发往 /messages：通常是 Base URL 少了 /v1，需要根据客户端的拼接规则补上。

OpenAI Chat Completions 在本平台的当前边界

POST /v1/chat/completions 是历史兼容入口，不应作为新接入的首选。OpenAI（GPT）和 xAI（Grok）当前可使用该入口；许多国产模型本身也支持 Chat Completions，但本平台当前尚未引入这些模型对应的货源，因此暂时没有可用入口。

这不代表国产模型不支持 Chat Completions，也不代表国产模型无法使用。请先在模型广场和 API Key 的可用模型列表中确认该模型当前在本平台可用的入口，再在客户端选择对应协议。当前国产模型可优先使用本平台已有的 Messages 或 Responses 入口。

测试并保存

填写完成后保存配置，先发送一条只包含普通文本的简单请求。确认基础请求成功后，再逐步测试工具调用、流式输出、图片或思考等功能。

建议按照以下顺序排查：

  1. 确认模型 ID 拼写正确，并且该模型属于当前 API Key 可用的分组。
  2. 确认协议类型和地址匹配：Messages 使用 /v1/messages，Responses 使用 /v1/responses，Chat Completions 使用 /v1/chat/completions。
  3. 确认 Base URL 与完整请求地址没有混用。
  4. 先使用一个已知可用模型测试，再切换到目标模型。
  5. 基础文本请求成功后，再单独验证工具调用等高级能力。

为什么同一协议在不同客户端结果不同？

“支持 Anthropic Messages”只说明客户端能够生成 Messages 形状的请求。不同客户端仍可能存在以下差异：

  • 自动拼接的路径不同，导致请求实际发往不同入口，例如 /messages、/v1/messages 和 /v1/chat/completions。
  • 鉴权头、anthropic-version 或其他 anthropic-beta 请求头不同。
  • 编码代理会在每次请求中自动附带工具定义、tool_choice、系统提示词和更长的上下文。
  • 某些客户端会启用提示词缓存、思考参数、图片内容或特定的流式事件。
  • 客户端对工具调用、流式事件和错误响应的解析要求不同。

因此，一个客户端中普通对话能够成功，只能证明该模型至少能承接这一种基础请求；不能证明另一个客户端的完整 Agent 工作流也一定兼容。以 GLM 为例，如果在一个客户端通过 Anthropic Messages 可以返回普通文本，但在另一个编码客户端中失败，优先检查后者是否在请求中加入了工具或其他扩展字段，再判断是否属于模型入口问题。

常见问题

  • 请求返回 404 或提示接口不存在：检查协议和地址是否匹配。Messages 使用 /v1/messages，Responses 使用 /v1/responses，Chat Completions 使用 /v1/chat/completions。
  • 请求路径出现 /v1/v1/messages、/v1/v1/responses、重复 /v1 或重复协议路径：Base URL 已包含版本路径或客户端会自动追加协议路径，改用客户端实际拼接规则对应的基础地址。
  • 返回 401：检查 API Key 是否完整、是否已停用或过期，并确认鉴权方式与协议一致。
  • 返回 403：检查 API Key 是否包含目标模型分组；如果启用了 IP 白名单，请确认当前设备 IP 已加入白名单。
  • 普通文本成功，但工具调用失败：这通常不是基础协议不可用，而是模型或上游入口不支持客户端发送的工具参数。先关闭工具能力或换一个已确认支持工具调用的模型进行对比。
  • 一个客户端成功，另一个客户端失败：对比两个客户端实际发送的请求路径、请求头和请求体。重点检查工具定义、tool_choice、思考/缓存字段及流式事件，不要只比较设置页面上的协议名称。
  • 返回模型不存在或没有可用入口：检查模型 ID 是否来自模型广场，并确认该模型在当前 API Key 下可用。若国产模型的 Chat Completions 请求失败，应先确认是本平台尚未引入对应货源，而不是直接判断模型不支持该协议；当前可改用本平台已有的 Messages 或 Responses 入口。