# 接入协议

> 灵眸支持 Anthropic、OpenAI Compatible 与 Gemini 原生三种入站协议，一张表选对 Base URL 与端点，避免报错。

URL: https://docs.lmuai.ai/cn/docs/guide/api-protocols



灵眸支持 **Anthropic、OpenAI Compatible 与 Gemini 原生 v1beta** 三种入站协议。各类端点都使用灵眸 `sk-` API Key，实际可用模型由 API Key 所属分组决定。

<Callout type="info" title="先理清两件事">
  * **「用哪种协议」**：由客户端、SDK 和业务场景决定。Anthropic SDK 走 `/v1/messages`，OpenAI SDK 走 `/v1/chat/completions` 或 `/v1/responses`，Gemini 原生图片调用走 `/v1beta/models/{model}:generateContent`。
  * **「能调哪些模型」**：由你的 API Key 所属**分组**（即你的订阅 / 充值套餐对应的上游账号）决定，**和入站协议是两个不同维度**。

  也就是说：选错协议会直接 401 / 404；选对协议但模型不在你分组的可用范围内，会返回模型不可用类的错误。
</Callout>

<Callout type="warn" title="最常见的报错来自填错协议">
  * **Anthropic 协议** 的 Base URL **不带** `/v1` 后缀
  * **OpenAI 协议** 的 SDK Base URL 通常 **带** `/v1` 后缀
  * **Gemini 原生协议** 使用 `https://api.lmuai.ai` 作为主机，并调用完整 `/v1beta/...` 路径

  填错会导致 400 / 401 / 404。配置工具或编写代码前，请先确认客户端期望的协议。
</Callout>

***

## 一眼对号入座 [#一眼对号入座]

| 协议                    | Base URL                  | 典型工具                                                                                                                 |
| --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Anthropic 协议**      | `https://api.lmuai.ai`    | Claude Code（CLI / 桌面版 / VS Code 插件）、官方 `anthropic` SDK、Cherry Studio、Kilo Code 接 Claude / 国产模型、所有兼容 Anthropic 协议的客户端 |
| **OpenAI Compatible** | `https://api.lmuai.ai/v1` | Codex CLI、Codex App、Cursor / Cline / Roo Code / OpenCode、官方 `openai` SDK、VS Code 插件接 GPT、所有兼容 OpenAI 协议的客户端          |
| **Gemini 原生 v1beta**  | `https://api.lmuai.ai`    | Gemini 原生 SDK / HTTP 客户端、Gemini 文生图和图生图、模型列表与 `generateContent`                                                      |

三类协议都使用 `sk-` 开头的灵眸密钥：

* Anthropic 协议：`Authorization: Bearer <YOUR_API_KEY>` 或 `x-api-key: <YOUR_API_KEY>`
* OpenAI Compatible：`Authorization: Bearer <YOUR_API_KEY>`
* Gemini 原生：推荐 `x-goog-api-key: <YOUR_API_KEY>`，也兼容 Bearer

***

## Anthropic 协议接入 [#anthropic-协议接入]

**Base URL：** `https://api.lmuai.ai`（**不带** `/v1`）

**端点：**

* `POST /v1/messages` — 消息对话
* `POST /v1/messages/count_tokens` — token 计数
* `GET /v1/models` — 可用模型列表

**Python SDK 示例：**

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.lmuai.ai",
    api_key="sk-xxxxxxxx",
)

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)
```

**curl 示例：**

```bash
curl -X POST https://api.lmuai.ai/v1/messages \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"你好"}]
  }'
```

<Callout type="info" title="为什么 SDK 配的是不带 /v1，curl 又带 /v1？">
  Anthropic 官方 SDK 的 `base_url` 习惯就是不带 `/v1`，SDK 内部会自动拼接 `/v1/messages` 等路径。而你手写 curl 时则要写完整路径 `/v1/messages`。两种写法对应同一个端点。
</Callout>

***

## OpenAI 协议接入 [#openai-协议接入]

**Base URL：** `https://api.lmuai.ai/v1`（**带** `/v1`）

**端点：**

* `POST /chat/completions` — 标准 Chat Completions API
* `POST /responses` — OpenAI Responses API（含 `/responses/{id}` 子路径）
* `POST /images/generations`、`POST /images/edits` — 图片生成 / 编辑

**Python SDK 示例：**

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.lmuai.ai/v1",
    api_key="sk-xxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

**curl 示例：**

```bash
curl -X POST https://api.lmuai.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role":"user","content":"你好"}]
  }'
```

***

## Gemini 原生协议接入 [#gemini-原生协议接入]

**Base URL：** `https://api.lmuai.ai`

**主要端点：**

* `GET /v1beta/models` — 查询 Gemini 原生模型列表
* `GET /v1beta/models/{model}` — 查询指定模型
* `POST /v1beta/models/{model}:generateContent` — 文本生成、文生图和图生图
* `POST /v1beta/models/{model}:streamGenerateContent?alt=sse` — 流式生成

**鉴权：**

```http
x-goog-api-key: YOUR_API_KEY
```

最小文生图示例：

```bash
curl --request POST \
  'https://api.lmuai.ai/v1beta/models/gemini-3.1-flash-image:generateContent' \
  -H 'x-goog-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "一只戴宇航员头盔的橘猫"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"}
    }
  }'
```

<Callout type="info" title="Gemini 图片接口不是 /v1/chat/completions">
  Gemini 图片模型推荐使用原生 `generateContent`。完整文生图、图生图、1K / 2K / 4K 和 Base64 解析说明请查看 [Gemini 生图 API](/cn/docs/api/gemini-image)。

  GPT 图片模型请查看 [GPT 生图 API](/cn/docs/api/gpt-image)，Grok 图片模型请查看 [Grok 生图 API](/cn/docs/api/grok-image)。大量 Gemini 离线任务请查看 [Gemini 批量生图 API](/cn/docs/api/gemini-image-batch)。
</Callout>

***

## 协议和可用模型是两件事 [#协议和可用模型是两件事]

你的 Key 能调哪些模型，**完全由所属分组挂载的上游账号决定**，和你用哪种协议调用无关：

| 你的分组挂的上游                | 实际能调的模型                                        |
| ----------------------- | ---------------------------------------------- |
| 仅 OpenAI 账号             | 仅 GPT 系列                                       |
| 仅 Claude 账号             | 仅 Claude 系列（即便你用 OpenAI 协议调用，后端会做协议转换，但模型范围不变） |
| 仅国产模型上游（如 GLM / Kimi 等） | 仅对应的国产模型                                       |
| 后台配置了模型路由（多上游分组）        | 按模型名分流到不同上游，可跨品牌——具体范围以分组配置为准                  |

所以：

* 选择 Anthropic、OpenAI Compatible 或 Gemini 原生协议，代表的是入站请求格式；实际模型范围仍由 API Key 分组决定。
* 想知道当前 Key 实际能调哪些模型，去后台「**API 密钥**」详情或「**可用模型**」页面查看分组对应的模型清单。

***

## 关于 Claude Max 分组 [#关于-claude-max-分组]

<Callout type="warn" title="Claude Max 分组仅支持 Anthropic 协议">
  **Claude Max 分组只供 Claude Code 使用**，所以它只能走 **Anthropic 协议**（`https://api.lmuai.ai`）。

  如果你用的是 Claude Max 套餐分组下的密钥：

  * ✅ 可以在 Claude Code（CLI / 桌面版 / VS Code 插件）中使用
  * ❌ **不能**用在 Codex CLI、Cursor、Cherry Studio 等任何走 OpenAI 协议的工具上
  * ❌ **不能**填入 `https://api.lmuai.ai/v1`

  需要在 OpenAI 协议工具中使用，请改用按量充值 / 普通订阅分组的密钥（具体可用模型仍以你购买的套餐分组为准）。
</Callout>

***

## 排错速查 [#排错速查]

| 现象                              | 通常原因                                                                         | 处理                                   |
| ------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
| `401 Unauthorized`              | Base URL 填错协议 / 密钥写错 / IDE 没重启                                               | 核对 Base URL 是否与工具协议匹配；重启 IDE 重新加载配置  |
| `404 Not Found`                 | OpenAI 协议地址漏写 `/v1`、Anthropic 地址多写 `/v1`，或 Gemini 路径未使用 `/v1beta/models/...` | 按上表重新核对 Base URL 和完整端点               |
| 模型不可用 / `No available accounts` | 调用了不在你分组可用范围内的模型（如用 Claude Max 分组调 GPT）                                      | 在后台「可用模型」页确认你分组实际包含的模型，或切换到包含目标模型的分组 |
| `429 Too Many Requests`         | 当日额度用完                                                                       | 参考 [常见问题](./faq#问题-2429-重试错误)        |

更多排错请参见 [常见问题](./faq)。

***

## 下一步 [#下一步]

确认好协议和 Base URL 后，挑选你要用的工具：

* [CC Switch（一键导入，推荐 Claude Code 用户）](../tools/cc-switch)
* [Claude Code CLI](../tools/claude-code) · [桌面版](../tools/claude-code-desktop) · [VS Code 插件](../tools/claude-code-vscode)
* [Codex CLI · Windows](../tools/codex-cli-windows) · [Mac/Linux](../tools/codex-cli-mac) · [服务器](../tools/codex-cli-server)
* [Codex App 桌面版](../tools/codex-app) · [VS Code / Cursor / Trae 插件](../tools/vscode-plugin)
* [OpenCode](../tools/opencode) · [Cherry Studio](../tools/cherry) · [IDEA Kilo Code](../tools/kilo-code-idea) · [Hermes Agent](../tools/hermes)
* [Gemini 生图 API](/cn/docs/api/gemini-image) · [GPT 生图 API](/cn/docs/api/gpt-image) · [Grok 生图 API](/cn/docs/api/grok-image) · [Gemini 批量生图 API](/cn/docs/api/gemini-image-batch)