> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 选择接入协议

> 按现有 SDK、工具和模型能力选择 OpenAI、Anthropic 或 Gemini 协议。

优先沿用应用已经使用的协议。多数接入只需替换 Base URL、API Key 和模型 ID。

![APIONE 模型选择器与能力标签](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/model-selector.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=5ab2c2637860f5f187a680268134fabf)

网页端模型选择器会同时展示模型厂商、能力、上下文和输入输出价格。

## 协议对照

| 使用场景 | 推荐协议 | Base URL |
| - | - | - |
| OpenAI SDK、LangChain、大多数第三方客户端 | OpenAI Chat 或 Responses | `https://api.apione.ai/v1` |
| Claude Code、Anthropic SDK | Anthropic Messages | `https://api.apione.ai` |
| Gemini SDK、Gemini 原生工具链 | Gemini | `https://api.apione.ai/v1beta` |

> [!WARNING]
>
> Base URL 不是完整请求地址。SDK 通常会自动追加端点，手写 HTTP 请求时才使用完整路径。

## Chat 还是 Responses

* 新接入的通用对话、流式输出和工具调用，可先使用 Chat Completions。
* 已使用 OpenAI Responses SDK 或 Codex 的项目，使用 Responses。
* 不要只为更换模型而改写协议。先保持现有请求格式，再替换模型 ID。

## 客户端地址速查

先打开对应工具教程，再填写该工具要求的基础地址。确认实际请求路径中 API 版本只出现一次。

| 工具或 SDK | 填写位置 | APIONE 地址 | 教程 |
| - | - | - | - |
| OpenAI SDK、OpenCode | Base URL | `https://api.apione.ai/v1` | [SDK](https://apione.ai/docs/guides/sdks.md) · [OpenCode](https://apione.ai/docs/guides/opencode.md) |
| Codex | `base_url`，Responses 协议 | `https://api.apione.ai/v1` | [Codex](https://apione.ai/docs/guides/codex.md) |
| Claude Code | `ANTHROPIC_BASE_URL` | `https://api.apione.ai` | [Claude Code](https://apione.ai/docs/guides/claude-code.md) |
| Claude Desktop | Gateway base URL | `https://api.apione.ai` | [Claude Desktop](https://apione.ai/docs/guides/claude-desktop.md) |
| Cherry Studio（Anthropic） | API 地址 | `https://api.apione.ai` | [Cherry Studio](https://apione.ai/docs/guides/cherry-studio.md) |
| Gemini CLI | `GOOGLE_GEMINI_BASE_URL` | `https://api.apione.ai` | [Gemini CLI](https://apione.ai/docs/guides/gemini-cli.md) |
| OpenClaw（Chat Completions） | `baseUrl` | `https://api.apione.ai/v1` | [OpenClaw](https://apione.ai/docs/guides/openclaw.md) |

保存配置后，先验证模型列表，再发送一条真实消息。在 APIONE 请求明细中确认调用成功后，继续启用工具、图片或其他能力。

## 选择前检查

1. 调用 `GET /v1/models`，确认当前 Key 可用的模型 ID。
2. 调用 `GET /v1/models/{model}/params`，确认模型声明的参数。
3. 先发送最小文本请求，再逐项启用流式、工具、图片或其他能力。
4. 在控制台请求明细中确认真实调用成功和实际费用。

## 配置项怎么填

| 客户端中的字段 | OpenAI 兼容 | Anthropic 原生 | Gemini 原生 |
| - | - | - | - |
| Provider / 协议 | OpenAI Compatible | Anthropic | Gemini / Google |
| Base URL | `https://api.apione.ai/v1` | `https://api.apione.ai` | `https://api.apione.ai/v1beta` |
| API Key | APIONE Key | APIONE Key | APIONE Key |
| 模型 | `/v1/models` 返回的 ID | 当前 Key 可用且支持该协议的 ID | 当前 Key 可用且支持该协议的 ID |
| 测试方式 | Chat 或 Responses 最小请求 | Messages 最小请求 | generateContent 最小请求 |

如果客户端只有“API 地址”而没有说明是 Base URL 还是完整端点，先查该客户端教程。最常见的错误是把 `.../v1/chat/completions` 填进会自动追加 `/chat/completions` 的 SDK，最终形成重复路径。

## 按使用场景选择

### 已有代码项目

保持原 SDK 和请求结构不变，只替换地址、密钥与模型。先不要同时修改流式、工具调用、重试策略和输出格式；一次只改一类配置，便于定位问题。

### 第三方客户端

优先选择客户端提供的 OpenAI Compatible、自定义 OpenAI 或 New API。Claude Code 使用 Anthropic 原生协议，Codex 通常使用 Responses。客户端能够保存配置并不等于模型已经连通，必须发送一条真实消息验证。

### 新项目

* 普通对话和广泛兼容：从 Chat Completions 开始。
* 已采用 OpenAI 新版工作流：使用 Responses。
* Claude 原生消息与工具格式：使用 Anthropic Messages。
* Gemini 原生内容结构：使用 Gemini generateContent。

## 最小验证顺序

1. 使用同一 Key 调用 `/v1/models`，确认网络、鉴权和权限。
2. 复制准确的模型 ID，不手工猜测版本号。
3. 只发送一条文本消息，不附加工具、图片或高级参数。
4. 保存 HTTP 状态、响应正文和 `X-Maxx-Request-ID`。
5. 最小请求成功后，再逐项启用流式、结构化输出、工具或多模态输入。

## 常见选错方式

| 现象 | 可能原因 | 处理 |
| - | - | - |
| 返回 HTML 而不是 JSON | 填入了控制台网址或错误路径 | 改用 `api.apione.ai` 的协议地址 |
| 404 且路径含两次 `/v1` | Base URL 与 SDK 自动路径重复 | Base URL 只保留到版本段 |
| Key 有效但模型不可用 | 模型不属于当前 Key 或协议不匹配 | 重新查询模型列表与参数 |
| cURL 成功、客户端失败 | 客户端实际协议、代理或路径不同 | 查看客户端日志和真实请求地址 |

下一步：[地址与鉴权](https://apione.ai/docs/api/overview.md)、[快速开始](https://apione.ai/docs/quickstart.md)、[从其他平台迁移](https://apione.ai/docs/guides/migration.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.