模型 — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 模型

列出并查询 API Key 可用的模型。

## 列出模型

```
GET <BASE_URL>/v1/models
```

### 查询参数

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `limit` | integer | 500 | 最大条数（1–1000） |

### 响应

```json
{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-chat",
      "object": "model",
      "name": "DeepSeek Chat",
      "context_length": 128000,
      "architecture": {
        "input_modalities": ["text"],
        "output_modalities": ["text"]
      },
      "supported_parameters": ["temperature", "max_tokens", "top_p"],
      "default_parameters": {"temperature": 0.7}
    }
  ]
}
```

仅返回 **对你的 API Key 可用** 的模型，不可用或已下线的模型不会出现在列表中。

## 获取单个模型

```
GET <BASE_URL>/v1/models/{id}
```

`{id}` 路径段支持斜杠（如 `deepseek/deepseek-chat`）。

### 响应

与列表 `data` 中单条对象相同。

### 错误

| HTTP | `error.code` | 原因 |
|------|--------------|------|
| 400 | — | 缺少 model id |
| 404 | `model_not_found` | 未知或不可用 |
| 502 | — | 模型列表暂时不可用 |

## 模型 id 格式

调用 Chat Completions 时，`model` 参数请使用 `GET /v1/models` 返回的 **`id`**（通常为 `{厂商}/{模型名}` 格式，例如 `deepseek/deepseek-chat`）。

**售价（输入 / 缓存输入 / 输出）** 不在本接口返回；请在 [开发者控制台 → 模型广场](https://console.supanexus.ai/models) 查看，详见 [模型定价](./model-pricing.md)。

## 响应字段说明

相比最小 OpenAI 模型对象，列表与详情可能包含以下附加信息：

| 字段 | 说明 |
|------|------|
| `name` | 展示名称 |
| `context_length` | 最大上下文长度 |
| `architecture` | 输入/输出模态（`input_modalities` / `output_modalities`；常见取值：`text`、`image`、`video`） |
| `supported_parameters` | 模型支持的参数 |
| `default_parameters` | 建议默认值 |

发图片或视频前，检查目标模型的 `architecture.input_modalities` 是否包含 `"image"` / `"video"`。

| 上游类型 | 推荐端点 | 请求格式 |
|----------|----------|----------|
| 非 Anthropic（OpenAI 兼容上游） | [`POST /v1/chat/completions`](./chat-completions.md) | `image_url`（URL 或 data URI）；`video_url`（**仅公网 http(s)**）— 见 [参数 → 多模态输入](./parameters.md) |
| `anthropic/*`（Anthropic Messages 上游） | [`POST /v1/messages`](./messages.md) | Anthropic image content blocks — 见 [Messages → 多模态输入](./messages.md)（视频不走此路径） |

跨协议发图（例如用 Chat Completions 调 Anthropic 模型，或用 Messages 调 OpenAI 上游模型）当前**不可靠**：图片可能被静默丢弃或被上游拒绝。请按上表选择端点。Whale **不支持** 将视频以 data URI 传入网关。

## 相关

- [Chat Completions](./chat-completions.md)
- [模型定价](./model-pricing.md)
- [参数](./parameters.md)