# 接入地址与鉴权

来源: https://platform.lyrouter.com/ai_gateway/docs/call-gateway
更新日期: 2026-10-19

所有调用都发往网关地址 `https://api.lyrouter.com`，用同一个 LYRouter API Key 鉴权。OpenAI SDK 的 Base URL 填 `https://api.lyrouter.com/v1`，Anthropic SDK 填根地址 `https://api.lyrouter.com`；密钥放在 `Authorization: Bearer <API Key>` 或 `x-api-key` 请求头中。请求体的 `model` 写系统模型 ID、`@vmodel/<名称>` 或 `lyrouter/auto`，省略时使用工作空间的默认模型。

## 地址

| 协议 | SDK Base URL | 请求路径 |
| --- | --- | --- |
| Chat Completions | https://api.lyrouter.com/v1 | /v1/chat/completions |
| Responses | https://api.lyrouter.com/v1 | /v1/responses |
| Anthropic Messages | https://api.lyrouter.com | /v1/messages |

- **SDK 只填 Base URL**：OpenAI SDK 会在 `/v1` 后拼接 `/chat/completions`、`/responses`、`/models` 等路径，Anthropic SDK 会在根地址后拼接 `/v1/messages`。cURL 和自己发 HTTP 请求时写完整 URL，例如 `https://api.lyrouter.com/v1/chat/completions`。
- **不要重复 `/v1`**：Anthropic SDK 的 Base URL 写成 `https://api.lyrouter.com/v1` 时，实际请求 `/v1/v1/messages`，返回 404。OpenAI SDK 的 Base URL 写到 `/v1/chat/completions` 也会拼出错误路径。
- **版本前缀**：除 `/v1` 外，网关也接受不带版本前缀（如 `/chat/completions`）或其他版本号前缀（如部分智谱客户端使用的 `/v4/chat/completions`）的同名路径，按同一接口处理。新接入的应用请统一使用 `/v1`。
- **控制台地址不是网关地址**：浏览器中打开的控制台页面（`/ai_gateway/...`）不能用作 Base URL。自部署时，把本页的 `https://api.lyrouter.com` 换成你的网关地址。

## 鉴权

在当前工作空间的 **API 密钥** 页面创建 API Key，见[创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys)。网关按 API Key 识别工作空间，并在调用上游时换成平台或 BYOK 的服务商凭证；你的 API Key 不会转发给上游。服务商的 API Key 和控制台登录会话都不能用来调用网关。

| 请求头 | 写法 | 适用 |
| --- | --- | --- |
| `Authorization` | `Bearer <API Key>`，`Bearer` 区分大小写，后面有一个空格 | 所有接口；OpenAI SDK 的 `api_key` / `apiKey`、Anthropic SDK 的 `auth_token` / `authToken` 使用这种写法 |
| `x-api-key` | 直接写 `<API Key>`，不加前缀 | 所有接口；Anthropic SDK 的 `api_key` / `apiKey` 使用这种写法 |

- **只读一个**：同时带两个请求头时，网关只读 `Authorization`。`Authorization` 格式错误时直接返回 401，不会改读 `x-api-key`。
- **只放在请求头**：不要把密钥写进 URL 查询参数或请求体。
- **生效时间**：新建、停用或修改 Key 后几秒内同步到网关。

### API Key 自身的限制

创建或编辑 Key 时可以设置以下限制，触发后网关在调用上游前拒绝请求：

| 设置（API 密钥编辑页） | 触发后的响应 | 说明 |
| --- | --- | --- |
| 「基本信息」中的「到期时间」 | 403 `api key expired` | 到期后过一段时间改为 401 `invalid api key`；新建 Key 替换 |
| 「预算限额」中的「费用预算（元）」「Token 预算（百万 Token）」 | 429 `rate limit exceeded on apikey <指标>/<窗口>` | 「每月」每月 1 日重置，「总计」不重置，见[预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota) |
| 「访问控制」中的「启用 IP 白名单」 | 403 `your IP address is not allowed` | 网关按请求到达时的出口 IP 判断；白名单为空或含无效条目时返回 403 `ip access control misconfigured` |

此外，Key 还受工作空间的安全围栏策略约束（模型策略、配额、客户端访问控制），见[安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails)。各报错的处理见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)和[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

## OpenAI SDK

Chat Completions、Responses、Models、Embeddings 等 OpenAI 兼容接口共用同一个客户端，Base URL 写到 `/v1`：

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'
```

Python:
```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(completion.choices[0].message.content)

# 同一个客户端调用 Responses
response = client.responses.create(model="MODEL_ID", input="用一句话介绍你自己")
print(response.output_text)
```

Node.js:
```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});

const completion = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(completion.choices[0].message.content);

// 同一个客户端调用 Responses
const response = await client.responses.create({ model: "MODEL_ID", input: "用一句话介绍你自己" });
console.log(response.output_text);
```

`MODEL_ID` 换成模型广场中复制的模型 ID，`LYROUTER_API_KEY` 环境变量的设置见[完成第一次模型调用](https://platform.lyrouter.com/ai_gateway/docs/quickstart)。Responses 要求模型和服务它的通道支持 Responses 接口，见[Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api)。Python 示例中的 `client.responses` 需要 openai Python SDK 1.66 或更高版本，旧版本会报 `AttributeError: 'OpenAI' object has no attribute 'responses'`。

## Anthropic SDK

Anthropic SDK 的 Base URL 写根地址，不带 `/v1`。`/v1/messages` 不要求模型来自 Anthropic，任何对话模型都可以通过它调用：

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/messages \
  -H "x-api-key: $LYROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'
```

Python:
```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(message.content[0].text)
```

Node.js:
```js
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com",
});

const message = await client.messages.create({
  model: "MODEL_ID",
  max_tokens: 1024,
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(message.content[0].text);
```

请求、响应和流式事件的细节见[Anthropic Messages](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages)。

### 只改环境变量接入已有代码

两种 SDK 都会读取环境变量。已有代码没有显式传入地址和密钥时，设置下表中的变量即可改走网关：

| SDK | 地址变量 | 密钥变量 |
| --- | --- | --- |
| OpenAI（Python / Node.js） | `OPENAI_BASE_URL=https://api.lyrouter.com/v1` | `OPENAI_API_KEY=<LYRouter API Key>` |
| Anthropic（Python / Node.js） | `ANTHROPIC_BASE_URL=https://api.lyrouter.com` | `ANTHROPIC_API_KEY=<LYRouter API Key>`（以 `x-api-key` 发送）或 `ANTHROPIC_AUTH_TOKEN=<LYRouter API Key>`（以 `Authorization: Bearer` 发送） |

代码中的模型名也要换成 LYRouter 的模型 ID。Claude Code、Codex 等编程工具的配置见[工具兼容性与接入总览](https://platform.lyrouter.com/ai_gateway/docs/tools)。

## `model` 字段

| 写法 | 含义 | 可用接口 |
| --- | --- | --- |
| 系统模型 ID，如 `deepseek/deepseek-v4-flash` | 调用这个模型，网关按[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)选择服务商通道 | 所有带 `model` 的接口 |
| `@vmodel/<名称>`（旧写法 `@preset/<名称>` 等价） | 调用已启用的[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)，按其主模型、备用模型和参数执行 | Chat Completions、Anthropic Messages、Responses；模型列表全部是向量或重排模型时也可用于[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)和[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank) |
| `lyrouter/auto` | 按任务难度在已开通的模型中挑选，见[Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto) | Chat Completions、Anthropic Messages、Responses |
| 省略，或写成 `""`、`null` | 使用工作空间在 **智能路由** 中设置的默认模型 | 带 `model` 的接口 |

- 模型 ID 区分大小写，必须与模型广场或 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 返回的 `id` 逐字一致，命名规则见[模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names)。
- 省略 `model` 且工作空间没有默认模型时，返回 400 `you must provide a model parameter`（`error.code` 为 `missing_model`）；`model` 不是字符串时返回 400 `invalid type for 'model': expected a string`（`invalid_model`）。
- 虚拟模型和 `lyrouter/auto` 用在图像、视频、语音接口上时，返回 403 `Model is not available in the model plaza`，这些接口请写具体的模型 ID。

## 全部端点

所有端点使用同一个 Base URL 和同一套鉴权：

| 方法 | 路径 | 用途 | 文档 |
| --- | --- | --- | --- |
| POST | `/v1/chat/completions` | 对话生成（OpenAI Chat Completions 格式） | [Chat Completions](https://platform.lyrouter.com/ai_gateway/docs/chat-completions) |
| POST | `/v1/responses` | 对话生成（OpenAI Responses 格式） | [Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api) |
| POST | `/v1/messages` | 对话生成（Anthropic Messages 格式） | [Anthropic Messages](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages) |
| GET | `/v1/models` | 列出这个 API Key 可调用的模型 | [列出模型](https://platform.lyrouter.com/ai_gateway/docs/models) |
| POST | `/v1/embeddings`、`/v1/rerank` | 文本向量、重排序 | [创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)、[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank) |
| POST | `/v1/images/generations`、`/v1/images/edits` | 图像生成、编辑 | [多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal) |
| POST | `/v1/videos`、`/v1/videos/regenerations`、`/v1/videos/context` | 提交视频任务 | [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) |
| GET、DELETE | `/v1/videos/{id}`、`/v1/videos/{id}/content` | 查询任务、下载产物、取消任务 | [异步任务](https://platform.lyrouter.com/ai_gateway/docs/async) |

全部接口按能力分组的说明见[API 文档](https://platform.lyrouter.com/ai_gateway/docs/api-overview)，网关自定义的请求头和响应头见[网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers)。

## 地址与鉴权类错误

OpenAI 兼容接口的错误体为 `{"error": {"message": "...", "type": "...", "code": "..."}}`，`code` 只在部分错误上出现。`/v1/messages` 上的错误会转换为 Anthropic 格式 `{"type": "error", "error": {"type": "authentication_error", "message": "..."}}`，`message` 原文不变，没有 `code`。

| 状态码 | 报错原文 | 原因与处理 |
| --- | --- | --- |
| 404 | `{"error_msg":"404 Route Not Found"}` | 路径或方法不存在：Base URL 重复了 `/v1`、路径末尾多了 `/`、拼错端点，或用 GET 调用了只接受 POST 的接口。按上文「地址」核对完整 URL。这个响应不是标准错误体，也不会转换为 Anthropic 格式 |
| 401 | `missing credentials` | 没有带 API Key，或 `Authorization` 写成了 `Bearer `（带空格）而后面没有密钥。加上 `Authorization: Bearer <API Key>` 或 `x-api-key` |
| 401 | `invalid authorization scheme, expected 'Bearer'` | `Authorization` 不是 `Bearer <API Key>` 格式，例如写成小写的 `bearer`、只写密钥，或只写 `Bearer` 而后面没有空格 |
| 401 | `invalid api key` | Key 复制不完整或带了空白字符，或已删除、停用、过期；新建的 Key 需要几秒同步 |
| 401 | `api key verification unavailable` | 平台暂时无法校验密钥，稍后重试 |
| 400 | `unsupported content-type: application/x-www-form-urlencoded, only application/json is supported` | JSON 请求的 `Content-Type` 不是 `application/json`。cURL 用 `-d` 发送却没写 `-H "Content-Type: application/json"` 时就是这种情况。OpenAI 兼容接口上这个响应是一行纯文本，不是 JSON，但响应头目前仍是 `Content-Type: application/json`，解析前先判断正文是否为 JSON |
| 402 | `subscription expired; renew to continue` | 账户订阅已到期，续费后恢复，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable#余额与订阅) |
| 403 | `api key expired`、`your IP address is not allowed`、`ip access control misconfigured` | 见上文「API Key 自身的限制」 |
| 403 | `Model is not available in the model plaza` | 工作空间没有开通该模型，或在图像、视频、语音接口上用了虚拟模型或 `lyrouter/auto`，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable) |

响应中不包含请求 ID。提交问题时，记录调用时间、端点、模型、API Key 名称和报错原文；能在 **日志分析** 中找到这次请求时，再附上日志详情顶部的 Request ID。401 请求无法归属到 Key，不会出现在日志中。全部错误码见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。

## 常见问题

### OpenAI SDK 的 Base URL 少写了 `/v1`，为什么也能调通？

**答：** 网关同时接受不带版本前缀的路径，`https://api.lyrouter.com/chat/completions` 与 `/v1/chat/completions` 等效。其他工具和 SDK 未必这样拼接路径，请统一写成 `https://api.lyrouter.com/v1`。

### 同一个 API Key 能同时给 OpenAI 和 Anthropic 客户端使用吗？

**答：** 可以。Key 属于工作空间，与协议无关；两种客户端调用同一个模型 ID 时，费用、配额和日志都记在这个 Key 下。日志的「API 路径」列可以区分请求来自哪个接口。

### 请求被路由到了哪个服务商，从响应里能看出来吗？

**答：** 响应中没有服务商信息，`model` 字段也是上游返回的值。在 **日志分析** 中打开这次请求，「模型（实际）」和「服务商」显示最终命中的模型和通道，见[查看实际路由](https://platform.lyrouter.com/ai_gateway/docs/route-log)。