网关扩展请求头与响应头

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

速查

请求头

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。

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 时返回：

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

各模型支持哪些参数见多模态能力。

x-session-id

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

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

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":"继续上次的话题"}]}'

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},
)

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，并说明是哪一项条件不满足，不会悄悄改走转换。

• 这个头只给网关看，不会转发给上游。
• 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。括号中各原因码的含义与处理方法见协议兼容性与限制。

X-Title

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

响应头

X-Gateway-Unsupported-Parameters

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

x-aigw-quota-*

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

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

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 -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-'

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()

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：限流与配额。

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

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

• 配额用完的 429 不带 Retry-After，请按错误体中的 reset_at 或 x-aigw-quota-*-reset 等待。
• 上游服务商自己的 Retry-After 只在 /v1/messages 上转发给你。
• 处理方法见429：限流与配额和401 / 403：鉴权与权限。

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，见错误码与请求标识。

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

特殊模型名

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