LYRouter 文档

模型命名与查询

请求中的 model 写模型 ID，格式为 厂商/模型（例如 deepseek/deepseek-v4-flash），区分大小写，必须与模型广场或 GET /v1/models 返回的值逐字一致。另有两类特殊名称：@vmodel/<名称> 调用虚拟模型，lyrouter/auto 调用 Auto 智能路由。客户端始终写模型 ID，服务商那边的真实模型名（包括 BYOK 的接入点编号）由网关替换，不要写进请求。

模型 ID 的格式

组成 示例 说明
厂商 deepseek、qwen、anthropic、openai、google 斜杠前是开发模型的厂商，不是提供服务的服务商。同一模型由多个服务商提供时，模型 ID 只有一个
模型名 deepseek-v4-flash、qwen3.7-plus、claude-sonnet-4.6 包含规格和版本号，写法以模型目录为准
  • 逐字一致：大小写、标点与目录中的模型 ID 完全相同，前后不带空格。网关不做大小写转换、不补厂商前缀，也不把相近的名称当作同一个模型。
  • 版本号照抄：anthropic/claude-sonnet-4.6 的版本号用点号，写成 anthropic/claude-sonnet-4-6 找不到这个模型。
  • 不同版本是不同的 ID：同一系列的不同规格、版本使用不同的模型 ID，网关不会把旧 ID 自动指向新版本。更换版本的步骤见模型版本与下线。
  • 显示名称不能调用：模型广场卡片标题（如「DeepSeek V4 Flash」）只用于展示；GET /v1/models 的 display_name 同理。

下表列出常见写法的结果（假设工作空间已开通 deepseek/deepseek-v4-flash 和 anthropic/claude-sonnet-4.6）：

请求中的 model 结果
deepseek/deepseek-v4-flash 正确
DeepSeek/deepseek-v4-flash 找不到（大小写不同）
deepseek-v4-flash 找不到（缺少厂商前缀）；Codex 客户端例外，见下文
deepseek/deepseek-v4-flash （末尾有空格） 找不到
anthropic/claude-sonnet-4-6 找不到（版本号写法不同）
DeepSeek V4 Flash 找不到（显示名称）
ep-20260101xxxxxx-xxxxx 找不到（服务商的接入点编号）

「找不到」时的表现取决于工作空间是否在 智能路由 中设置了默认模型：

  • 设置了默认模型：对话类请求改由默认模型回答，HTTP 状态是 200。程序拿到了回答，但不是你想调用的模型。
  • 没有设置默认模型：返回 403 Model is not available in the model plaza（error.code 为 model_not_available）。

在 日志分析 中对比「模型（请求）」和「模型（实际）」：两者不同、且「模型（实际）」是默认模型时，说明请求中的名称没有匹配上。默认模型的行为见通道选择与路由策略。

特殊名称

名称 作用 规则
@vmodel/<名称> 调用工作空间中已启用的虚拟模型 <名称> 只含小写字母、数字和连字符，以字母或数字开头，区分大小写。旧前缀 @preset/<名称> 与之等价
lyrouter/auto 按任务难度在已开通的模型中挑选，见Auto 智能路由 固定写法
  • 适用接口：lyrouter/auto 只适合 /v1/chat/completions、/v1/messages 和 /v1/responses；虚拟模型除这三个接口外，也可以用于向量与重排接口（其模型列表须全部是向量或重排模型，见创建向量和文档重排）。两者用在图像、视频接口上都返回 403 Model is not available in the model plaza。
  • 名称失效：虚拟模型被停用、删除或改名后，旧名称不再匹配。设置了默认模型时由默认模型回答，否则返回 503 all routed candidates exhausted。
  • 在日志中显示：通过这两类名称调用时，日志「路由追踪」的「虚拟模型」显示虚拟模型名称（不带 @vmodel/）或 lyrouter/auto，「模型（实际）」显示实际回答的模型。

省略 model

请求体没有 model，或写成 ""、null 时，网关使用工作空间的默认模型。没有设置默认模型时返回 400 you must provide a model parameter（missing_model）；model 不是字符串时返回 400 invalid type for 'model': expected a string（invalid_model）。生产代码请始终写明模型 ID，避免默认模型调整后行为随之改变。

Codex 客户端的名称补全

Codex 的部分界面只能选择不带厂商前缀的模型名（如 gpt-5.5）。网关识别到 Codex 客户端发来的请求时，给不含斜杠的模型名自动补上 openai/，即 gpt-5.5 按 openai/gpt-5.5 调用。已经带斜杠的名称不受影响，其他客户端也不做这种补全。在 Codex 中调用非 OpenAI 模型时，请在配置文件中填写完整的模型 ID，见Codex。

BYOK 与上游模型名

使用 BYOK 接入自己的服务商凭证后，客户端仍然写模型 ID，网关在发往服务商时换成映射的上游模型名：

名称 示例 写在哪里
模型 ID deepseek/deepseek-v4-pro 请求的 model、虚拟模型、Auto 候选范围、安全围栏模型策略
上游模型名 deepseek-v4-pro，或火山方舟的 ep-* 接入点编号 只出现在网关发给服务商的请求中，由 BYOK 的模型映射决定
  • 上游名不能当模型 ID：请求中写 ep-* 等上游名，按「找不到」处理，见上文。
  • 同一个模型 ID 可能对应不同上游名：平台通道和各个 BYOK 通道各有自己的映射，网关按实际选中的通道替换。客户端代码不需要关心是哪一个。
  • 自定义服务商也映射到模型 ID：自定义服务商的每个上游模型都要对应一个平台模型目录中的模型，不能新建模型 ID，见模型映射与来源配置。
  • 核对实际发出的名称：在日志详情的「原始报文」中查看「上游请求」，其中的 model 是上游模型名。正文只在工作空间开启全文日志后保存，失败的请求除外。

响应体中的 model 字段是上游返回的值，通常是上游模型名，不一定等于请求时写的模型 ID。程序需要记录「调用了哪个模型」时，请记录自己发送的模型 ID，或以日志的「模型（实际）」为准。

查询可用的名称

方式 得到什么 适合
工作空间 模型广场 已开通的模型及其服务商、价格；点击模型 ID 旁的复制按钮 人工挑选模型，见如何选择模型
GET /v1/models 这个 API Key 可调用的模型 ID，以及已启用的 @vmodel/<名称> 和 lyrouter/auto 程序获取列表、填充模型选择器
虚拟模型 页面 虚拟模型的调用名称 当前账号管理员管理虚拟模型；普通成员用 GET /v1/models 查询名称

GET /v1/models 已经按安全围栏的模型策略过滤，比模型广场更接近「这个 Key 实际能调用什么」。

常见问题

模型广场能看到这个模型，为什么调用时找不到？

答： 先确认它在「专属可用模型」中，而不是「可启用」或「需接入」；再用调用时的 API Key 请求 GET /v1/models，确认列表中有这个 ID。不在列表中，说明没有开通，或被安全围栏的模型策略限制了，见模型授权。在列表中却仍然失败，按报错原文对照模型不可用。

客户端只能填不带斜杠的模型名，怎么办？

答： Codex 由网关自动补 openai/ 前缀。其他只接受固定名称的客户端，可以创建一个虚拟模型，把 @vmodel/<名称> 填进客户端；客户端连 @ 和 / 都不接受时，请换用支持自定义模型名的客户端或配置方式，见工具兼容性与接入总览。

Claude Code 发出的请求用了 Claude 官方模型名，为什么失败？

答： Claude Code 的后台任务和模型别名会使用 Claude 官方模型名（如 claude-haiku-4-5），这不是 LYRouter 的模型 ID。按Claude Code补齐各个模型变量，全部填 LYRouter 的模型 ID，再在日志的「模型（请求）」中确认没有遗漏。