# Models

列出当前密钥(分组)可用的模型。

```text
GET https://api.clomio.ai/v1/models
```

> 当前网关只暴露模型列表路由,**没有** `GET /v1/models/{id}`。想确认某个模型是否可用,请看列表返回值或直接发一次最小请求。
>
> Gemini 原生模型列表不是本页 `/v1/models`:Gemini 分组使用 `GET /v1beta/models`，单模型查询使用 `GET /v1beta/models/{model}`。不要把 Gemini 的单模型查询写成 `GET /v1/models/{id}`。

---

## 请求头

| 请求头 | 必填 | 值 |
|--------|:----:|-----|
| `Authorization` | 是* | `Bearer 你的密钥` |
| `x-api-key` | 是* | 你的密钥 |
| `x-goog-api-key` | 是* | 你的密钥，兼容部分 Google 风格客户端 |

> \* 三种 Key 头任选其一即可。不要把 Key 放进 `?key=` 或 `?api_key=` query；普通 `/v1` 网关会返回 400 `api_key_in_query_deprecated`。`GET /v1/models` 不需要 `Content-Type`。

---

## 响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `object` | string | `list` |
| `data` | array | 模型数组;每项唯一稳定字段是 `id`,其他字段随平台/来源变化 |

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4", "object": "model", "owned_by": "clomio" },
    { "id": "claude-sonnet-4-6", "object": "model", "owned_by": "clomio" }
  ]
}
```

> 返回的具体模型取决于你密钥所在的[分组](#/api-key)。同一个模型名还可能经过控制台的模型映射转发到上游实际模型,使用记录里会记录实际用量。

### data[] 字段不是固定 OpenAI 官方形态

`/v1/models` 的顶层稳定为 `object:"list"` 和 `data:[...]`;`data[]` 里只应把 `id` 当作稳定字段。OpenAI 默认/自定义列表可能有 `object`、`created`、`owned_by`、`type`、`display_name`;映射聚合列表、Claude/Kiro/Gemini/Grok 经 `/v1/models` 暴露时,可能只有 `id`、`type`、`display_name`、`created_at` 或省略 `created/owned_by`。兼容客户端不要强校验每项都必须是 OpenAI 官方 `model` object。

模型列表有短缓存；控制台模型列表或分组能力刚变化后，短时间内可能仍看到旧结果。

## 模型名从哪里来

`GET /v1/models` 展示的是**当前密钥分组可请求的模型名**，通常是客户端可填写的请求模型名/别名，不是某个上游厂商的完整官方清单。它会综合当前分组开放模型、可用别名、平台默认模型列表以及已开放的兼容能力。

因此请区分:

| 名称 | 出现位置 | 含义 |
|------|----------|------|
| 请求模型 | 请求体 `model`、`/v1/models` 列表 | 客户端允许填写的名字,可能是别名 |
| 路由/映射模型 | 控制台模型映射、分组默认路由 | 网关用于改写上游请求的中间结果 |
| 上游真实模型 | 控制台用量明细里的上游模型 | 实际发给上游供应商的模型,可能不同于请求模型 |

排查“我明明请求了 A,为什么像 B”时,优先看控制台用量明细里的**请求模型**和**上游模型**;不要只凭 `/v1/models` 判断上游真实模型。

---

## 示例:列出所有模型

```bash
curl https://api.clomio.ai/v1/models \
  -H "Authorization: Bearer 你的密钥"
```

```python
from openai import OpenAI
client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1")

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

```javascript
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" });

const models = await client.models.list();
for (const m of models.data) console.log(m.id);
```

---

## 示例:在 Shell 中判断模型是否存在

```bash
curl -s https://api.clomio.ai/v1/models   -H "Authorization: Bearer 你的密钥" | jq -r '.data[].id' | grep -Fx 'gpt-5.4'
```

有输出说明当前密钥分组里能看到该模型;没有输出则换模型名或换分组。

---

## 常见模型错误怎么区分

| 关键词 | 含义 | 处理 |
|--------|------|------|
| `The current group does not support the requested model "xxx". Available models: ...` | 当前密钥分组明确不支持请求模型 | 按 `Available models` 换模型,或换到支持该模型的分组 |
| `model_not_found` / `Model "xxx" is not supported by any configured account in this group` | 当前分组不支持该模型 | 核对模型名和分组模型清单 |
| `No available accounts supporting model: xxx` | 当前暂时无法提供该模型 | 先看 `/v1/models`;持续出现带 request_id 工单 |
| `No available accounts` | 当前服务暂时没有可用资源 | 稍后重试、换线路或降低并发 |
| `This group does not allow /v1/messages dispatch` | OpenAI 分组未开启 Claude Messages 形状转 OpenAI 的 dispatch | 改走 `/v1/responses` 或 `/v1/chat/completions`,或换到允许 dispatch 的 OpenAI 分组 |

> `/v1/models` 只返回当前密钥分组可见的模型列表;没有 `GET /v1/models/{id}`。模型名是否最终映射到另一个上游真实模型,以控制台用量记录为准。

---

> 拿到模型名后,填进对话/图像等请求的 `model` 字段。怎么挑模型见 [模型选择指南](#/models)。

## 字段与查询约束

`GET /v1/models` 不接受请求体；Key 通过 `Authorization`、`x-api-key` 或 `x-goog-api-key` 三选一传入。`client_version` 为 Codex 客户端专用查询参数，存在时可能返回 Codex manifest 形态而不是普通 OpenAI list。

| 查询 | 可选值/范围 | 说明 |
|---|---|---|
| `client_version` | 客户端版本字符串 | 仅 Codex 模型选择器使用；普通 SDK 不要传 |

## 完整错误响应

```json
{"error":{"type":"authentication_error","message":"Invalid API key"}}
```

| HTTP | 典型错误 | 处理 |
|---:|---|---|
| 400 | `api_key_in_query_deprecated` | 把 Key 从 query 移到 header |
| 401 | `API key required` / `Invalid API key` | 检查 Key、状态和用户 |
| 403 | 未分组、订阅或 IP 限制 | 在控制台绑定正确分组 |
| 429 | 请求频率过高 | 缓存模型列表并退避 |
| 503 | 服务暂时不可用 | 稍后重试并带 request_id |