# 模型列表

> 列出与查询模型的接口：模型 id 格式、按 API Key 权限过滤的规则、scirouter 扩展字段与计价维度。

来源：https://www.scirouter.cn/docs/models · 更新于 2026-10-23

```http
GET https://api.scirouter.cn/v1/models
GET https://api.scirouter.cn/v1/models/{model_id}
```

返回调用所用 API Key 可调用的模型。响应格式与 OpenAI 模型接口一致，每个模型另带 `scirouter` 扩展字段；官方 SDK 忽略该字段，`client.models.list()` 可直接使用。

## 模型 id

模型 id 的格式为 `厂商/模型名`，调用时原样填入 `model` 字段。

| 部分 | 规则 |
|---|---|
| 厂商 | 接入该线路的厂商。以小写字母或数字开头，只含小写字母、数字、`.`、`_`、`-` |
| 模型名 | 以字母或数字开头，可含大写字母 |
| 整体 | 只含一个 `/`，不超过 160 个字符，区分大小写 |

模型 id 以列表接口的返回为准，不由展示名推断。示例中的 `YOUR_MODEL_ID` 为占位，使用时替换为列表中的 id。

## 列出模型

```bash
curl https://api.scirouter.cn/v1/models \
  -H "Authorization: Bearer $SCIROUTER_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "YOUR_MODEL_ID",
      "object": "model",
      "created": 1757894400,
      "owned_by": "…",
      "display_name": "…",
      "context_length": 128000,
      "scirouter": {
        "domain": "life-science",
        "display_name": "…",
        "status": "available",
        "pricing": [
          { "dimension": "input_tokens", "dimension_label": "输入", "unit": "1M tokens", "ratio_micro": 20000000 },
          { "dimension": "output_tokens", "dimension_label": "输出", "unit": "1M tokens", "ratio_micro": 60000000 }
        ],
        "features": ["tools", "vision", "reasoning", "json_mode"],
        "reasoning": { "controls": ["effort"], "efforts": ["low", "medium", "high"] },
        "supported_params": ["temperature", "top_p", "stop", "tools", "tool_choice", "response_format", "reasoning", "seed"],
        "emulated_params": ["parallel_tool_calls"]
      }
    }
  ]
}
```

倍率与上下文长度为示例值。

### 顶层字段

| 字段 | 说明 |
|---|---|
| `id` | 模型 id |
| `object` | 固定为 `model` |
| `created` | 模型在平台登记的时间，Unix 时间戳（秒） |
| `owned_by` | 厂商标识 |
| `display_name` | 展示名 |
| `context_length` | 上下文长度，单位 token。未登记上下文长度的模型不返回该字段 |

前四项是 OpenAI 的标准字段，`display_name` 与 `context_length` 是聚合平台的通行字段。SciRouter 作为上游接入其他平台时，对方读取模型列表顶层即可获得展示名与上下文长度。

### 权限过滤

列表按该 Key 当前的权限过滤，判定规则与调用时的授权相同。同时满足以下四项的模型才会列出，已停用的模型不列出：

1. Key 的模型白名单；
2. Key 所属项目的模型白名单；
3. 账户套餐；
4. 受限模型的团队授权。

因此同一账户下的不同 Key 可能得到不同的列表。列表中的模型均有调用权限，配额与限频另行判定。

| 情况 | 列表行为 | 调用结果 |
|---|---|---|
| `status` 为 `maintenance` | 列出 | 503 `model_unavailable`，`details.reason` 为 `model_offline` |
| 设为完全隐藏的受限模型 | 不列出，即使所在团队的项目 Key 已获授权 | 无权时 404 `model_not_found` |

该 Key 无法调用任何模型时，列表接口返回与调用相同的错误，不返回空列表：

| 状态码 | code | 触发条件 |
|---|---|---|
| 422 | `project_archived` | Key 所属项目已归档 |
| 404 | `project_not_found` | Key 所属项目不存在 |
| 404 | `team_not_found` | 团队项目的 Key 的所有者已不在该团队 |
| 403 | `team_suspended` | 团队已停用 |

## `scirouter` 扩展字段

| 字段 | 说明 |
|---|---|
| `domain` | 科研领域：`life-science`、`medicine`、`chemistry`、`materials`、`physics`、`math`、`earth`、`agriculture`、`environment`、`engineering`、`cs`、`general` |
| `display_name` | 展示名 |
| `status` | `available`：正常；`degraded`：部分线路异常，仍可调用；`maintenance`：维护中，调用返回 503 |
| `pricing` | 计价维度列表，见[计价维度](#计价维度) |
| `context_tiers` | 长上下文分档，见[长上下文分档](#长上下文分档)。不分档的模型不返回该字段 |
| `variant_of` / `variant` | 变体的基础模型 id 与后缀（如 `fast`）；非变体为 `null`。变体是单独定价的独立模型，见 [Messages（Anthropic 格式）](https://www.scirouter.cn/docs/messages) |
| `variant_params` | 仅变体返回。调用该变体时平台强制写入请求的参数，格式为 `[{ "path", "value" }]`：`path` 为点分路径（如 `speed`、`thinking.type`），`value` 为原样的 JSON。请求中的同名字段以此为准。只强制 beta 的变体不返回该字段 |
| `variant_betas` | 仅变体返回。调用该变体时平台并入 `anthropic-beta` 请求头的值；未强制 beta 的变体不返回该字段 |
| `variant_switch_formats` | 仅变体返回，取值 `openai` / `anthropic`。以列出的格式调用基础模型、并带齐取值相同的 `variant_params` 时，平台自动改用该变体并按其计价。不返回该字段表示不会自动改用，需将 `model` 设为变体的 id |
| `features` | 模型声明的能力标识，如 `tools`、`vision`、`reasoning`、`json_mode`、`structured_output`、`logprobs`、`seed`、`prompt_cache`、`audio`。需要某项能力的参数，模型未声明该能力时无法带到线路上 |
| `reasoning` | 思考控制方式；不返回表示模型不思考。`controls` 为支持的控制方式（`toggle` 开关、`effort` 强度、`budget` 预算的子集），`efforts` 为 `effort` 方式支持的档位。请求的强度不在其中时平台降档，见[参数如何被处理](https://www.scirouter.cn/docs/params) |
| `supported_params` | 原生支持或经翻译可带到线路上的标准参数，取模型当前启用线路的并集。不在其中的提示类参数被去掉并留痕，契约类参数返回 400 |
| `emulated_params` | 线路不支持、由平台模拟的参数，范围为 `stop`、`response_format`、`tool_choice`、`parallel_tool_calls` 与向量接口的 `encoding_format` |
| `kind` | 模型种类：`chat`（对话接口）、`embedding`（向量接口）、`image`（[图片接口](https://www.scirouter.cn/docs/images)）、`video` 与 `speech`（仅限站内百宝箱）。调用种类不符的接口返回 400 `validation_failed`，`details.reason` 为 `model_kind_mismatch` |
| `image` | 仅生图模型返回，说明图片接口接受的参数，见下表 |

`features`、`reasoning`、`supported_params`、`emulated_params` 是模型的能力自述，随平台配置与线路启停变化，以调用时的值为准。各参数无法带到线路上时的处理方式见[参数如何被处理](https://www.scirouter.cn/docs/params)。

`image` 的字段：

| 字段 | 说明 |
|---|---|
| `sizes` | 尺寸。`presets`：标准尺寸；`auto`：是否接受自动尺寸；`custom`：任意尺寸的约束 `{multiple_of, min_pixels, max_pixels, max_edge, max_ratio}`；`default`：缺省尺寸 |
| `qualities` / `quality_auto` / `default_quality` | 支持的质量档位、是否接受自动质量、缺省质量 |
| `output_formats` | 支持的输出格式 |
| `transparent` | 是否支持透明背景 |
| `edit` | 改图能力 `{max_images, mask, input_fidelity}`；不支持改图时为 `null` |
| `variations` | 变体生成方式：`native`、`via_edit` 或 `none` |
| `max_outputs` | 单次请求最多生成的张数 |
| `metering` | 计量方式：`tokens` 按 token，`per_image` 按张 |

### 计价维度

`pricing` 的每一项：

| 字段 | 说明 |
|---|---|
| `dimension` | 计价维度，如 `input_tokens`、`output_tokens`、`cached_input_tokens`、`reasoning_tokens`（见[多厂商差异](https://www.scirouter.cn/docs/vendors)）；生图模型为 `image_input_tokens`、`cached_image_input_tokens`、`image_output_tokens`（见[图片](https://www.scirouter.cn/docs/images)） |
| `dimension_label` | 维度的展示名 |
| `unit` | 展示粒度，如 `1M tokens`。仅用于展示，不参与计价 |
| `ratio_micro` | 定点倍率，`1000000` 表示 1.0 倍：该维度每 1 个计量单位（1 个 token）扣除的配额 |
| `tiers` | 可选。`[{ "from", "ratio_micro" }]`：用量达到 `from` 后整笔按该档计价，不累进 |
| `min_billable` | 可选。最小计费量，不足时按该值计 |

### 长上下文分档

`context_tiers` 的每一档为 `{ "above_prompt_tokens", "ratios" }`。单次请求的输入合计（普通输入、缓存命中、缓存写入与 1 小时缓存写入之和）超过 `above_prompt_tokens` 时（等于不算），整笔按该档计价：`ratios` 中列出的维度使用该档倍率，未列出的维度沿用基础倍率。同时超过多档时，取阈值最高的一档。

### 实际扣费

实际扣费还要乘以模型倍率，模型倍率不在本接口返回，因此不能用本接口的数值自行计算费用。单次调用的扣费见响应中的 `scirouter.cost_quota`；各模型的完整价格表见[模型中心](https://www.scirouter.cn/models)的详情页。

`pricing` 与 `context_tiers` 是读取列表时生效的价格。平台可随时调价，也可预先设定将来某一时刻生效的新价格；每次调用按请求开始时生效的价格结算。程序中不要长期缓存或写死价格，使用前重新读取列表。

## 查询单个模型

```bash
curl https://api.scirouter.cn/v1/models/YOUR_MODEL_ID \
  -H "Authorization: Bearer $SCIROUTER_API_KEY"
```

- 模型 id 中的 `/` 直接写入路径，写成 `%2F` 也可识别。
- 可使用平台为模型配置的别名，响应中的 `id` 为平台的模型 id。
- 列表中看不到的模型返回 404 `model_not_found`，不存在与无权调用不作区分。完全隐藏的受限模型在调用时同样返回 404。
- 调用接口对白名单外的模型返回 403 `model_not_allowed`，与本接口不同。

## Anthropic 格式

请求带 `anthropic-version` 请求头时（Claude Code 与 Anthropic SDK 会自动携带），两个接口均按 Anthropic 的格式返回，见 [Messages（Anthropic 格式）](https://www.scirouter.cn/docs/messages)。

## 选择模型

列表接口供程序读取。比较模型的能力、上下文长度、价格与近期可用率，使用[模型中心](https://www.scirouter.cn/models)：可按领域筛选，最多并排对比五个模型。