> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 列出模型

> 获取当前账户可用的模型标识。

`GET /api/v1/cloud/models`

列出当前账户可用的已启用模型。创建或更新 Agent 时，可使用这里返回的 `id` 作为 `model` 值。

## 请求头

| 头部              | 必选 | 说明             |
| --------------- | -- | -------------- |
| `Authorization` | 是  | `Bearer <PAT>` |

## 查询参数

该接口当前不支持查询参数。

## 示例请求

```bash theme={null}
curl -X GET "https://api.qoder.com/api/v1/cloud/models" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "ultimate",
      "type": "model",
      "display_name": "Ultimate",
      "source": "system",
      "is_enabled": true,
      "is_new": false,
      "price_factor": 1.6,
      "efforts": ["low", "medium", "high", "xhigh", "max"],
      "default_effort": "high",
      "max_input_tokens": 1000000,
      "default_context_window": 200000,
      "available_context_windows": [200000, 400000, 1000000]
    }
  ],
  "has_more": false
}
```

## 响应字段

| 字段         | 类型      | 说明                                                            |
| ---------- | ------- | ------------------------------------------------------------- |
| `data`     | array   | 可用 [Model 对象](/zh/cloud-agents/api/models/schemas#model-对象)数组 |
| `has_more` | boolean | 固定为 `false`；模型列表当前不分页                                         |

`data` 中每个模型对象包含：

| 字段                          | 类型         | 说明                                                              |
| --------------------------- | ---------- | --------------------------------------------------------------- |
| `id`                        | string     | 模型标识，创建或更新 Agent 时传入 `model` 字段                                 |
| `type`                      | string     | 固定为 `"model"`                                                   |
| `display_name`              | string     | 面向用户展示的模型名称                                                     |
| `source`                    | string     | 模型来源，通常为 `system`；账号专属模型为 `user`                                |
| `is_enabled`                | boolean    | 模型是否启用且可用                                                       |
| `is_new`                    | boolean    | 是否标记为新模型                                                        |
| `price_factor`              | number     | 可选，相对价格倍率                                                       |
| `efforts`                   | array      | 可选，支持的推理 effort 等级，如 `none`、`low`、`medium`、`high`、`xhigh`、`max` |
| `default_effort`            | string     | 可选，上游模型目录指定的默认 effort 等级                                        |
| `max_input_tokens`          | integer    | 模型支持的最大输入上下文（token 数）                                           |
| `default_context_window`    | integer    | 可选，Agent 未设置 `model.context_window` 时使用的默认上下文窗口（token 数）        |
| `available_context_windows` | integer 数组 | 可选，创建/更新 Agent 时 `model.context_window` 可选的上下文窗口档位（token 数）     |

## 注意事项

* 只返回已启用模型。
* 响应不会包含内部路由、供应商、密钥或 `description` 字段。
* 模型目录会按当前认证用户和服务端配置的 scene 解析；默认 scene 为 `assistant`。

## 错误码

| HTTP | type                   | 触发条件      |
| ---- | ---------------------- | --------- |
| 401  | `authentication_error` | PAT 无效或过期 |
| 503  | `api_error`            | 模型目录暂时不可用 |

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="定义 Agent" icon="user-gear" href="/zh/cloud-agents/define-agent">
    创建可复用、可版本化的 Agent 配置。
  </Card>
</CardGroup>