## 授权
### `Authorization`
- **类型** `string` · **位置** `header` · **必填**
- **认证方式** **HTTP: Bearer Auth**（Security Scheme Type: `http`）
- **说明** 请求头格式为 `Authorization: Bearer
`。请在 [公共参数](api-common.md) 中取得 API Key 并按 `Bearer` 方案传入。
## 请求头
### `Content-Type`
- **类型** 字符串枚举 · **默认值** `application/json` · **必填**
- **说明** 请求体媒介类型须为 `application/json`。
## 请求体
以下仅描述 **JSON 请求体** 内字段；**Authorization** 与 **Content-Type** 见上文「授权」「请求头」。
### `model`
- **类型** `string` · **必填**
- **说明** 模型 ID。**识图请使用 Flash 系列**：`deepseek-flash`（官方现名）或 `deepseek-v4-flash`（旧名）——两者是同一个模型、同一份定价，都能调用；平台转发时统一用官方现名。`deepseek-v4-pro` 不支持识图。
### `messages`
- **类型** `object[]` · **必填**
- **说明** 包含对话历史的消息列表。`content` 可以是纯字符串，也可以是内容块数组（`text` / `image_url` / `file`）。
#### Message 单条
- **`role`**（`enum`，必填）：`system` / `user` / `assistant`。
- **`content`**（`string | object[]`，必填）：文本字符串，或内容块数组。
- `{"type":"text","text":"..."}` —— 文本。
- `{"type":"image_url","image_url":{"url":"...","detail":"low"}}` —— 图片，见下方「图片输入」。
- `{"type":"file","file_id":"file-api-..."}` 或 `{"type":"file","file_data":"data:image/jpeg;base64,...","filename":"a.jpg"}` —— Files API 引用的图片。
> ⚠️ **图片只能出现在 `user` 消息中。** `system` / `assistant` 消息携带图片会返回 `400`（网关会提前拦下，不会打到上游）。
### `stream`
- **类型** `boolean` · **默认** `false`
- **说明** 是否流式返回（SSE）。网关会为流式请求自动补 `stream_options.include_usage`，以便末尾回传完整 usage 用于计费。
### 其他常用字段
- **`max_tokens`**（`integer`）：最大生成 token 数，上限 384K。
- **`temperature`** / **`top_p`**：采样参数。
- **`response_format`**：结构化输出。
- **`thinking`**：思考模式开关。
以上字段与[官方 Chat Completions](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion) 一致；网关**原样透传**请求体，只改写顶层 `model` 并补充 `stream_options`，因此官方支持的字段都能用。
---
## 图片输入
Flash 系列支持在文本之外输入图片：让模型描述图片、识别截图中的文字、分析图表等。支持 **JPEG、PNG、GIF、WebP** 四种格式（**由文件实际内容判断**，不看文件名或声明的 MIME 类型）。
共有三种传图方式，都使用标准的 OpenAI 兼容 `content` 块数组格式。
### 1. Base64 内联（`data:` URL）
图片编码后直接嵌入请求，适合本地文件。
```json
{
"model": "deepseek-v4-flash",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "这张图片里有什么？" },
{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64," } }
]
}
]
}
```
### 2. 外部图片 URL
传入可公开访问的 `http(s)` 链接，模型会自动下载。
```json
{ "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
```
### 3. Files API 引用
用 `file` 内容块承载 `file_id`（通过 Files API 上传的图片），适合多请求复用同一张图或图片较大导致请求体超限时：
```json
{ "type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx" }
```
也可以用 `file_data` 以 base64 形式内联（`file_id` 与 `file_data` 互斥）：
```json
{ "type": "file", "file_data": "data:image/jpeg;base64,", "filename": "image.jpg" }
```
### 细节级别 `detail`
`image_url` 可选填 `detail` 控制图片处理方式：
| 取值 | 行为 |
| --- | --- |
| `low` | 推理前将图片缩放到 512×512，更快更省 token |
| `high` | 保留原图（为兼容性提供，等价于 `original`） |
| `original` | 保留原图 |
| `auto` | 自动选择，当前等价于 `original` |
### 限制
| 限制项 | 数值 |
| --- | --- |
| 支持的格式 | JPEG、PNG、GIF、WebP（按文件内容判断） |
| 外部 URL 长度 | ≤ 8192 个字符 |
| 请求体大小 | **48 MiB** —— 指**整个请求体**（含 base64 膨胀后的字符数）。网关侧按此上限拦截，超出返回 `413` |
| 单张图片大小（base64 内联） | ≤ 32 MiB（指 base64 **解码后**的大小；base64 文本约 43 MiB） |
| 单张图片大小（外部 URL 指向的图片） | ≤ 32 MiB，由上游判断 —— 网关只能检查 URL 长度（≤ 8192 字符），不会去下载图片 |
| 单张图片大小（Files API `file_id`） | ≤ 64 MiB，由上游判断（网关只拿到一个 id） |
| 单个请求图片数 | ≤ 600 |
| 单个请求图片总大小 | 内联部分实际受**请求体 48 MiB 上限**约束（见下方说明）；含 `file_id` 时由上游按 200 MiB 判断 |
| 图片最大尺寸 | 单边 ≤ 8192 像素；请求含 15 张及以上图片时降为 4096 像素 |
| 出现位置 | **只能在 `user` 消息中**；`system` / `assistant` 中带图返回 `400` |
网关会**提前**拦截可离线判断的违规项 —— 图片数量、出现位置、外部 URL 长度、单张内联体积与内联总体积，返回 `400` 并给出具体原因。
> **注意：内联图片总体积实际上被请求体上限"包住"。** 网关内部虽然定义了 64 MiB 的内联总量阈值，但整个请求体上限是 **48 MiB**，而 base64 会膨胀约 4/3 —— 所以**请求体上限总是先触发**：内联图片合计可用的空间实际 ≤ 48 MiB（对应解码后约 36 MiB）。单张 32 MiB 上限仍在可达范围内（base64 约 43 MiB，能塞进 48 MiB）。若确实要传更多图片，请改用图片 URL 或 Files API 引用。
**图片真实格式与像素尺寸不做网关侧预检**：这两项需要解码图片内容（一张 32 MiB 的 base64 解码本身就要几十 MB 内存），交由上游判断；`file_id` 引用的图片大小同样交由上游判断。
### 图片如何计费
图片会按尺寸换算成 token，与文本 token 一起计入**输入 token**。每张图都会被自动缩放（总像素小于约 544×544 的放大、更大的缩到总像素约等于 1300×1300），因此**每张图消耗的 token 存在上限 1024**：2000×2000 与 5000×5000 的图片缩放后消耗相同。多张图片时每张独立计算。
> DeepSeek 官方采用**峰谷定价**（高峰时段为北京时间周一至周五 09:00–12:00、14:00–18:00，单价为空闲时段的 2 倍）；本站的实际计费以控制台展示的定价规则为准。
---
## 响应
非流式返回 OpenAI 兼容的 `choices[].message.content`；流式为 SSE（`data:` 事件）。两种情况下上游都会回传 `usage`，平台按其中的真实用量计费。
### `usage`
- **`prompt_tokens`**：输入 token 数（**含图片 token**）
- **`completion_tokens`**：输出 token 数
- **`prompt_cache_hit_tokens`** / **`prompt_cache_miss_tokens`**：上下文缓存的命中与未命中部分
- **`completion_tokens_details.reasoning_tokens`**：思维链 token 数
## 常见错误
| 状态码 | 场景 |
| --- | --- |
| `400` | 图片出现在 `system` / `assistant` 消息中；图片数量、URL 长度或体积超限；`model` 不存在或未启用 |
| `402` | 余额不足（在调用上游之前拦截） |
| `413` | 请求体超过 48 MiB |
| `503` | 模型所属供应商配置缺失或不可用 |