# 查询模型列表

查询当前凭据可调用的 Genesis 模型。响应中的模型 ID 可作为 Chat Completions、Responses、Embeddings 或 Rerank 请求的 `model` 字段。

```text
GET https://token.moi.matrixorigin.cn/v1/models
```

## 调用前准备

查询地址为 `https://token.moi.matrixorigin.cn/v1/models`。准备具有 Genesis 权限的访问凭据。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际访问令牌或服务账号 API Key，通过 `Authorization` Header 传递。不要将凭据写入源代码、镜像或日志。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。 |
| `Accept` | 否 | 可设置为 `application/json`。 |

## 请求示例

```bash
curl "https://token.moi.matrixorigin.cn/v1/models" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Accept: application/json'
```

请求不需要请求体。只使用响应实际返回的模型 ID。

## 获取模型 ID

1. 运行上面的请求示例。
2. 从成功响应的 `data[]` 中复制要调用的模型 `id`。
3. 将该值填入后续 Chat Completions、Responses、Embeddings 或 Rerank 请求的 `model` 字段。

## 成功响应

成功响应返回当前凭据可调用的模型列表：

```json
{
  "object": "list",
  "data": [
    {
      "id": "<MODEL_ID>"
    }
  ]
}
```

响应中用于选择模型的字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`data[].id` 表示 `data` 数组中每一项的 `id` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 列表响应的对象类型。 |
| `data` | array | 当前凭据可调用的模型列表。没有可调用模型时可为空数组。 |
| `data[].id` | string | 模型的稳定标识。将该值原样传入后续请求的 `model` 字段。 |

## 错误响应

此接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要继续读取 `data[]`。错误正文由兼容的模型服务返回；`error.message` 可用于展示或记录，`error.type`、`error.code` 仅在响应实际包含时使用。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

错误正文中可能出现的字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误对象。 |
| `error.message` | string | 可读错误信息。不要将其中可能包含的敏感输入写入日志。 |
| `error.type` | string，可选 | 上游提供的错误类别；可能省略。 |
| `error.code` | string 或 null，可选 | 上游提供的错误代码；可能省略或为 `null`。 |

### 常见 HTTP 错误

下表说明收到不同 HTTP 状态时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `401`
  - —
  - 缺少、无效或已失效的访问凭据。
  - 检查 `Authorization` Header 和凭据状态。
* - `403`
  - —
  - 当前凭据没有 Genesis 或目标模型的访问权限。
  - 检查凭据对应的 Genesis 权限和模型范围。
* - `404`
  - —
  - 请求地址错误。
  - 使用 `https://token.moi.matrixorigin.cn/v1/models`。
* - `429`
  - —
  - 当前请求受到速率、并发或额度限制。
  - 降低请求频率后再次查询。
* - `5xx`
  - —
  - 服务或依赖暂时无法处理请求。
  - 稍后再次查询。
```

## 后续操作

- [Chat Completions](chat-completions.md)
- [Responses](responses.md)
- [Embeddings](embeddings.md)
- [Rerank](rerank.md)