# 网关扩展请求头与响应头

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

除了 OpenAI、Anthropic 的标准字段，LYRouter 还约定了几个请求头、响应头和特殊模型名：用请求头控制参数校验、声明会话、要求原生直通，从响应头读取被丢弃的参数和配额余量，用特殊模型名调用虚拟模型、Auto 智能路由或默认模型。这些约定都是可选的，不使用时按标准协议正常调用。HTTP 头名不区分大小写。

## 速查

| 名称 | 方向 | 作用 | 适用接口 |
| --- | --- | --- | --- |
| `X-Gateway-Strict-Parameters: true` | 请求 | 有参数会被丢弃时，改为返回 400 | 图像、视频 |
| `x-session-id` | 请求 | 声明会话，日志按会话归组；原样转发给上游 | 全部 |
| `x-gateway-passthrough: require` | 请求 | 要求 Anthropic 原生直通，做不到就返回 400 | `/v1/messages` |
| `X-Title` | 请求 | 在日志「客户端」列标识你的应用 | 全部 |
| `X-Gateway-Unsupported-Parameters` | 响应 | 列出被网关丢弃的参数 | 图像、视频 |
| `x-aigw-quota-<指标>-limit` / `-remaining` / `-reset` | 响应 | 适用配额的上限、剩余量和重置时间 | 调用模型的接口 |
| `anthropic-ratelimit-*` | 响应 | Anthropic 格式的限额信息 | `/v1/messages` |
| `Retry-After`、`X-RateLimit-Reason`、`X-RateLimit-Reset` | 响应 | API Key 被熔断或封禁 | 调用模型的接口 |
| `@vmodel/<名称>`、`@preset/<名称>` | 模型名 | 调用虚拟模型 | 对话类接口等 |
| `lyrouter/auto` | 模型名 | Auto 智能路由 | 对话类接口 |
| 省略 `model` | 模型名 | 使用工作空间默认模型 | 全部模型接口 |

## 请求头

### X-Gateway-Strict-Parameters

图像和视频接口会把所选模型不支持的参数丢掉、继续执行，并在响应头 `X-Gateway-Unsupported-Parameters` 中列出。带上这个请求头后，出现会被丢弃的参数时网关直接返回 400，不调用上游、不计费。

- **取值**：只认小写的 `true`，其他值（包括 `True`、`1`）等同于没带。
- **适用接口**：`/v1/images/generations`、`/v1/images/edits`、`/v1/videos`、`/v1/videos/regenerations`、`/v1/videos/context`。对话接口在跨协议转换时去掉的参数不受它控制，见 [Chat Completions](https://platform.lyrouter.com/ai_gateway/docs/chat-completions)。

```bash
curl https://api.lyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Gateway-Strict-Parameters: true" \
  -d '{"model":"MODEL_ID","prompt":"一只戴墨镜的柴犬","guidance_scale":7}'
```

所选模型不支持 `guidance_scale` 时返回：

```json
{
  "error": {
    "message": "unsupported parameters for this model: guidance_scale",
    "type": "invalid_request_error",
    "code": "unsupported_parameters"
  }
}
```

各模型支持哪些参数见[多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal)。

### x-session-id

为一段对话指定一个固定的会话 ID（例如每个会话生成一个 UUID），同一会话的每次请求都带上同一个值。用于日志归组时，`x-session` 与它等价。

- **日志归组**：[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)的「会话」列按这个值把请求归为一组，来源显示「声明（客户端 x-session-id）」，也可以按「会话 ID」筛选。不带这个头时，网关根据对话内容推断会话，来源显示「推断（网关派生）」，标签末尾带 `≈`。
- **原样转发**：网关把这个头原样转发给上游，不改值。
- **上游会话保持**：平台为少数通道开启了会话保持时，你没带这个头，网关会自动补一个 `X-Session-Id: aigw-<哈希>`；带了就用你的值。是否影响上游的缓存或实例分配由服务商决定。
- **不影响网关选路**：网关自己的会话保持按「API Key + 模型」进行，见[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)，与这个头无关。

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-session-id: 6f1c7e2a-3b4d-4e5f-9a8b-1c2d3e4f5a6b" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"继续上次的话题"}]}'
```

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

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
session_id = str(uuid.uuid4())  # 每段对话生成一次，之后每轮都复用
completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "继续上次的话题"}],
    extra_headers={"x-session-id": session_id},
)
```

Node.js:
```js
import { randomUUID } from "node:crypto";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const sessionId = randomUUID(); // 每段对话生成一次，之后每轮都复用
const completion = await client.chat.completions.create(
  {
    model: "MODEL_ID",
    messages: [{ role: "user", content: "继续上次的话题" }],
  },
  { headers: { "x-session-id": sessionId } },
);
```

### x-gateway-passthrough

通过 `/v1/messages` 调用 Anthropic 协议的通道时，网关默认会把请求转换为内部格式再转换回去。带上 `x-gateway-passthrough: require` 表示「请求体必须原样发给上游，不允许转换」：满足不了时网关返回 400，并说明是哪一项条件不满足，不会悄悄改走转换。

| 取值 | 行为 |
| --- | --- |
| `require`（不区分大小写） | 必须原样直通，做不到就返回 400 |
| `prefer`、其他值或不带 | 默认行为：能直通就直通，不能就转换，请求照常完成 |

- 这个头只给网关看，不会转发给上游。
- LYRouter 公共网关目前没有开启原生直通，带 `require` 的请求都会返回 400，不需要时不要发送这个头。

被拒绝时的报错原文为 ``native passthrough was required by `x-gateway-passthrough: require` but is not available for this request (<原因>)``。在 `/v1/messages` 上它以 Anthropic 错误格式返回（`invalid_request_error`），在其他接口上（如 `/v1/responses`）是一行纯文本，但响应头目前仍是 `Content-Type: application/json`，解析前请先判断正文是否为 JSON。括号中各原因码的含义与处理方法见[协议兼容性与限制](https://platform.lyrouter.com/ai_gateway/docs/compatibility#原生直通)。

### X-Title

在请求头中带上 `X-Title: <应用名>`，网关没有从其他特征识别出已知工具（如 Claude Code、Cursor）时，[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)的「客户端」列显示这个应用名，用量分析中也按它统计客户端分布。这个头会原样转发给上游。

## 响应头

### X-Gateway-Unsupported-Parameters

图像、视频请求中有参数被网关丢弃时，响应带上这个头，值为逗号分隔的参数名，例如 `X-Gateway-Unsupported-Parameters: response_format` 或 `guidance_scale,watermark`。请求本身照常执行。生产环境建议检查这个头，或者直接用 `X-Gateway-Strict-Parameters: true` 把丢弃变成报错。

### x-aigw-quota-*

有[配额](https://platform.lyrouter.com/ai_gateway/docs/quota)适用于这次调用时，响应带上配额头。成功的响应和配额触顶的 429 会带，很多 400 也会带，例如 `Content-Type` 不对、模型不支持所调用的接口、上游返回的 400、原生直通被拒绝；401、403、503 和缺少 `model` 的 400（`missing_model`）不带。每个适用的指标三项：

| 响应头 | 含义 |
| --- | --- |
| `x-aigw-quota-<指标>-limit` | 上限。`credits` 为整信用点，其余为 Token 数或请求数 |
| `x-aigw-quota-<指标>-remaining` | 剩余量，按发出请求时的用量计算，不含本次请求的消耗；不会小于 0 |
| `x-aigw-quota-<指标>-reset` | 下次重置时间，RFC 3339 格式的 UTC 时刻。目前这个值比实际重置时刻晚：按天、按月的配额约晚 2 分钟（例如在 `16:00:00Z` 重置的按月配额，返回的是 `16:02:00Z`～`16:02:06Z`），按分钟计的配额约晚 1 分钟，各次请求之间还会相差几秒。只用它估计重置时间，不要用于精确计时。没有重置周期的总量配额不带这一项 |

指标为 `credits`、`tokens`、`requests`、`input-tokens`、`output-tokens`。同一指标有多条配额同时适用时（例如 API Key 配额和工作空间配额），给出剩余量最少的那一条。

```text
x-aigw-quota-credits-limit: 2000
x-aigw-quota-credits-remaining: 1532
x-aigw-quota-credits-reset: 2026-10-31T16:02:00Z
x-aigw-quota-requests-limit: 600
x-aigw-quota-requests-remaining: 597
x-aigw-quota-requests-reset: 2026-10-14T06:31:00Z
```

用 SDK 读取响应头：

**读取响应头**

cURL:
```bash
curl -s -D - -o /dev/null 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":"你好"}]}' \
  | grep -i '^x-aigw-quota-'
```

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

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
raw = client.chat.completions.with_raw_response.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(raw.headers.get("x-aigw-quota-credits-remaining"))
completion = raw.parse()
```

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

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const { data: completion, response } = await client.chat.completions
  .create({ model: "MODEL_ID", messages: [{ role: "user", content: "你好" }] })
  .withResponse();
console.log(response.headers.get("x-aigw-quota-credits-remaining"));
```

配额头只出现在调用模型的接口上（对话、Responses、Messages、向量、重排、图像、语音和视频提交），`/v1/models`、视频任务查询等接口不带。配额用完后的 429 见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

### Retry-After、X-RateLimit-Reason、X-RateLimit-Reset

这组头只在 API Key 因错误率过高被网关熔断或封禁时出现：

| 场景 | 状态码 | 响应头 |
| --- | --- | --- |
| 临时熔断（`api_key_circuit_open`） | 429 | `Retry-After: <秒数>`、`X-RateLimit-Reason: api_key_circuit_open`、`X-RateLimit-Reset: <解除时刻的 Unix 秒>` |
| 永久封禁（`api_key_permanently_banned`） | 403 | `X-RateLimit-Reason: api_key_permanently_banned` |

- 配额用完的 429 不带 `Retry-After`，请按错误体中的 `reset_at` 或 `x-aigw-quota-*-reset` 等待。
- 上游服务商自己的 `Retry-After` 只在 `/v1/messages` 上转发给你。
- 处理方法见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)和[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

### anthropic-ratelimit-*

通过 `/v1/messages` 调用时，响应带 Anthropic 格式的限额头，供 Claude Code 等客户端调整请求节奏：

- 服务这次请求的上游返回了 `anthropic-ratelimit-*` 时，网关原样转发（连同上游的 `Retry-After`），这些数字是上游账户的限额。
- 上游没有返回、而你有请求数或 Token 配额时，网关按配额生成 `anthropic-ratelimit-requests-*`、`-tokens-*`、`-input-tokens-*`、`-output-tokens-*` 的 `-limit`、`-remaining`、`-reset`。信用点配额没有对应的 Anthropic 头，请看 `x-aigw-quota-credits-*`。

同一个响应里 `anthropic-ratelimit-*` 与 `x-aigw-quota-*` 的数字不同是正常的：前者可能来自上游，后者始终是你在 LYRouter 的配额。

### 请求 ID

网关不在响应头中返回请求 ID。排查某次调用时，在控制台日志详情顶部复制 Request ID，见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。

部分上游（如 GLM 系列模型的通道）的响应体里会出现 `"request_id":"aigw-…"`：这是网关自动补的会话 ID（`X-Session-Id`，见上文「x-session-id」）被上游回显，不是 LYRouter 的 Request ID。请求带了 `x-session-id` 时，回显的就是你传的值。

## 特殊模型名

| 写法 | 含义 | 可用接口 |
| --- | --- | --- |
| `@vmodel/<名称>` | 调用工作空间的[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets) | `/v1/chat/completions`、`/v1/messages`、`/v1/responses`；虚拟模型的模型列表全部是向量或重排模型时，也可用于 `/v1/embeddings`、`/v1/rerank` |
| `@preset/<名称>` | 虚拟模型的旧前缀，与 `@vmodel/` 等价 | 同上 |
| `lyrouter/auto` | [Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto)，在候选模型中按请求意图选择 | `/v1/chat/completions`、`/v1/messages`、`/v1/responses` |
| 省略 `model`，或写成 `""`、`null` | 使用工作空间的[默认模型](https://platform.lyrouter.com/ai_gateway/docs/routing) | 所有需要 `model` 的接口 |

- 虚拟模型和 `lyrouter/auto` 用在图像、视频、语音接口上时返回 403 `Model is not available in the model plaza`，这些接口只接受具体的模型 ID。
- 启用中的虚拟模型和 `lyrouter/auto` 会出现在 `GET /v1/models` 的结果中，见[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)。
- 省略 `model` 而工作空间没有设置默认模型时，返回 400 `you must provide a model parameter`（`missing_model`）。默认模型通常是对话模型，在向量、重排、语音接口上省略 `model` 多半得到 400 `unsupported_model_api`，这些接口请始终写明模型 ID。模型 ID 的写法见[模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names)。