# 列出模型

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

返回当前 API Key 可以写进 `model` 的全部名称：Key 所属工作空间已开通、且安全围栏模型策略允许这个 Key 调用的模型，外加已启用的虚拟模型（`@vmodel/<名称>`）和 `lyrouter/auto`。响应是 OpenAI 的模型列表格式，适合客户端填充模型选择器，或在启动时检查配置的模型是否可用。这个接口由网关直接应答，不调用上游、不计费，也不写入日志列表。

`GET /v1/models`

## 鉴权

在请求头中携带 API Key：

```text
Authorization: Bearer <API Key>
```

`Bearer` 区分大小写。也可以改用 `x-api-key: <API Key>`，两者同时存在时只读 `Authorization`。API Key 在工作空间的 **API 密钥** 页面创建，列表按这个 Key 所属的工作空间和适用的模型策略生成。完整说明见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)。

## 请求头

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` 或 `x-api-key` | 是 | 二选一，见上文「鉴权」 |

GET 请求没有请求体，不需要 `Content-Type`。

## 查询参数

无。列表不分页，一次返回全部条目；请求中带的查询参数会被忽略。

## 请求示例

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/models \
  -H "Authorization: Bearer $LYROUTER_API_KEY"
```

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

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

for model in client.models.list():
    print(model.id)
```

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

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

for await (const model of client.models.list()) {
  console.log(model.id);
}
```

## 响应

成功时返回 `Content-Type: application/json` 的模型列表；出错时返回 `error` 对象。下面的 401 是请求没有带 API Key，503 是网关暂时读不到工作空间的模型配置。

**响应示例**

200:
```json
{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-v4-flash",
      "object": "model",
      "created": 1791964800,
      "owned_by": "workspace",
      "display_name": "DeepSeek V4 Flash",
      "context_length": 131072,
      "max_output_tokens": 8192,
      "api_types": ["chat_completions", "responses"],
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "supported_params": ["temperature", "top_p", "max_tokens", "tools", "tool_choice", "response_format", "stream"]
    },
    {
      "id": "google/gemini-3-pro-image",
      "object": "model",
      "created": 1791964800,
      "owned_by": "workspace",
      "display_name": "Gemini 3 Pro Image",
      "api_types": ["images"],
      "input_modalities": ["text", "image"],
      "output_modalities": ["image"]
    },
    {
      "id": "lyrouter/auto",
      "object": "model",
      "created": 1791964800,
      "owned_by": "workspace"
    },
    {
      "id": "@vmodel/support-bot",
      "object": "model",
      "created": 1791964800,
      "owned_by": "workspace"
    }
  ]
}
```

401:
```json
{
  "error": {
    "message": "missing credentials",
    "type": "invalid_request_error"
  }
}
```

503:
```json
{
  "error": {
    "message": "Workspace model projection is unavailable",
    "type": "service_unavailable",
    "code": "workspace_model_projection_unavailable"
  }
}
```

条目顺序固定：先是具体模型，按模型 ID 的字母顺序排列；然后是 `lyrouter/auto`；最后是虚拟模型，按名称排列。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 固定为 `list` |
| `data[].id` | string | 写进请求 `model` 的名称，原样使用 |
| `data[].object` | string | 固定为 `model` |
| `data[].created` | integer | 生成这次响应的 Unix 时间（秒），所有条目相同，不是模型的发布时间 |
| `data[].owned_by` | string | 固定为 `workspace`，不表示模型厂商或服务商 |
| `data[].display_name` | string | 模型在模型广场上的显示名称，适合在界面上展示；调用时仍使用 `id` |
| `data[].context_length` | integer | 上下文长度（Token） |
| `data[].max_output_tokens` | integer | 最大输出长度（Token） |
| `data[].api_types` | string[] | 模型声明支持的接口，如 `chat_completions`、`responses`、`embeddings`、`rerank`、`images`、`videos`；也可能是更细的操作，如 `images_edits` |
| `data[].input_modalities` / `output_modalities` | string[] | 输入、输出模态，如 `text`、`image` |
| `data[].supported_params` | string[] | 模型声明支持的请求参数，仅供参考，网关不据此删减对话请求的参数 |

- `display_name` 及其后的字段只出现在具体模型上，并且只在模型目录有这项信息时才返回；字段缺失或为空数组（如 `"api_types": []`）都表示「没有声明」，不是「不支持」。
- `lyrouter/auto` 和虚拟模型只有 `id`、`object`、`created`、`owned_by` 四个字段，它们实际调用的模型由路由时决定。
- 响应始终是 OpenAI 格式，没有 Anthropic Models 接口的 `has_more`、`first_id` 等字段；使用 Anthropic SDK 的应用请直接发 HTTP 请求读取 `data[].id`。

### 列表包含哪些名称

| 类别 | 是否列出 | 条件 |
| --- | --- | --- |
| 模型广场「专属可用模型」中的模型 | 列出 | 按这个 Key 适用的安全围栏模型策略过滤：被策略禁止，或不在允许列表中的模型不列出 |
| 「可启用」「需接入」中的模型 | 不列出 | 在本工作空间开通或通过 BYOK 接入后才会出现 |
| 已启用的虚拟模型 | 列出，写作 `@vmodel/<名称>` | 不按模型策略过滤；已停用、已删除的虚拟模型不列出 |
| `lyrouter/auto` | 总是列出 | 不按模型策略过滤，也不受 Auto 候选范围影响 |

### 与模型广场的关系

两者的范围相同，都是当前工作空间已开通的模型，区别在于展示对象：

| | 模型广场 | `GET /v1/models` |
| --- | --- | --- |
| 看的人 | 登录控制台的成员 | 持有 API Key 的程序 |
| 模型策略 | 受限的服务商显示「成员访问受限」 | 直接不列出受限模型 |
| 粒度 | 每个模型下按服务商列出状态和价格 | 每个模型一条，不显示服务商 |
| 虚拟模型、Auto | 不显示 | 列出 |
| 显示名称 | 卡片标题 | `display_name` 字段 |

模型广场中某个模型可用、列表中却没有它时，通常是安全围栏的模型策略限制了这个 Key，请当前账号管理员查看[模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization)。公开的模型广场展示的是平台全部模型，与某个工作空间可调用的范围不同。

## 常见用法

### 填充客户端的模型选择器

用 `display_name` 展示、`id` 提交。只列对话模型时，保留 `api_types` 包含 `chat_completions`（使用 Responses 的客户端看 `responses`）的条目，没有 `api_types` 或 `api_types` 为空数组的条目和 `lyrouter/auto`、虚拟模型一起保留：

```python
import os
from openai import OpenAI

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

def is_chat(model):
    extra = model.model_extra or {}
    api_types = extra.get("api_types")
    return not api_types or "chat_completions" in api_types

options = [
    {"value": m.id, "label": (m.model_extra or {}).get("display_name") or m.id}
    for m in client.models.list()
    if is_chat(m)
]
```

`display_name`、`api_types` 等不是 OpenAI 的标准字段，OpenAI Python SDK 把它们放在 `model_extra` 中；Node.js SDK 直接作为对象属性读取。

按 `api_types` 筛选向量模型、重排模型的命令见[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)和[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank)。

### 启动时检查配置的模型

应用启动时请求一次列表，确认配置文件里的模型 ID 在 `data[].id` 中；不在时提示「模型未开通或无权调用」，比等到第一次调用才收到 403 更容易排查。列表可以缓存几分钟，不必每次调用前都请求。

## 网关行为

- **由网关直接应答**：网关按工作空间的配置生成列表，不调用上游服务商、不计费；模型发现请求不写入日志列表。
- **列表不代表一定调得通**：网关生成列表时不检查服务商凭证当前是否可用，也不检查余额、预算和配额。列出的模型仍可能因凭证失效返回 503，或因余额不足返回 402，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)。
- **虚拟模型和 Auto 在调用时才检查**：它们实际选中的模型被模型策略禁止时，调用返回 403 `Request blocked by guardrail policy`。
- **接口能力要另行判断**：列表包含对话、向量、图像等各类模型。只给对话界面用时，按 `api_types` 或 `output_modalities` 筛选，见上文「常见用法」。
- **配置变化几秒后生效**：在模型广场开通或停用模型、启用或停用虚拟模型、修改模型策略后，几秒内反映到列表中。

## 常见错误

错误响应为 `{"error":{"message":"...","type":"...","code":"..."}}`，`code` 只有部分错误才有。

| 状态码 | `error.message` | `error.code` | 原因与处理 |
| --- | --- | --- | --- |
| 401 | `missing credentials` | — | 没有带 API Key，见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors) |
| 401 | `invalid api key` | — | 网关找不到这个 Key：复制不完整，或 Key 已删除、停用、过期，见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors) |
| 402 | `subscription expired; renew to continue` | — | 账户订阅已到期且已过宽限期，请当前账号管理员续费 |
| 403 | `api key expired` | — | Key 已过期 |
| 403 | `your IP address is not allowed` | — | 请求的出口 IP 不在 Key 的 IP 白名单中 |
| 503 | `Workspace model projection is unavailable` | `workspace_model_projection_unavailable` | 网关暂时读不到工作空间的模型配置，属于平台侧问题，稍后重试 |

- 用了 GET 以外的方法，或路径拼错（如 `/v1/models/` 末尾多了 `/`）时返回 404，响应体是 `{"error_msg":"404 Route Not Found"}`，外层没有 `error`。
- 完整错误码见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。

## 常见问题

### 列表里只有 `lyrouter/auto`，没有任何模型，怎么办？

**答：** 工作空间还没有开通任何模型，或者安全围栏的模型策略禁止了这个 Key 调用全部模型。在工作空间的 **模型广场** 确认「专属可用模型」不为空，再请当前账号管理员检查模型策略，见[如何选择模型](https://platform.lyrouter.com/ai_gateway/docs/choose)和[模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization)。

### 同一个模型由多个服务商提供，为什么列表里只有一条？

**答：** 模型 ID 与服务商无关，一个模型只有一个 ID。调用时网关按[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)选择服务商，实际命中的服务商在请求日志的「服务商」中查看。

### 列表里的 `id` 能直接用在图像、视频接口上吗？

**答：** 具体模型的 `id` 可以，前提是 `api_types` 或 `output_modalities` 表明它支持该接口。`lyrouter/auto` 和 `@vmodel/<名称>` 用在图像、视频接口上返回 403 `Model is not available in the model plaza`：`lyrouter/auto` 只适合 Chat Completions、Anthropic Messages 和 Responses；虚拟模型除这三个接口外，也可以用于[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)和[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank)，前提是它的模型列表全部是对应的向量或重排模型。