参数 — Markdown 源文
以下为可直接复制或提供给 AI Agent 的 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`
# 参数
`POST /v1/chat/completions` 请求参数说明。
## 必需
| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | `GET /v1/models` 中的模型 id |
| `messages` | array | OpenAI 聊天消息；`content` 可为字符串，也可为 content part 数组（文本 + 图片 / 视频等） |
## 常用可选参数
SupaNexus 在模型支持范围内 **透传** OpenAI 标准参数。可用性取决于模型 — 见模型对象的 `supported_parameters`。
| 参数 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `stream` | boolean | 是否**逐字流式**返回；聊天界面通常设为 `true`，批处理可设为 `false` | `"stream": true` |
| `temperature` | number | **随机程度**：越高越发散、越有创意；越低越稳定、越可重复。日常对话常用 `0.7`，事实问答可降到 `0`–`0.3` | `"temperature": 0.7` |
| `top_p` | number | 另一种控制随机性的方式（核采样），一般**与 temperature 二选一**微调即可 | `"top_p": 0.9` |
| `max_tokens` | integer | **回复长度上限**（token 数），防止一次生成过长或超出预算 | `"max_tokens": 1024` |
| `frequency_penalty` | number | **少重复同一用词**：越高越不爱「车轱辘话」 | `"frequency_penalty": 0.5` |
| `presence_penalty` | number | **鼓励聊新内容**：越高越不容易一直卡在同一个话题上 | `"presence_penalty": 0.3` |
| `stop` | string 或 array | 模型生成到这些**停止词**时结束；可用来截断列表、段落等 | `"stop": ["\n\n", "END"]` |
| `tools` | array | 告诉模型**可以调用哪些函数**（如查天气、查订单）；需模型支持 Function Calling | 见下方示例 |
| `tool_choice` | string 或 object | 是否必须调工具：`"auto"` 由模型决定，`"none"` 禁止，`"required"` 必须调 | `"tool_choice": "auto"` |
| `response_format` | object | 要求模型按**指定格式**输出，例如只要合法 JSON | `"response_format": {"type": "json_object"}` |
| `user` | string | **终端用户 id**（你的 App 里每个用户的标识），便于滥用追踪；OpenAI 模型还可提高 Prompt Cache 命中率 | `"user": "user-42"` |
`tools` 示例（简化）：
```json
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的当前天气",
"parameters": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "城市名，如 上海" }
},
"required": ["city"]
}
}
}
]
```
## 多模态输入
当模型支持视觉或视频时，`messages[].content` 可为 **content part 数组**（OpenAI 兼容格式）。
先通过 `GET /v1/models` 确认 `architecture.input_modalities`：含 `"image"` 可发图，含 `"video"` 可发视频。纯文本模型（仅 `["text"]`）不接受媒体。
### 图片（`image_url`）
#### URL 图片示例
```json
{
"model": "google/gemini-2.5-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "请描述这张图片的内容"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg"
}
}
]
}
]
}
```
#### Base64 图片示例
将 `image_url.url` 设为 data URI：
```json
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
}
```
Base64 会使请求体体积膨胀约 **33%**。默认请求体上限为 **64 MB**，超限返回 **413**（`error.code` = `request_too_large`）。大图建议使用公网可访问的 URL。
### 视频（`video_url`）
当 `input_modalities` 包含 `"video"`（例如 `minimax/minimax-m3`、`moonshot/kimi-k2.6`）时，可使用 `video_url` content part。
**Whale 第一版约定**：
| 允许 | 不允许 |
|------|--------|
| 公网 `http://` / `https://` 视频 URL（上游自行拉取） | `data:`（base64）、`file://`、`blob:`、厂商私有引用（如 `mm_file://`、`ms://`） |
非法 `video_url` 网关返回 **400**，不会转发到上游。视频勿用 data URI 过网关，以免占用平台带宽。
#### 公网视频 URL 示例
```json
{
"model": "minimax/minimax-m3",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "总结这个视频的主要内容"},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/demo.mp4",
"detail": "default"
}
}
]
}
]
}
```
部分上游还支持 `fps` 等抽帧字段，在模型支持范围内会透传。
### 限制：Anthropic 上游模型
用 OpenAI 客户端（`POST /v1/chat/completions`）调用 **`anthropic/*`** 时，网关会做协议转换并将消息压成纯文本，**图片会被静默丢弃且不报错**。发图请用 [`POST /v1/messages`](./messages.md)。
**建议**：发图时客户端协议与上游一致——`anthropic/*` 用 `/v1/messages`，其余用 `/v1/chat/completions`。
## 请求处理说明
### 识别的字段
- `model` — 本次调用的模型 id
- `stream` — 是否返回 SSE 流式响应
### 流式 usage
`stream: true` 时，响应末尾可能包含 `usage` 对象（取决于模型支持情况）。
### 其它参数
请求体中其余 JSON 字段在体积限制内按 OpenAI 兼容方式处理。
## 请求体大小限制
默认最大 **64 MB**（`GATEWAY_OPENAPI_MAX_REQUEST_BODY_BYTES`）。
超限返回 **413**，`error.code` 为 `request_too_large`。大图可用 data URI；**大视频必须用公网 URL**，不要把视频 base64 塞进请求体。
## 模型默认参数
`GET /v1/models` 中的 `default_parameters` 为建议默认值，客户端可在请求中覆盖。
## 相关
- [模型](./models.md)
- [Chat Completions](./chat-completions.md)
- [Messages（Anthropic）](./messages.md)
- [错误](./errors.md)