# 查询可调用模型

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

查询当前凭据可见且已启用的 Genesis 模型，获取调用标识和能力。模型列表用于发现模型，不保证每个模型都支持所有同类型调用接口。

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

## 调用前准备

准备用于 Genesis 调用的个人访问令牌或服务账号 API Key。创建和权限配置参阅[管理 Genesis 访问凭据](../../../guides/genesis/api-keys.md#选择凭据类型)。

## 查询参数

将 `$GENESIS_ACCESS_TOKEN` 替换为个人访问令牌或服务账号 API Key。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -G "https://token.moi.matrixorigin.cn/v1/models" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  --data-urlencode "type=chat"
```

:::::
:::::{tab-item} 参数说明

::::{div} mo-api-parameter-table

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `type` | string | 否 | 按模型类型筛选：`chat`、`embedding` 或 `rerank`。`chat` 只表示对话模型，不保证模型支持所有对话生成接口。省略或传入 `all` 时返回当前凭据可见的全部类型。 |

::::

:::::
::::::
:::::::

## 凭据与权限

个人访问令牌、服务账号 API Key 和 OAuth 服务账号访问令牌使用 `Authorization: Bearer`。本地 `sk-mo-` 令牌仅在部署启用本地令牌功能时可用，接受 Bearer 或 `X-API-Key`；其他凭据不能放入 `X-API-Key`。

每次请求只提交一种凭据，不在查询参数中传凭据。多个认证头、重复认证头或格式不明确的凭据返回 `400` / `ambiguous_credential`；缺失或无效凭据返回 `401` / `invalid_api_key`。OAuth 凭据必须通过服务账号类型、受众、有效期等校验，不能用管理 JWT 或浏览器 Cookie 替代。

服务账号需具备 `models.read` 能力；结果还受账号目录、服务账号的有效模型策略和可用企业套餐约束。身份验证可能更新本地令牌的最近调用时间、刷新个人令牌或更新服务账号投影，因此模型列表查询也可能产生身份维护写入。

## 成功响应

成功时返回当前凭据可见且已启用的模型列表及模型信息。模型是否支持具体调用接口，还取决于 `capabilities` 和当前可用的模型路由。

该接口不返回模型价格。返回的能力标签用于选择协议，不能作为提供方最终可用性的保证。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "object": "list",
  "data": [
    {
      "id": "example-chat-model",
      "object": "model",
      "type": "chat",
      "sub_type": "text",
      "capabilities": [
        "messages"
      ],
      "created": 1780000000,
      "owned_by": "taas",
      "context_window": 32768,
      "max_output_tokens": 4096
    }
  ]
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 固定为 `list`。 |
| `data` | array of object | 筛选后当前凭据可见且已启用的模型。列表中的模型不一定支持所有同类型调用接口。 |
| `data[].id` | string | 模型调用标识，填入推理请求的 `model`。 |
| `data[].object` | string | 固定为 `model`。 |
| `data[].type` | string | 模型类型：`chat`、`embedding` 或 `rerank`。`chat` 表示模型家族，不等同于支持 Chat Completions。 |
| `data[].sub_type` | string | 输入子类型：`text` 或 `multimodal`。 |
| `data[].capabilities` | array of string | 公开协议标签：普通模型目录保留 vision、messages、responses；企业套餐的模型能力由可用通道确定。未返回某个标签不能由客户端补造。 |
| `data[].created` | integer | 模型创建时间，Unix 秒级时间戳。 |
| `data[].owned_by` | string | 模型归属标记，返回 `taas`。 |

:::::
::::::
:::::::

## 错误响应

未提供有效凭据时返回 HTTP `401`。检查访问凭据是否有效，并在请求中携带认证信息。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "error": {
    "message": "Invalid or missing TaaS API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误信息。 |
| `error.message` | string | 凭据缺失或无效的说明。 |
| `error.type` | string | 错误类别。 |
| `error.code` | string | 错误代码。 |

:::::
::::::
:::::::

## 后续操作

将 `data[].id` 作为 `model` 传入推理请求。按目标接口选择模型：

- [Messages](text-generation/anthropic-messages.md)：选择 `capabilities` 包含 `messages` 的模型。
- [Responses](text-generation/responses.md)：选择 `capabilities` 包含 `responses` 的模型。
- [Embeddings](text-embeddings/embeddings.md) 和 [Rerank](text-reranking/rerank.md)：根据模型的 type 及对应接口支持的输入形式选择模型。
- [Chat Completions](text-generation/chat-completions.md)：先使用 `type=chat` 缩小模型范围。当前模型列表不提供 Chat Completions 专用能力标签；如果调用返回 `endpoint_capability_mismatch`，请选择其他 `chat` 模型。