Blame for API.md

# DS2API 接口文档1

语言 / Language: [中文](API.md) | [English](API.en.md)

本文档描述当前 Go 代码库的实际 API 行为。

文档导航：[总览](README.MD) / [架构说明](docs/ARCHITECTURE.md) / [部署指南](docs/DEPLOY.md) / [测试指南](docs/TESTING.md) / [上下文兼容流程](docs/prompt-compatibility.md)

---

## 目录

- [基础信息](#基础信息)
- [配置最佳实践](#配置最佳实践)
- [鉴权规则](#鉴权规则)
- [路由总览](#路由总览)
- [健康检查](#健康检查)
- [OpenAI 兼容接口](#openai-兼容接口)
- [Claude 兼容接口](#claude-兼容接口)
- [Gemini 兼容接口](#gemini-兼容接口)
- [Ollama 兼容接口](#ollama-兼容接口)
- [Admin 接口](#admin-接口)
- [错误响应格式](#错误响应格式)
- [cURL 示例](#curl-示例)

---

## 基础信息

| 项目 | 说明 |
| --- | --- |
| Base URL | `http://localhost:5001` 或你的部署域名 |
| 默认 Content-Type | `application/json` |
| 健康检查 | `GET /healthz`、`GET /readyz` |
| CORS | 已启用（统一覆盖 `/v1/*`、`/anthropic/*`、`/v1beta/models/*`、`/api/*`、`/admin/*`；浏览器有 `Origin` 时回显该 Origin，否则为 `*`；默认允许 `Content-Type`, `Authorization`, `X-API-Key`, `X-Ds2-Target-Account`, `X-Ds2-Source`, `X-Vercel-Protection-Bypass`, `X-Goog-Api-Key`, `Anthropic-Version`, `Anthropic-Beta`，并会放行预检里声明的第三方请求头，如 `x-stainless-*`；Vercel 上 `/v1/chat/completions` 的 Node Runtime 也对齐相同行为；内部专用头 `X-Ds2-Internal-Token` 仍被拦截） |

- 所有 JSON 请求体都必须是合法 UTF-8；非法字节序列会在入站阶段被拒绝为 `400 invalid json`。

### 3.0 接口适配层说明

- OpenAI / Claude / Gemini 三套协议已统一挂在同一 `chi` 路由树上，由 `internal/server/router.go` 负责装配。
- 适配器层职责收敛为：**请求归一化 → DeepSeek 调用 → 协议形态渲染**，减少历史版本中“同能力多处实现”的分叉。
- 从协议请求到纯文本 web-chat prompt 的完整链路（统一标准请求、思考格式注入、历史拆分、完成载荷组装、响应归档）见 [docs/prompt-compatibility.md](docs/prompt-compatibility.md)，该文是这条流程的源文档；本文只描述各接口的可见字段与响应形态。
- Tool Calling 的解析策略在 Go 与 Node Runtime 间保持一致：推荐模型输出半角管道符 DSML 外壳 `<|DSML|tool_calls>` → `<|DSML|invoke name="...">` → `<|DSML|parameter name="...">`；兼容层也接受 DSML wrapper 别名 `<dsml|tool_calls>`、`<|tool_calls>`、常见 DSML 分隔符漏写形态（如 `<|DSML tool_calls>`）、`DSML` 与工具标签名黏连的常见 typo（如 `<DSMLtool_calls>`）、控制分隔符漂移（如 `<DSML␂tool_calls>` / 原始 STX `\x02`）、CJK 尖括号、全角感叹号、顿号、PascalCase 本地名、弯引号属性值与属性尾部分隔符漂移（如 `<DSM|parameter name="command"|>...〈/DSM|parameter〉` / `<！DSML！invoke name=“Bash”>` / `<、DSML、tool_calls>` / `<DSmartToolCalls>` / `<DSMLtool_calls※>`）、任意协议前缀壳（如 `<proto💥tool_calls>`），以及旧式 canonical XML `<tool_calls>` → `<invoke name="...">` → `<parameter name="...">`。实现上采用结构扫描：只要固定本地标签名是 `tool_calls` / `invoke` / `parameter`，标签名前或标签名后的非结构性分隔符会在解析入口归一化；CDATA 开头也会容错 `<！[CDATA[` / `<、[CDATA[` 这类分隔符漂移；只有 `tool_calls` wrapper 或可修复的缺失 opening wrapper 会进入工具路径，裸 `<invoke>` 不计为已支持语法；流式场景继续执行防泄漏筛分。若参数体本身是合法 JSON 字面量（如 `123`、`true`、`null`、数组或对象），会按结构化值输出，不再一律当作字符串；显式空字符串和纯空白参数会结构化保留为空字符串，是否拒绝缺参由工具执行侧决定；完整但 malformed 的 wrapper 会作为普通文本释放，不会吞掉或伪造成工具调用；若 CDATA 偶发漏闭合，则会在最终 parse / flush 恢复阶段做窄修复，尽量保住已完整包裹的外层工具调用。
- `Admin API` 将配置与运行时策略分开：`/admin/config*` 管静态配置，`/admin/settings*` 管运行时行为。
- 当上游返回 thinking-only 响应（模型输出了推理链但无可见文本）时，Go 主路径与 Vercel Node 流式路径都会先自动重试一次：以多轮对话 follow-up 方式追加 prompt 后缀 `"Please provide a non-empty final answer or tool call."` 并设置 `parent_message_id` 在同一 DeepSeek session 内让模型重新输出；同账号重试最大 1 次。若同账号重试后仍即将返回 `429 upstream_empty_output`，托管账号模式会在返回 429 前自动切换到下一个可用账号，新建 session，用原始 payload 再 fresh retry 一次。
- 引用标记处理边界：流式输出默认隐藏 `[citation:N]` / `[reference:N]` 这类上游内部占位符；非流式输出默认把 DeepSeek 搜索引用标记转换为 Markdown 引用链接。

---

## 配置最佳实践

推荐把 `config.json` 作为唯一配置源：

```bash
cp config.example.json config.json
# 编辑 config.json（keys/accounts）
```

按部署方式使用：

- 本地运行：直接读取 `config.json`
- Docker / Vercel：从 `config.json` 生成 Base64，填入 `DS2API_CONFIG_JSON`，也可以直接填原始 JSON

```bash
DS2API_CONFIG_JSON="$(base64 < config.json | tr -d '\n')"
```

Vercel 一键部署可先只填 `DS2API_ADMIN_KEY`，部署后在 `/admin` 导入配置，再通过 “Vercel 同步” 写回环境变量。

---

## 鉴权规则

### 业务接口（`/v1/*`、`/anthropic/*`、`/v1beta/models/*`）

支持两种传参方式：

| 方式 | 示例 |
| --- | --- |
| Bearer Token | `Authorization: Bearer <token>` |
| API Key Header | `x-api-key: <token>`（无 `Bearer` 前缀） |
| Gemini 兼容 | `x-goog-api-key: <token>` 或 `?key=<token>` / `?api_key=<token>` |

**鉴权行为**：

- token 在 `config.keys` 中 → **托管账号模式**，自动轮询选择账号
- token 不在 `config.keys` 中 → **直通 token 模式**，直接作为 DeepSeek token 使用

**可选请求头**：`X-Ds2-Target-Account: <email_or_mobile>` — 指定使用某个托管账号；如果目标账号不存在，或管理账号队列已耗尽，相关业务请求会返回 `429`，当前不会附带 `Retry-After` 头。若账号存在但登录/刷新失败，则返回对应的 `401` 或上游错误。未指定目标账号时，托管账号模式的 completion 空输出 429 会先尝试切到另一个可用账号 fresh retry 一次；指定目标账号或无其他可用账号时不会切号。
Gemini 兼容客户端还可以使用 `x-goog-api-key`、`?key=` 或 `?api_key=` 作为凭据来源。

### Admin 接口（`/admin/*`）

| 端点 | 鉴权 |
| --- | --- |
| `POST /admin/login` | 无需鉴权 |
| `GET /admin/verify` | `Authorization: Bearer <jwt>`（仅 JWT） |
| 其他 `/admin/*` | `Authorization: Bearer <jwt>` 或 `Authorization: Bearer <admin_key>`（直传管理密钥） |

---

## 路由总览

| 方法 | 路径 | 鉴权 | 说明 |
| --- | --- | --- | --- |
| GET | `/healthz` | 无 | 存活探针 |
| HEAD | `/healthz` | 无 | 存活探针（无响应体） |
| GET | `/readyz` | 无 | 就绪探针 |
| HEAD | `/readyz` | 无 | 就绪探针（无响应体） |
| GET | `/v1/models` | 无 | OpenAI 模型列表 |
| GET | `/v1/models/{id}` | 无 | OpenAI 单模型查询（支持 alias 入参） |
| POST | `/v1/chat/completions` | 业务 | OpenAI 对话补全 |
| POST | `/v1/responses` | 业务 | OpenAI Responses 接口（流式/非流式） |
| GET | `/v1/responses/{response_id}` | 业务 | 查询已生成 response（内存 TTL） |
| POST | `/v1/embeddings` | 业务 | OpenAI Embeddings 接口 |
| POST | `/v1/files` | 业务 | OpenAI Files 上传（multipart/form-data） |
| GET | `/v1/files/{file_id}` | 业务 | 查询已上传文件状态 |
| GET | `/anthropic/v1/models` | 无 | Claude 模型列表 |
| POST | `/anthropic/v1/messages` | 业务 | Claude 消息接口 |
| POST | `/anthropic/v1/messages/count_tokens` | 业务 | Claude token 计数 |
| POST | `/v1/messages` | 业务 | Claude 消息快捷路径 |
| POST | `/messages` | 业务 | Claude 消息快捷路径 |
| POST | `/v1/messages/count_tokens` | 业务 | Claude token 计数快捷路径 |
| POST | `/messages/count_tokens` | 业务 | Claude token 计数快捷路径 |
| POST | `/v1beta/models/{model}:generateContent` | 业务 | Gemini 非流式 |
| POST | `/v1beta/models/{model}:streamGenerateContent` | 业务 | Gemini 流式 |
| POST | `/v1/models/{model}:generateContent` | 业务 | Gemini 非流式兼容路径 |
| POST | `/v1/models/{model}:streamGenerateContent` | 业务 | Gemini 流式兼容路径 |
| GET | `/api/version` | 无 | Ollama 版本接口 |
| GET | `/api/tags` | 无 | Ollama 模型列表 |
| POST | `/api/show` | 无 | Ollama 单模型能力查询（返回 `id` 与 `capabilities`） |
| POST | `/admin/login` | 无 | 管理登录 |
| GET | `/admin/verify` | JWT | 校验管理 JWT |
| GET | `/admin/vercel/config` | Admin | 读取 Vercel 预配置 |
| GET | `/admin/config` | Admin | 读取配置（脱敏） |
| POST | `/admin/config` | Admin | 更新配置 |
| GET | `/admin/settings` | Admin | 读取运行时设置 |
| PUT | `/admin/settings` | Admin | 更新运行时设置（热更新） |
| POST | `/admin/settings/password` | Admin | 更新 Admin 密码并使旧 JWT 失效 |
| GET | `/admin/skills` | Admin | 读取技能库配置（全局开关、截断长度、条目列表） |
| PUT | `/admin/skills` | Admin | 整体替换技能库配置（校验失败返回 400） |
| POST | `/admin/config/import` | Admin | 导入配置（merge/replace） |
| GET | `/admin/config/export` | Admin | 导出完整配置（含 `config`/`json`/`base64`） |
| POST | `/admin/keys` | Admin | 添加 API key（可附 name/remark） |
| PUT | `/admin/keys/{key}` | Admin | 更新 API key 备注信息 |
| DELETE | `/admin/keys/{key}` | Admin | 删除 API key |
| GET | `/admin/proxies` | Admin | 代理列表 |
| POST | `/admin/proxies` | Admin | 添加代理 |
| PUT | `/admin/proxies/{proxyID}` | Admin | 更新代理（留空 password 表示保留原密码） |
| DELETE | `/admin/proxies/{proxyID}` | Admin | 删除代理（自动解绑引用该代理的账号） |
| POST | `/admin/proxies/test` | Admin | 测试代理连通性 |
| GET | `/admin/accounts` | Admin | 分页账号列表 |
| POST | `/admin/accounts` | Admin | 添加账号 |
| PUT | `/admin/accounts/{identifier}` | Admin | 更新账号 name/remark |
| DELETE | `/admin/accounts/{identifier}` | Admin | 删除账号 |
| PUT | `/admin/accounts/{identifier}/proxy` | Admin | 为账号绑定/解绑代理 |
| GET | `/admin/queue/status` | Admin | 账号队列状态 |
| POST | `/admin/accounts/test` | Admin | 测试单个账号 |
| POST | `/admin/accounts/test-all` | Admin | 测试全部账号 |
| POST | `/admin/accounts/sessions/delete-all` | Admin | 删除某账号的全部会话 |
| POST | `/admin/import` | Admin | 批量导入 keys/accounts |
| POST | `/admin/test` | Admin | 测试当前 API 可用性 |
| POST | `/admin/dev/raw-samples/capture` | Admin | 直接发起一次请求并保存为 raw sample |
| GET | `/admin/dev/raw-samples/query` | Admin | 按问题关键词查询当前内存抓包链 |
| POST | `/admin/dev/raw-samples/save` | Admin | 把命中的内存抓包链保存为 raw sample |
| POST | `/admin/vercel/sync` | Admin | 同步配置到 Vercel |
| GET | `/admin/vercel/status` | Admin | Vercel 同步状态 |
| POST | `/admin/vercel/status` | Admin | Vercel 同步状态 / 草稿对比 |
| GET | `/admin/export` | Admin | 导出配置 JSON/Base64 |
| GET | `/admin/dev/captures` | Admin | 查看本地抓包记录 |
| DELETE | `/admin/dev/captures` | Admin | 清空本地抓包记录 |
| GET | `/admin/chat-history` | Admin | 查看服务器端对话记录（支持按 caller/status/surface/关键词筛选与分页） |
| DELETE | `/admin/chat-history` | Admin | 清空服务器端对话记录 |
| GET | `/admin/chat-history/{id}` | Admin | 查看单条服务器端对话记录 |
| DELETE | `/admin/chat-history/{id}` | Admin | 删除单条服务器端对话记录 |
| PUT | `/admin/chat-history/settings` | Admin | 更新对话记录保留条数（`0`..`500`） |
| GET | `/admin/chat-history/export` | Admin | 按相同筛选条件导出对话记录（`json` / `markdown`） |
| GET | `/admin/version` | Admin | 查询当前版本与最新 Release |

OpenAI `/v1/*` 仍是规范路径。对于只配置 DS2API 根地址的客户端，同一套 OpenAI handler 也通过根路径快捷路由暴露：`/models`、`/models/{id}`、`/chat/completions`、`/responses`、`/responses/{response_id}`、`/embeddings`、`/files`、`/files/{file_id}`。

服务器端记录本质上是 DeepSeek 上游响应归档：OpenAI Chat、OpenAI Responses、Claude Messages、Gemini GenerateContent 等直连 DeepSeek 的生成接口，在收到上游响应后会于各协议回译/裁剪前写入记录；列表按请求创建时间倒序展示，流式请求会在生成过程中持续刷新状态与详情。WebUI「API 测试」发出的请求也会进入该记录。每条记录带 `caller_id`（API Key 调用方）与 `caller_label`（Key 的名称/备注/脱敏值），以及 `surface`（来源接口）、`status`、`status_code` 等可筛选字段；列表、详情、导出共用同一份数据，详见 [对话记录](#get-adminchat-history)。

---

## 健康检查

### `GET /healthz`

```json
{"status": "ok"}
```

### `GET /readyz`

```json
{"status": "ready"}
```

---

## OpenAI 兼容接口

### `GET /v1/models`

无需鉴权。返回当前支持的 DeepSeek 原生模型列表。

**响应示例**：

```json
{
  "object": "list",
  "data": [
    {"id": "deepseek-v4-flash", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-search", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-search-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []}
  ]
}
```

> 说明：`/v1/models` 返回的是规范化后的 DeepSeek 原生模型 ID；常见 alias 仅用于请求入参解析，不会在该接口中单独展开返回。带 `-nothinking` 后缀的模型表示无论请求里是否显式开启 thinking / reasoning，都会强制关闭思考输出。
>
> 模型系列已收敛到上表 4 个 flash 变体：`deepseek-v4-pro` / `deepseek-v4-pro-search` / `deepseek-v4-vision` 及其 `-nothinking` 形式已下线，不再出现在本接口、Ollama `/api/tags` 与 `/anthropic/v1/models` 中，但旧名字仍可被请求，解析时静默映射到 flash 对应项（见下一节）。

### 模型 alias 解析策略

对 `chat` / `responses` / `embeddings` 的 `model` 字段采用“宽进严出”：

1. 先匹配 DeepSeek 原生模型。
2. 再匹配 `model_aliases` 精确映射。
3. 如果请求名以 `-nothinking` 结尾，则在最终解析出的规范模型上追加对应的无思考变体。
4. 仍未命中则返回 `invalid_request_error`。当前不会按未知模型家族做启发式兜底；需要新增兼容名时请通过 `model_aliases` 明确配置。

当前内置默认 alias 来自 `internal/config/models.go`，`config.model_aliases` 会在运行时覆盖或补充同名映射。节选（全部指向 flash 系列）：

- OpenAI / Codex：`gpt-4o`、`gpt-4.1`、`gpt-5`、`gpt-5.5`、`gpt-5-codex`、`gpt-5.3-codex`、`codex-mini-latest` → `deepseek-v4-flash`
- OpenAI reasoning：`o1`、`o3`、`o4-mini` → `deepseek-v4-flash`；`o3-deep-research`、`o4-mini-deep-research` → `deepseek-v4-flash-search`
- Claude：`claude-opus-4-6`、`claude-sonnet-4-6`、`claude-haiku-4-5`、`claude-3-5-sonnet-latest` → `deepseek-v4-flash`
- Gemini：`gemini-2.5-pro`、`gemini-2.5-flash`、`gemini-3.1-pro`、`gemini-3-pro`、`gemini-3-flash`、`gemini-3.1-flash-lite`、`gemini-pro-vision` → `deepseek-v4-flash`
- 其他内置精确 alias：`llama-3.1-70b-instruct`、`qwen-max` → `deepseek-v4-flash`

上述 alias 若在请求名后追加 `-nothinking` 后缀，也会映射到对应的强制关闭 thinking 版本。

已下线的 DeepSeek 模型名不会让老客户端失效，解析时静默归一：

| 请求模型名 | 实际解析结果 |
| --- | --- |
| `deepseek-v4-pro` / `deepseek-v4-vision` | `deepseek-v4-flash` |
| `deepseek-v4-pro-search` | `deepseek-v4-flash-search` |
| `deepseek-v4-pro-nothinking` / `deepseek-v4-vision-nothinking` | `deepseek-v4-flash-nothinking` |
| `deepseek-v4-pro-search-nothinking` | `deepseek-v4-flash-search-nothinking` |

上游 `model_type` 现在只剩 `default`（历史配置里出现的 `expert` / `vision` 按 `default` 处理），因此不存在独立的视觉或 expert 通道。

退役历史模型（如 `claude-1.*`、`claude-2.*`、`claude-instant-*`、`gpt-3.5*`）会被显式拒绝。

### 思考与联网搜索解析策略

同一套规则适用于 `/v1/chat/completions`、`/v1/responses`、`/anthropic/v1/messages` 与 Gemini `generateContent`，实现在 `internal/util/thinking.go`、`internal/util/search.go`，不在各协议适配器里。

**思考（thinking）**，优先级从低到高：

| 顺序 | 来源 | 说明 |
| --- | --- | --- |
| 1 | 模型默认值 | `-nothinking` 变体默认关；其余 flash 模型默认开 |
| 2 | 客户端显式覆盖 | 命中任一字段即生效 |
| 3 | `-nothinking` 模型 | 强制关闭，优先级最高，客户端无法打开 |

客户端覆盖字段（`extra_body` 里的同名键同样会被读取）：

| 字段 | 接受写法 |
| --- | --- |
| `thinking` | bool；`"enabled"` / `"disabled"`（含 `on` / `off` / `true` / `false` / `none`）；`{"type": ...}` |
| `reasoning` | `{"effort": ...}`、`{"type": ...}`、`{"enabled": ...}`；字符串按 effort 解析 |
| `reasoning_effort` | `minimal` / `low` / `medium` / `high` / `xhigh` / `max` = 开启；`none` / `disabled` / `disable` / `off` / `false` = 关闭 |

Kelivo 这类客户端的「思维强度」界面就是靠 `reasoning_effort` 传开关：不发该字段表示跟随默认（开启思考），传 `none` 表示关闭。本项目只区分开/关，不区分强度档位。

**联网搜索（search）**，优先级为「模型默认 → 客户端显式信号优先」：

| 信号 | 说明 |
| --- | --- |
| `enable_search` | bool，或 `"true"` / `"false"` / `"on"` / `"off"` / `"enabled"` / `"disabled"` 等字符串 |
| `web_search_options` | 字段出现即视为开启 |
| `search_options` | 字段出现即视为开启 |
| `tools` 原生搜索类型 | `type` 以 `web_search` 开头、`type=google_search`，或工具对象含 `googleSearch` / `google_search` / `web_search` 字段 |

`-search` 变体默认开启联网；显式 `enable_search=false` 可在该模型上临时关掉。普通 function 工具（例如 Kelivo 客户端自己执行的 `search_web`）不算联网信号，所以默认仍不开启上游联网——要联网请选 `-search` 模型；一旦客户端开始发送上述原生信号，服务端会自动跟随，无需改配置。

### `POST /v1/chat/completions`

> 路径说明：除规范路径 `/v1/chat/completions` 外，也支持根路径快捷别名 `/chat/completions`。在 Vercel Runtime 上，`vercel.json` 仅把规范路径 `/v1/chat/completions` 重写到 Node 流式桥接；根路径快捷别名仍走 Go 主链路。因此 Vercel 上需要实时流式时请使用 `/v1/chat/completions`。

**请求头**：

```http
Authorization: Bearer your-api-key
Content-Type: application/json
```

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | ✅ | 支持 DeepSeek 原生模型 + 常见 alias（如 `gpt-5.5`、`gpt-5.4-mini`、`gpt-5.3-codex`、`o3`、`claude-opus-4-6`、`claude-sonnet-4-6`、`gemini-2.5-pro`、`gemini-3.1-pro`、`gemini-3-flash` 等）；若模型名带 `-nothinking` 后缀，则强制关闭 thinking / reasoning |
| `messages` | array | ✅ | OpenAI 风格消息数组 |
| `stream` | boolean | ❌ | 默认 `false` |
| `tools` | array | ❌ | Function Calling 定义 |
| `thinking` | bool / string / object | ❌ | 显式思考开关，覆盖模型默认；`-nothinking` 模型会忽略 |
| `reasoning` / `reasoning_effort` | object / string | ❌ | 与 `thinking` 等价的另一种写法；`reasoning_effort=none` 关闭思考，`minimal`~`max` 开启 |
| `enable_search` | bool / string | ❌ | 显式联网开关，覆盖模型默认（用于在 `-search` 模型上临时关闭） |
| `temperature` 等 | any | ❌ | 兼容透传字段（最终效果由上游决定） |

> 思考与联网的完整解析优先级见 [思考与联网搜索解析策略](#思考与联网搜索解析策略)。

#### 非流式响应

```json
{
  "id": "<chat_session_id>",
  "object": "chat.completion",
  "created": 1738400000,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "最终回复",
        "reasoning_content": "思考内容（开启 thinking 时）"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30,
    "completion_tokens_details": {
      "reasoning_tokens": 5
    }
  }
}
```

#### 流式响应（`stream=true`）

SSE 格式：每段为 `data: <json>\n\n`，结束为 `data: [DONE]`。

```text
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"..."},"index":0}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"..."},"index":0}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{},"index":0,"finish_reason":"stop"}],"usage":{...}}

data: [DONE]
```

**字段说明**：

- 首个 delta 包含 `role: assistant`
- 开启 thinking 时会输出 `delta.reasoning_content`
- 普通文本输出 `delta.content`
- 最后一段包含 `finish_reason` 和 `usage`
- token 计数优先透传上游 DeepSeek SSE（如 `accumulated_token_usage` / `token_usage`）；仅在上游缺失时回退本地估算。失败/中断型结束（例如 `response.failed`）可能不会携带 `usage`

#### Tool Calls

> 若 `tools.enabled=false`（默认），请求里的 `tools` 会被忽略，响应不会包含 `tool_calls`。下面描述的行为只在开启工具调用后生效，开启风险见 [docs/prompt-compatibility.md](docs/prompt-compatibility.md)。

当请求中含 `tools` 时，DS2API 做防泄漏处理：

**非流式**：识别到工具调用时，返回 `message.tool_calls`，设置 `finish_reason=tool_calls`，`message.content=null`。

```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_xxx",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

**流式**：命中高置信特征后立即输出 `delta.tool_calls`（不等待完整工具参数闭合），并持续发送 arguments 增量；已确认的工具调用片段不会回流到 `delta.content`。

补充说明：

- **非代码块上下文**下，工具负载即使与普通文本混合，也会按特征识别并产出可执行 tool call（前后普通文本仍可透传）。
- 解析器当前把推荐半角管道符 DSML 外壳（`<|DSML|tool_calls>` / `<|DSML|invoke name="...">` / `<|DSML|parameter name="...">`）、DSML wrapper 别名（`<dsml|tool_calls>`、`<|tool_calls>`）、常见 DSML 分隔符漏写形态（如 `<|DSML tool_calls>` / `<|DSML invoke>` / `<|DSML parameter>`）、`DSML` 与工具标签名黏连的常见 typo（如 `<DSMLtool_calls>` / `<DSMLinvoke>` / `<DSMLparameter>`）、控制分隔符漂移（如 `<DSML␂tool_calls>` / 原始 STX `\x02`）、CJK 尖括号、全角感叹号、顿号、PascalCase 本地名、弯引号属性值与属性尾部分隔符漂移（如 `<DSM|parameter name="command"|>...〈/DSM|parameter〉` / `<！DSML！invoke name=“Bash”>` / `<、DSML、tool_calls>` / `<DSmartToolCalls>` / `<DSMLtool_calls※>`）、任意协议前缀壳（如 `<proto💥tool_calls>`）和旧式 canonical XML 工具块（`<tool_calls>` / `<invoke name="...">` / `<parameter name="...">`）作为可执行调用解析；这些非结构性分隔符壳会先归一化回 XML，内部仍以 XML 解析语义为准，CDATA 开头也会容错 `<！[CDATA[` / `<、[CDATA[`。旧式 `<tools>`、`<tool_call>`、`<tool_name>`、`<param>`、`<function_call>`、`tool_use`、antml 风格与纯 JSON `tool_calls` 片段默认都会按普通文本处理；完整但 malformed 的 wrapper 同样会作为普通文本释放。
- 解析层不会因为参数值为空而丢弃工具调用；显式空字符串或纯空白参数会按空字符串进入结构化 `tool_calls`。Prompt 会要求模型不要主动输出空参数，缺参/空命令的拒绝应由工具执行侧或客户端 schema 校验负责。
- 当最终可见正文为空但思维链里包含可执行工具调用时，Chat / Responses 会在收尾阶段补发标准 OpenAI `tool_calls` / `function_call` 输出；如果客户端未开启 thinking / reasoning，该思维链只用于检测，不会作为可见正文或 `reasoning_content` 暴露。
- Markdown fenced code block（例如 ```json ... ```）和行内 code span（例如 `` `<tool_calls>...</tool_calls>` ``）中的 `tool_calls` 仅视为示例文本，不会被执行。

---

### `GET /v1/models/{id}`

无需鉴权。入参支持 alias（例如 `gpt-4o`），返回的是映射后的 DeepSeek 模型对象。

### `POST /v1/responses`

OpenAI Responses 风格接口，兼容 `input` 或 `messages`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | ✅ | 支持原生模型 + alias 自动映射 |
| `input` | string/array/object | ❌ | 与 `messages` 二选一 |
| `messages` | array | ❌ | 与 `input` 二选一 |
| `instructions` | string | ❌ | 自动前置为 system 消息 |
| `stream` | boolean | ❌ | 默认 `false` |
| `tools` | array | ❌ | 与 chat 同样的工具识别与转译策略（含代码块示例豁免） |
| `tool_choice` | string/object | ❌ | 支持 `auto`/`none`/`required` 与强制函数（`{"type":"function","name":"..."}`） |

**非流式响应**：返回标准 `response` 对象，`id` 形如 `resp_xxx`，并写入内存 TTL 存储。
当 `tool_choice=required` 且未产出有效工具调用时，返回 HTTP `422`（`error.code=tool_choice_violation`）。

**流式响应（SSE）**：最小事件序列如下。

```text
event: response.created
data: {"type":"response.created","id":"resp_xxx","status":"in_progress",...}

event: response.output_item.added
data: {"type":"response.output_item.added","response_id":"resp_xxx","item":{"type":"message|function_call",...},...}

event: response.content_part.added
data: {"type":"response.content_part.added","response_id":"resp_xxx","part":{"type":"output_text",...},...}

event: response.output_text.delta
data: {"type":"response.output_text.delta","response_id":"resp_xxx","item_id":"msg_xxx","output_index":0,"content_index":0,"delta":"..."}

event: response.function_call_arguments.delta
data: {"type":"response.function_call_arguments.delta","response_id":"resp_xxx","call_id":"call_xxx","delta":"..."}

event: response.function_call_arguments.done
data: {"type":"response.function_call_arguments.done","response_id":"resp_xxx","call_id":"call_xxx","name":"tool","arguments":"{...}"}

event: response.content_part.done
data: {"type":"response.content_part.done","response_id":"resp_xxx",...}

event: response.output_item.done
data: {"type":"response.output_item.done","response_id":"resp_xxx","item":{"type":"message|function_call",...},...}

event: response.completed
data: {"type":"response.completed","response":{...}}

data: [DONE]
```

流式场景下若 `tool_choice=required` 违规，会返回 `response.failed` 后结束（不再发送 `response.completed`）。

> 当前版本说明：解析层默认“尽量提取结构化 tool call”，未启用基于 `tools` allow-list 的硬拒绝；是否执行仍应由你的工具执行器做白名单校验。

### `GET /v1/responses/{response_id}`

需要业务鉴权。查询 `POST /v1/responses` 生成并缓存的 response 对象（按调用方鉴权隔离，仅同一 key/token 可读取）。

> 当前为内存 TTL 存储，默认过期时间 `900s`（可用 `responses.store_ttl_seconds` 调整）。

### `POST /v1/embeddings`

需要业务鉴权。返回 OpenAI Embeddings 兼容结构。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | ✅ | 支持原生模型 + alias 自动映射 |
| `input` | string/array | ✅ | 支持字符串、字符串数组、token 数组 |

> 需配置 `embeddings.provider`。当前支持：`mock` / `deterministic` / `builtin`（三者都走同一套本地确定性实现）。未配置或不支持时返回标准错误结构（HTTP 501）。

### `POST /v1/files`

需要业务鉴权。兼容 OpenAI Files 上传接口，当前仅支持 `multipart/form-data`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | file | ✅ | 上传文件二进制 |
| `purpose` | string | ❌ | 透传到上游用途字段 |

约束与行为：

- 请求必须为 `multipart/form-data`，否则返回 `400`。
- 请求体总大小上限 **100 MiB**（超限返回 `413`）。
- 成功返回 OpenAI `file` 对象（`id/object/bytes/filename/purpose/status` 等字段），并附带 `account_id` 便于定位来源账号。

### `GET /v1/files/{file_id}`

需要业务鉴权。查询 DeepSeek 上传文件的当前状态，并返回 OpenAI `file` 对象；未找到匹配文件时返回 `404`。

---

## Claude 兼容接口

除标准路径 `/anthropic/v1/*` 外，还支持快捷路径 `/v1/messages`、`/messages`、`/v1/messages/count_tokens`、`/messages/count_tokens`。
实现上统一走 OpenAI Chat Completions 解析与回译链路，避免多套解析逻辑分叉维护。

### `GET /anthropic/v1/models`

无需鉴权。

**响应示例**：

```json
{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-4-6", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-sonnet-4-6-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-haiku-4-5", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-haiku-4-5-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-opus-4-6", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-opus-4-6-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"}
  ],
  "first_id": "claude-opus-4-6",
  "last_id": "claude-3-haiku-20240307-nothinking",
  "has_more": false
}
```

> 说明：示例仅展示部分模型；实际返回除当前主别名外，还包含 Claude 4.x snapshots、3.x 历史模型 ID 与常见别名，并为这些可映射模型额外提供 `-nothinking` 变体。

### `POST /anthropic/v1/messages`

**请求头**：

```http
x-api-key: your-api-key
Content-Type: application/json
anthropic-version: 2023-06-01
```

> `anthropic-version` 可省略，服务端会自动补为 `2023-06-01`。

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | ✅ | 例如 `claude-sonnet-4-6` / `claude-opus-4-6` / `claude-haiku-4-5`（兼容 `claude-sonnet-4-5`、`claude-3-5-haiku-latest`），并支持历史 Claude 模型 ID；若模型名带 `-nothinking` 后缀，则强制关闭 thinking / reasoning |
| `messages` | array | ✅ | Claude 风格消息数组 |
| `max_tokens` | number | ❌ | 缺省自动补 `8192`；当前实现不会硬性截断上游输出 |
| `stream` | boolean | ❌ | 默认 `false` |
| `system` | string | ❌ | 可选系统提示 |
| `tools` | array | ❌ | Claude tool 定义 |
| `thinking` | object | ❌ | Anthropic thinking 配置；会转译为下游 reasoning 控制，`-nothinking` 模型会忽略 |
| `temperature` | number | ❌ | 透传到下游；若同时提供 `top_p`，以 `temperature` 为准 |
| `top_p` | number | ❌ | 当未提供 `temperature` 时透传到下游 |
| `stop_sequences` | array | ❌ | 透传到下游停用序列 |
| `tool_choice` | string/object | ❌ | 支持 `auto` / `none` / `required` / `{"type":"function","name":"..."}`，并会转译为下游工具选择 |

> 说明：上述 `thinking`、`temperature`、`top_p`、`stop_sequences`、`tool_choice` 都会走兼容层转译；最终是否生效仍取决于当前模型和上游能力。`temperature` 与 `top_p` 同时存在时，`temperature` 优先。思考与联网的解析优先级与 OpenAI 接口完全一致，见 [思考与联网搜索解析策略](#思考与联网搜索解析策略)。若 `tools.enabled=false`（默认），请求里的 `tools` 会被忽略，响应不会包含 `tool_calls`（Claude 侧即 `tool_use` 块）。

#### 非流式响应

```json
{
  "id": "msg_1738400000000000000",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "回复内容"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 34
  }
}
```

若识别到工具调用，`stop_reason=tool_use`，`content` 中返回 `tool_use` block。

#### 流式响应（`stream=true`）

SSE 使用 `event:` + `data:` 双行格式，JSON 中保留 `type` 字段。

```text
event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hello"}}

event: ping
data: {"type":"ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}
```

**说明**：

- 默认支持 thinking 的模型会输出 `thinking` block / `thinking_delta`；请求显式关闭 thinking 或使用 `-nothinking` 模型时不会输出
- 带 `-nothinking` 后缀的模型会强制关闭 thinking，即使请求显式传了 `thinking` / `reasoning` / `reasoning_effort` 也不会输出 `thinking_delta`
- 不会输出 `signature_delta`（上游 DeepSeek 未提供可验证签名）
- `tools` 场景优先避免泄露原始工具 JSON，不强制发送 `input_json_delta`

### `POST /anthropic/v1/messages/count_tokens`

**请求**：

```json
{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}
```

**响应**：

```json
{
  "input_tokens": 5
}
```

---

## Gemini 兼容接口

支持路径：

- `/v1beta/models/{model}:generateContent`
- `/v1beta/models/{model}:streamGenerateContent`
- `/v1/models/{model}:generateContent`（兼容路径）
- `/v1/models/{model}:streamGenerateContent`（兼容路径）

鉴权方式同业务接口（`Authorization: Bearer <token>` 或 `x-api-key`）。
实现上统一走 OpenAI Chat Completions 解析与回译链路，避免多套解析逻辑分叉维护。

### `POST /v1beta/models/{model}:generateContent`

请求体兼容 Gemini `contents` / `tools` 字段，模型名可用 alias 自动映射到 DeepSeek 模型；若路径中的模型名带 `-nothinking` 后缀，则最终会映射到对应的无思考模型。思考与联网的解析优先级与 OpenAI 接口一致，见 [思考与联网搜索解析策略](#思考与联网搜索解析策略)。若 `tools.enabled=false`（默认），请求里的 `tools` 会被忽略，响应不会包含 `tool_calls`（Gemini 侧即 `functionCall`）。

响应为 Gemini 兼容结构，核心字段包括：

- `candidates[].content.parts[].text`
- `candidates[].content.parts[].thought=true`（thinking 输出）
- `candidates[].content.parts[].functionCall`（工具调用时）
- `usageMetadata`（`promptTokenCount` / `candidatesTokenCount` / `totalTokenCount`）

### `POST /v1beta/models/{model}:streamGenerateContent`

返回 SSE（`text/event-stream`），每个 chunk 为一条 `data: <json>`：

- 常规文本：持续返回增量文本 chunk
- thinking：持续返回 `parts[].thought=true` 的增量 chunk
- `tools` 场景：会缓冲并在结束时输出 `functionCall` 结构
- 结束 chunk：包含 `finishReason: "STOP"` 与 `usageMetadata`
- token 计数优先透传上游 DeepSeek SSE（如 `accumulated_token_usage` / `token_usage`）；仅在上游缺失时回退本地估算

---

## Ollama 兼容接口

- `POST /api/show` 请求体：`{"model":"<model-id>"}`。
- `GET /api/tags` 只列出 flash 系列的 4 个模型 ID（`deepseek-v4-flash`、`deepseek-v4-flash-search` 及各自 `-nothinking` 变体），与 `/v1/models` 保持一致；已下线的 pro / vision 名字不再出现，但仍可作为 `model` 入参被请求。
- 响应字段使用小写 `id`（不是 `ID`），并返回 `capabilities` 数组，便于与 Ollama 风格客户端/严格 schema 对齐。

示例响应：

```json
{
  "id": "deepseek-v4-flash",
  "capabilities": ["tools", "thinking"]
}
```

## Admin 接口

### `POST /admin/login`

无需鉴权。

**请求**：

```json
{
  "admin_key": "admin",
  "expire_hours": 24
}
```

`expire_hours` 可省略，默认 `24`。

**响应**：

```json
{
  "success": true,
  "token": "<jwt>",
  "expires_in": 86400
}
```

### `GET /admin/verify`

需要 JWT：`Authorization: Bearer <jwt>`

**响应**：

```json
{
  "valid": true,
  "expires_at": 1738400000,
  "remaining_seconds": 72000
}
```

### `GET /admin/vercel/config`

返回 Vercel 预配置状态。优先读取环境变量，其次回退到已保存的 `vercel` 配置块。

```json
{
  "has_token": true,
  "token_preview": "vc****en",
  "token_source": "config",
  "project_id": "prj_xxx",
  "team_id": null
}
```

### `GET /admin/config`

返回脱敏后的配置，包含 `keys` 与 `api_keys`。

```json
{
  "keys": ["k1", "k2"],
  "api_keys": [
    {"key": "k1", "name": "主 Key", "remark": "生产流量"},
    {"key": "k2", "name": "备用 Key", "remark": "压测"}
  ],
  "env_backed": false,
  "env_source_present": true,
  "env_writeback_enabled": true,
  "config_path": "/data/config.json",
  "vercel": {
    "has_token": true,
    "token_preview": "vc****en",
    "project_id": "prj_xxx",
    "team_id": ""
  },
  "accounts": [
    {
      "identifier": "user@example.com",
      "email": "user@example.com",
      "mobile": "",
      "has_password": true,
      "has_token": true,
      "token_preview": "abcde..."
    }
  ],
  "model_aliases": {
    "claude-sonnet-4-6": "deepseek-v4-flash",
    "claude-opus-4-6": "deepseek-v4-flash"
  }
}
```

### `POST /admin/config`

只更新 `keys`、`api_keys`、`accounts`、`model_aliases`。
如果同时发送 `api_keys` 与 `keys`，优先保留 `api_keys` 中的结构化 `name` / `remark`；`keys` 仅作为旧格式兼容回退。

**请求**：

```json
{
  "keys": ["k1", "k2"],
  "api_keys": [
    {"key": "k1", "name": "主 Key", "remark": "生产流量"},
    {"key": "k2", "name": "备用 Key", "remark": "压测"}
  ],
  "accounts": [
    {"email": "user@example.com", "password": "pwd", "token": ""}
  ],
  "model_aliases": {
    "claude-sonnet-4-6": "deepseek-v4-flash",
    "claude-opus-4-6": "deepseek-v4-flash"
  }
}
```

### `api_keys[].thinking_injection`（单 Key 覆盖思考格式注入）

`api_keys` 的每一项都可以带 `thinking_injection`，用于给单个 API Key 定制注入提示词；`keys` 旧格式不支持该字段。

```json
{
  "api_keys": [
    {
      "key": "k1",
      "name": "主 Key",
      "remark": "生产流量",
      "thinking_injection": {
        "custom": true,
        "enabled": true,
        "prompt": "回答前先列清楚已知条件，再给结论。"
      }
    },
    {"key": "k2", "name": "备用 Key"}
  ]
}
```

| 字段 | 说明 |
| --- | --- |
| `custom` | 默认 `false`。为 `false`（或整段省略）时完全跟随全局 `thinking_injection` |
| `enabled` | 仅在 `custom=true` 时生效；省略表示继续跟随全局开关 |
| `prompt` | 仅在 `custom=true` 时生效；为空或全空白表示继续跟随全局提示词 |

全局开关与默认提示词见 [`GET /admin/settings`](#get-adminsettings) 的 `thinking_injection`；注入位置与默认提示词内容见 [docs/prompt-compatibility.md](docs/prompt-compatibility.md)。

### `api_keys[].prompt_profile`（单 Key 覆盖提示词特化层）

`api_keys` 的每一项都可以带 `prompt_profile`，用于给单个 API Key 指定特化层预设或正文，与 `thinking_injection`、`skills` 并列；`keys` 旧格式不支持该字段。该字段目前只在配置文件/导入导出里生效，后台面板只提供全局段（见下）。

```json
{
  "api_keys": [
    {
      "key": "k1",
      "name": "写作 Key",
      "prompt_profile": {"custom": true, "enabled": true, "name": "writing"}
    },
    {"key": "k2", "name": "默认 Key"}
  ]
}
```

| 字段 | 说明 |
| --- | --- |
| `custom` | 默认 `false`；为 `false` 或整段省略时完全跟随全局 `prompt_profile` |
| `enabled` | 仅在 `custom=true` 时生效；为 `false` 表示该 Key 不注入特化层 |
| `name` | 仅在 `custom=true` 时生效；`default` / `writing`，非空时覆盖全局预设 |
| `prompt` | 仅在 `custom=true` 时生效；非空时覆盖预设正文（上限 20000 字符） |

全局 `prompt_profile.enabled=false` 时上表全部不生效，任何 Key 都不注入。

### `prompt_style`（内置提示词风格，全局）

顶层字符串字段，只影响内置文案，不影响你自己配置的提示词：

```json
{"prompt_style": "legacy"}
```

| 值 | 行为 |
| --- | --- |
| `v2`（缺省，也接受空串） | 历史拆分后的衔接指令带「执行要求」（上文要求逐条满足）并注入内置执行契约（思考注入） |
| `legacy` | 衔接指令换回 ce5a019 时代的短文案，且**不注入内置执行契约**；显式配置过 `thinking_injection.prompt` 时仍然注入自定义内容 |

未知值不会让配置加载失败：按 `v2` 处理并打一条告警。后台 `PUT /admin/settings` 传未知值直接返回 400。

### `model_profiles`（自定义模型列表，全局）

给同一个 flash 基模挂出多个对外模型名，每个名字带自己的提示词。客户端请求里写哪个模型名，就用哪一份提示词，互不影响。

```json
{
  "model_profiles": [
    {
      "id": "deepseek-writer",
      "base": "deepseek-v4-flash",
      "name": "写作",
      "remark": "长文与改稿",
      "prompt": "## 写作要求\n…"
    }
  ]
}
```

| 字段 | 说明 |
| --- | --- |
| `id` | 必填，对外模型名。字符集 `[A-Za-z0-9._-]`，长度 1-64，不可与内置模型名（如 `deepseek-v4-flash`）冲突，条目间不可重复（大小写不敏感） |
| `base` | 必填，基模，只能是 `deepseek-v4-flash` / `-search` / `-nothinking` / `-search-nothinking` |
| `name` / `remark` | 可选，仅用于后台与导出可读性 |
| `prompt` | 可选，该模型专属提示词，上限 20000 字符；为空表示不额外注入 |

解析与注入语义：

- 模型名解析优先于内置别名映射：`id` 命中自定义模型时按它的 `base` 调用上游（`/v1/models`、`/v1/models/{id}`、`/v1/chat/completions`、Claude / Gemini 入口共用同一套解析）。
- `/v1/models` 会把自定义模型一起列出来，`owned_by` 为 `ds2api`。
- 提示词注入点与 `prompt_profile` 相同（历史拆分之后、技能层之前），两者**互斥**：该模型配了非空 `prompt` 就用它，否则回落到全局 `prompt_profile`。
- 数量上限 50 条。接口见 [`GET` / `PUT /admin/model_profiles`](#get--put-adminmodel_profiles)。

### `api_keys[].skills`（单 Key 覆盖技能注入）

`api_keys` 的每一项都可以带 `skills`，用来指定这个 API Key 注入哪些技能，与 `thinking_injection` 并列；`keys` 旧格式不支持该字段。

```json
{
  "api_keys": [
    {"key": "k1", "name": "主 Key", "skills": {"custom": true, "enabled": true, "ids": ["sql-report"]}},
    {"key": "k2", "name": "备用 Key"}
  ]
}
```

| 字段 | 说明 |
| --- | --- |
| `custom` | 默认 `false`；为 `false` 或整段省略时使用全部 `skills.items` |
| `enabled` | 仅在 `custom=true` 时生效；为 `false` 表示该 Key 不注入 |
| `ids` | 仅在 `custom=true` 时生效；非空时只用命中的技能，为空时该 Key 不注入 |

| `custom` | `enabled` | `ids` | 结果 |
| --- | --- | --- | --- |
| 省略或 `false` | 任意 | 任意 | 使用全部 `items` |
| `true` | `false` | 任意 | 不注入 |
| `true` | 省略或 `true` | 非空 | 只用命中的 `items` |
| `true` | 省略或 `true` | 空 | 不注入 |

全局 `skills.enabled=false` 时上表全部不生效，任何 Key 都不注入。技能正文与管理接口见 [`GET` / `PUT /admin/skills`](#get--put-adminskills)。

### `GET /admin/settings`

读取运行时设置与状态，返回：

- `success`
- `admin`（`has_password_hash`、`jwt_expire_hours`、`jwt_valid_after_unix`、`default_password_warning`）
- `runtime`（`account_max_inflight`、`account_max_queue`、`global_max_inflight`、`token_refresh_interval_hours`）
- `runtime.token_refresh_interval_hours` 的语义是「会话体检间隔」：到期只做一次无密码复核（`GET /api/v0/users/current`），只有服务端明确拒绝会话时才回退到密码登录
- `config_snapshot`：原始配置快照（`admin` / `runtime` / `responses` / `embeddings` / `auto_delete` / `current_input_file` / `thinking_injection` / `prompt_profile` / `prompt_style` / `model_profiles` / `model_aliases`），用于区分环境变量覆盖前的配置
- `responses` / `embeddings`
- `auto_delete`（`mode`：`none` / `single` / `all`；旧配置 `sessions=true` 仍按 `all` 处理）
- `current_input_file`（`enabled` 默认返回 `true`、`min_chars`）
- `thinking_injection`（`enabled` 缺省为 `true`、`prompt`、`default_prompt`）；`prompt` 为空时使用内置默认提示词，单 Key 可用 `api_keys[].thinking_injection` 覆盖
- `prompt_profile`（`enabled` 缺省 `false`、`enabled_default` 固定 `false`、`name`、`prompt`、`presets`）；`presets` 是 `[{name, body}]` 的内置预设清单，`body` 为该预设正文，供面板在输入框里显示「留空时使用的默认正文」
- `prompt_style`（`mode`：生效风格 `v2` / `legacy`；`modes`：可选值；`default`：`v2`；`value_raw`：配置里原样存的值）
- `model_profiles`（`count`、`max_count`、`base_models`、`max_id_chars`、`max_prompt_chars`）；条目本身用 `/admin/model_profiles` 读写
- `model_aliases`
- `tools`（`enabled`：工具调用总开关，缺省 `false`；`default_enabled`：固定 `false`，供面板显示默认值）
- `env_backed`、`needs_vercel_sync`
- `toolcall` 策略已固定为 `feature_match + high`，不再通过 settings 返回或修改

### `PUT /admin/settings`

热更新运行时设置。支持更新：

- `admin.jwt_expire_hours`
- `runtime.account_max_inflight` / `runtime.account_max_queue` / `runtime.global_max_inflight` / `runtime.token_refresh_interval_hours`
- `responses.store_ttl_seconds`
- `embeddings.provider`
- `auto_delete.mode`
- `current_input_file.enabled` / `current_input_file.min_chars`
- `thinking_injection.enabled` / `thinking_injection.prompt`
- `prompt_profile.enabled` / `prompt_profile.name` / `prompt_profile.prompt`
- `prompt_style`
- `tools.enabled`
- `model_aliases`
- `toolcall` 策略已固定，不再作为可写入字段

`prompt_profile` 是本次新增的「提示词特化层」，缺省关闭；`name` 只接受 `default` / `writing`（其他值返回 400），`prompt` 上限 20000 字符（超限返回 400），只传部分字段时其余字段保持不变：

```json
{"prompt_profile": {"enabled": true, "name": "writing"}}
```

注入位置、拼接顺序与预设正文见 [docs/prompt-compatibility.md](docs/prompt-compatibility.md) 与 [docs/prompt-design.md](docs/prompt-design.md)。

`prompt_style` 是顶层字符串（不是对象），只接受 `v2` / `legacy` / 空串（空串等于回到 v2）：

```json
{"prompt_style": "legacy"}
```

自定义模型列表不走 settings，用下面的 `/admin/model_profiles` 整体替换。

`tools.enabled` 只改请求体里传了的字段，其它设置的现有语义不变：

```json
{"tools": {"enabled": true}}
```

关闭（默认）时带 `tools` 的请求按纯对话处理；DSML 工具调用可能触发上游风控导致账号封禁，是否开启请自行评估，风险说明见 [docs/prompt-compatibility.md](docs/prompt-compatibility.md)。

### `POST /admin/settings/password`

更新管理密码并使旧 JWT 失效。

请求示例：

```json
{"new_password":"your-new-password"}
```

也兼容 `{"password":"your-new-password"}`。

### `GET` / `PUT /admin/skills`

纯文本技能库，实验性功能，缺省关闭（`skills.enabled=false`）。技能正文由服务端拼进 prompt，模型不需要工具调用就能按固定套路工作。

- 全局配置：`skills.enabled`（缺省 `false`）、`skills.max_chars`（缺省 `8000`）、`skills.items`
- 单 Key 覆盖：`api_keys[].skills`，语义见上文「api_keys[].skills（单 Key 覆盖技能注入）」
- 注入形态、注入顺序与「为什么不用工具调用」：[docs/prompt-compatibility.md](docs/prompt-compatibility.md) 的「技能注入（skills）」

**GET 响应**：

```json
{
  "enabled": false,
  "max_chars": 8000,
  "items": [
    {
      "id": "sql-report",
      "name": "SQL 报表",
      "description": "按固定口径写 SQL",
      "body": "# 技能正文 markdown\n..."
    }
  ]
}
```

**PUT 请求**：与 GET 同形状，整体替换，不做增量合并。

```json
{
  "enabled": true,
  "max_chars": 8000,
  "items": [
    {
      "id": "sql-report",
      "name": "SQL 报表",
      "description": "按固定口径写 SQL",
      "body": "# 报表口径\n先按天聚合，再按渠道拆分。"
    }
  ]
}
```

**PUT 成功响应**：

```json
{"success": true, "count": 1}
```

**校验规则**（任一不满足返回 `400`，响应体为 `{"detail": "..."}`）：

| 字段 | 规则 |
| --- | --- |
| `items` | 最多 50 条 |
| `id` | 必填、唯一，字符集 `[a-z0-9_-]` |
| `body` | 必填；单条 ≤ 100000 字符，全部条目合计 ≤ 500000 字符 |
| `max_chars` | 缺省 `8000`；按字符（rune）截断，截断时追加「（技能内容已截断）」；`0` 表示不限制 |

校验在写入时执行，与 `enabled` 无关：先关着开关把内容配好、改好，再打开即可。超限、重复 `id`、非法 `id` 都不会被静默修正。

### `GET` / `PUT /admin/model_profiles`

自定义模型列表（模型名 + 基模 + 该模型专属提示词）。与技能库同样是独立接口、整体替换语义：PUT 请求里的 `items` 就是最终列表，传空数组表示清空。

**GET 响应**：

```json
{
  "items": [
    {"id": "deepseek-writer", "base": "deepseek-v4-flash", "name": "写作", "remark": "长文", "prompt": "## 写作要求\n…"}
  ],
  "base_models": ["deepseek-v4-flash", "deepseek-v4-flash-search", "deepseek-v4-flash-nothinking", "deepseek-v4-flash-search-nothinking"],
  "max_count": 50,
  "max_id_chars": 64,
  "max_prompt_chars": 20000
}
```

**PUT 请求**：

```json
{"items": [{"id": "deepseek-writer", "base": "deepseek-v4-flash", "prompt": "…"}]}
```

**校验规则**（任一条不满足返回 `400`，响应体为 `{"detail": "..."}`）：

| 字段 | 规则 |
| --- | --- |
| `items` | 最多 50 条 |
| `id` | 必填、唯一（大小写不敏感），字符集 `[A-Za-z0-9._-]`，长度 1-64，不可与内置模型名冲突 |
| `base` | 必填，只能是 `deepseek-v4-flash` 系列的四个名字之一 |
| `prompt` | 可空；≤ 20000 字符 |

保存后立即生效：`/v1/models` 列表与模型名解析都会包含新条目，无需重启。

### `POST /admin/config/import`

导入完整配置，支持：

- `mode=merge`（默认）
- `mode=replace`

请求可直接传配置对象，或使用 `{"config": {...}, "mode":"merge"}` 包裹格式。
也支持在查询参数里传 `?mode=merge` / `?mode=replace`。
`replace` 模式会按完整配置结构替换（保留 Vercel 同步元信息）；`merge` 模式会合并 `keys`、`api_keys`、`accounts`、`model_aliases`，并覆盖 `admin`、`runtime`、`responses`、`embeddings` 中的非空字段。`auto_delete`、`current_input_file` 建议通过 `/admin/settings` 或配置文件管理；`compat` 与 `toolcall` 相关字段会被忽略。

> 注意：`merge` 模式不会更新 `auto_delete`、`current_input_file`。

### `GET /admin/config/export`

导出完整配置，返回 `config`、`json`、`base64` 三种格式。

响应示例：


> 注：`_vercel_sync_hash` 和 `_vercel_sync_time` 为内部同步元数据字段，用于 Vercel 配置漂移检测。

### `POST /admin/keys`

```json
{"key": "new-api-key", "name": "主 Key", "remark": "生产流量"}
```

**响应**：`{"success": true, "total_keys": 3}`

### `PUT /admin/keys/{key}`

更新指定 API key 的 `name` / `remark`，路径参数中的 `key` 为只读标识，不可修改。

```json
{"name": "备用 Key", "remark": "压测"}
```

**响应**：`{"success": true, "total_keys": 3}`

### `DELETE /admin/keys/{key}`

**响应**：`{"success": true, "total_keys": 2}`

### `GET /admin/proxies`

列出代理配置（密码不回传，仅返回 `has_password` 标记）。

### `POST /admin/proxies`

新增代理。请求体支持 `id`（可选，未传则自动生成）、`name`、`type`（`http` / `socks5`）、`host`、`port`、`username`、`password`。

### `PUT /admin/proxies/{proxyID}`

更新指定代理。若请求中 `password` 为空字符串，则保留原密码。

### `DELETE /admin/proxies/{proxyID}`

删除代理，并自动清空所有引用该代理账号的 `proxy_id`。

### `POST /admin/proxies/test`

测试代理连通性：传 `proxy_id` 时测试已保存代理；不传时按请求体代理字段做临时连通性测试。

### `GET /admin/accounts`

**查询参数**：

| 参数 | 默认 | 范围 |
| --- | --- | --- |
| `page` | `1` | ≥ 1 |
| `page_size` | `10` | 1–5000 |
| `q` | 空 | 按 identifier / email / mobile 过滤 |

**响应**：

```json
{
  "items": [
    {
      "identifier": "user@example.com",
      "email": "user@example.com",
      "mobile": "",
      "has_password": true,
      "has_token": true,
      "token_preview": "abc...",
      "test_status": "ok"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 10,
  "total_pages": 3
}
```

### `POST /admin/accounts`

```json
{"email": "user@example.com", "password": "pwd"}
```

**响应**：`{"success": true, "total_accounts": 6}`

### `PUT /admin/accounts/{identifier}`

更新指定账号的 `name` / `remark`。路径参数中的 `identifier` 可以是 email 或 mobile，且不可修改。

```json
{"name": "主账号", "remark": "团队共享"}
```

**响应**：`{"success": true, "total_accounts": 6}`

### `DELETE /admin/accounts/{identifier}`

`identifier` 可为 email、mobile，或 token-only 账号的合成标识（`token:<hash>`）。

**响应**：`{"success": true, "total_accounts": 5}`

### `PUT /admin/accounts/{identifier}/proxy`

更新指定账号绑定代理。

- 请求体：`{"proxy_id":"..."}`；
- `proxy_id` 传空字符串时表示解绑代理；
- `identifier` 支持 email / mobile / token-only 合成标识。

### `GET /admin/queue/status`

```json
{
  "available": 3,
  "in_use": 1,
  "total": 4,
  "available_accounts": ["a@example.com"],
  "in_use_accounts": ["b@example.com"],
  "max_inflight_per_account": 2,
  "global_max_inflight": 8,
  "recommended_concurrency": 8,
  "waiting": 0,
  "max_queue_size": 8
}
```

| 字段 | 说明 |
| --- | --- |
| `available` | 仍有剩余并发槽位的账号数 |
| `in_use` | 当前已占用的 in-flight 槽位数 |
| `total` | 总账号数 |
| `available_accounts` | 仍有剩余并发槽位的账号 ID 列表 |
| `in_use_accounts` | 当前处于使用中的账号 ID 列表 |
| `max_inflight_per_account` | 每账号并发上限 |
| `global_max_inflight` | 全局并发上限 |
| `recommended_concurrency` | 建议并发值（`total × max_inflight_per_account`） |
| `waiting` | 当前等待中的请求数 |
| `max_queue_size` | 等待队列上限 |

### `POST /admin/accounts/test`

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `identifier` | ✅ | email / mobile / token-only 合成标识 |
| `model` | ❌ | 默认 `deepseek-v4-flash` |
| `message` | ❌ | 空字符串时仅测试会话创建 |

**响应**：

```json
{
  "account": "user@example.com",
  "success": true,
  "response_time": 1240,
  "message": "API 测试成功（仅会话创建）",
  "model": "deepseek-v4-flash",
  "session_count": 0,
  "config_writable": true,
  "config_warning": ""
}
```

如果传入 `message`，还会附带 `thinking`（当上游返回思考内容时）。

当部署环境配置文件路径不可写（例如容器内默认 `/app/config.json` 只读）时，登录与会话测试仍可继续；此时会返回 `config_warning` 提示 token 仅保存在内存、重启后丢失。

### `POST /admin/accounts/test-all`

可选请求字段：`model`

```json
{
  "total": 5,
  "success": 4,
  "failed": 1,
  "results": [...]
}
```

内部并发上限当前固定为 5。

### `POST /admin/accounts/sessions/delete-all`

清空指定账号的所有 DeepSeek 会话。请求体示例：

```json
{"identifier":"user@example.com"}
```

响应：

```json
{"success": true, "message": "删除成功"}
```

如果账号不存在或删除失败，`success` 会是 `false`，`message` 会返回错误原因。

### `POST /admin/import`

批量导入 keys 与 accounts。

**请求**：

```json
{
  "keys": ["k1", "k2"],
  "accounts": [
    {"email": "user@example.com", "password": "pwd", "token": ""}
  ]
}
```

**响应**：

```json
{
  "success": true,
  "imported_keys": 2,
  "imported_accounts": 1
}
```

### `POST /admin/test`

测试当前 API 可用性（通过自身接口调用）。

| 字段 | 必填 | 默认值 |
| --- | --- | --- |
| `model` | ❌ | `deepseek-v4-flash` |
| `message` | ❌ | `你好` |
| `api_key` | ❌ | 配置中第一个 key |

**响应**：

```json
{
  "success": true,
  "status_code": 200,
  "response": {"id": "..."}
}
```

### `POST /admin/dev/raw-samples/capture`

直接通过服务自身发起一次 `/v1/chat/completions` 请求，并把请求元信息和上游原始 SSE 保存到 `tests/raw_stream_samples/<sample-id>/`。

常用请求字段：

| 字段 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `message` | 否 | `你好` | 便捷单轮用户消息 |
| `messages` | 否 | 自动由 `message` 生成 | OpenAI 风格消息数组 |
| `model` | 否 | `deepseek-v4-flash` | 目标模型 |
| `stream` | 否 | `true` | 建议保留流式，以记录原始 SSE |
| `api_key` | 否 | 配置中第一个 key | 调用业务接口使用的 key |
| `sample_id` | 否 | 自动生成 | 样本目录名 |

成功时会在响应头里附带：

- `X-Ds2-Sample-Id`
- `X-Ds2-Sample-Dir`
- `X-Ds2-Sample-Meta`
- `X-Ds2-Sample-Upstream`

如果请求本身成功，但当前进程没有记录到新的上游抓包，会返回：

```json
{"detail":"no upstream capture was recorded"}
```

### `GET /admin/dev/raw-samples/query`

按关键词查询当前进程内存里的抓包记录，并按 `chat_session_id` 归并 `completion + continue` 链。

**查询参数**：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `q` | 空 | 按请求体/响应体关键词模糊匹配 |
| `limit` | `20` | 返回链条数上限 |

**响应字段**包含：

- `items[].chain_key`
- `items[].capture_ids`
- `items[].round_count`
- `items[].initial_label`
- `items[].request_preview`
- `items[].response_preview`

### `POST /admin/dev/raw-samples/save`

把当前内存中的某条抓包链落盘为 `tests/raw_stream_samples/<sample-id>/`。

支持以下任一种选中方式：

```json
{"chain_key":"session:xxxx","sample_id":"tmp-from-memory"}
```

```json
{"capture_id":"cap_xxx","sample_id":"tmp-from-memory"}
```

```json
{"query":"广州天气","sample_id":"tmp-from-memory"}
```

成功响应会返回 `sample_id`、`dir`、`meta_path`、`upstream_path`。

### `POST /admin/vercel/sync`

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `vercel_token` | ❌ | 空或 `__USE_PRECONFIG__` 则读环境变量，再回退到已保存配置 |
| `project_id` | ❌ | 空则读 `VERCEL_PROJECT_ID`，再回退到已保存配置 |
| `team_id` | ❌ | 空则读 `VERCEL_TEAM_ID`，再回退到已保存配置 |
| `auto_validate` | ❌ | 默认 `true` |
| `save_credentials` | ❌ | 默认 `true`；保存本次显式填写的 Vercel 凭据，供下次同步复用 |
| `config_override` | ❌ | 传入完整配置对象，覆盖当前内存配置用于同步 |

**成功响应**：

```json
{
  "success": true,
  "validated_accounts": 3,
  "message": "配置已同步，正在重新部署...",
  "deployment_url": "https://..."
}
```

或需要手动部署：

```json
{
  "success": true,
  "validated_accounts": 3,
  "message": "配置已同步到 Vercel，请手动触发重新部署",
  "manual_deploy_required": true
}
```

失败校验的账号会通过 `failed_accounts` 返回；成功保存到 Vercel 的凭据会通过 `saved_credentials` 返回。

### `GET /admin/vercel/status`

也支持 `POST /admin/vercel/status`，可提交 `config_override` 用于比对草稿是否与已同步配置一致。

```json
{
  "synced": true,
  "last_sync_time": 1738400000,
  "has_synced_before": true,
  "env_backed": false,
  "config_hash": "....",
  "last_synced_hash": "....",
  "draft_hash": "....",
  "draft_differs": false
}
```

`POST /admin/vercel/status` 还可以携带 `config_override`，用于对比“草稿配置”和当前已同步配置。

### `GET /admin/export`

```json
{
  "json": "{...}",
  "base64": "ey4uLn0="
}
```

该接口与 `GET /admin/config/export` 返回相同内容，只是路径更短。

### `GET /admin/version`

查询当前构建版本与 GitHub 最新 Release：

```json
{
  "success": true,
  "current_version": "3.0.0",
  "current_tag": "v3.0.0",
  "source": "file:VERSION",
  "checked_at": "2026-03-29T00:00:00Z",
  "latest_tag": "v3.0.0",
  "latest_version": "3.0.0",
  "release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v3.0.0",
  "published_at": "2026-03-28T12:00:00Z",
  "has_update": false
}
```

如果 GitHub API 不可用，响应里会额外包含 `check_error`，但 HTTP 状态仍为 200。

### `GET /admin/dev/captures`

查看本地抓包状态与最近记录（需 Admin 鉴权）：

- `enabled`
- `limit`
- `max_body_bytes`
- `items`

### `DELETE /admin/dev/captures`

清空抓包记录，返回：

```json
{"success":true,"detail":"capture logs cleared"}
```

### `GET /admin/chat-history`

查询服务器端对话记录，支持筛选与分页。

**查询参数**：

| 参数 | 默认 | 匹配方式 |
| --- | --- | --- |
| `caller` | 空 | 与 `caller_id` 全等（取值用响应里的 `callers[].caller_id`，不是 Key 名称） |
| `status` | 空 | 与记录状态不区分大小写全等：`streaming` / `success` / `error` / `stopped` |
| `surface` | 空 | 与来源接口不区分大小写全等，如 `openai.chat_completions`、`openai.responses`、`claude.messages`、`gemini.generate_content` |
| `q` | 空 | 不区分大小写包含匹配，命中 `user_input` / `preview` / `model` / `caller_label` / `error` |
| `offset` | `0` | 分页偏移；`offset` 与 `limit` 都为 `0` 表示不分页 |
| `limit` | `0` | 单页条数；`0` 表示不限制条数（不按 settings 的保留条数分页） |

非法或负数的 `offset` / `limit` 按 `0` 处理。

**响应**：

```json
{
  "version": 2,
  "limit": 20,
  "revision": 128,
  "total": 137,
  "callers": [
    {"caller_id": "caller:9f2c1a2b3c4d5e6f", "label": "主 Key", "configured": true, "count": 96},
    {"caller_id": "caller:41ab0c9d8e7f6a5b", "label": "备用 Key", "configured": true, "count": 0}
  ],
  "items": [
    {
      "id": "chat_20260418_093012_ab12",
      "status": "success",
      "caller_id": "caller:9f2c1a2b3c4d5e6f",
      "caller_label": "主 Key",
      "account_id": "user@example.com",
      "surface": "openai.chat_completions",
      "model": "deepseek-v4-flash",
      "stream": true,
      "user_input": "今天的新闻",
      "preview": "……",
      "status_code": 200,
      "elapsed_ms": 4210,
      "finish_reason": "stop",
      "created_at": 1777000000000,
      "updated_at": 1777000004000,
      "detail_revision": 3
    }
  ],
  "path": "/data/chat_history.json"
}
```

- `total` 是筛选后的总条数，`items` 是分页后的当前页；不带任何筛选/分页参数时 `items` 仍是全部摘要。
- `caller_label` 是发起方 API Key 的可读标签（名称 / 备注 / 脱敏 Key），没有备注时退回脱敏值，避免面板里只剩一串哈希。
- `callers` 汇总记录里出现过的 `caller_id`，并补上配置里已登记但还没有记录的 Key（`count` 为 `0`，`configured=true`），按 `count` 倒序、`label` 升序排列。
- 时间戳字段（`created_at` / `updated_at` / `completed_at`）单位是毫秒。
- `If-None-Match` + `ETag` 的 `304` 协商只在**不带任何筛选/分页参数**时生效，因为带参数的响应内容本身随查询条件变化。

### `GET /admin/chat-history/{id}`

查看单条记录全文，响应为 `{"item": {...}}`。除摘要字段外还包含 `messages`、`history_text`（历史拆分上传的对话记录全文）、`final_prompt`、`reasoning_content`、`content`、`error`、`usage`、`file_infos`（上传文件 ID、审核结果、来源）等。同样支持 `ETag` / `304`。

### `DELETE /admin/chat-history`

清空全部服务器端记录，返回 `{"success": true}`。

### `DELETE /admin/chat-history/{id}`

删除单条记录，返回 `{"success": true}`；记录不存在返回 `404`。

### `PUT /admin/chat-history/settings`

更新保留条数。`limit` 接受 `0`..`500` 的任意整数，不再是固定档位。

```json
{"limit": 120}
```

| 取值 | 行为 |
| --- | --- |
| `0` | 关闭记录：不再写新记录 |
| `1`..`500` | 保留最近该数量的记录，超出部分按创建时间淘汰 |
| 其他 | 返回 `400`，`detail` 为 `unsupported chat history limit: <n>` |

响应带 `success`、`limit`、`revision` 与裁剪后的 `items`。

### `GET /admin/chat-history/export`

按与列表接口相同的筛选与分页参数（`caller` / `status` / `surface` / `q` / `offset` / `limit`）导出记录，响应是文件下载。

| 参数 | 说明 |
| --- | --- |
| `format=json`（默认） | JSON 附件，结构为 `{exported_at, count, filters, items}`；`exported_at` 为 RFC3339，`filters` 回显本次筛选条件，`items` 是完整记录（含 `messages` / `final_prompt` / `history_text` 等大字段） |
| `format=markdown` | Markdown 附件，标题 `# ds2api 响应记录导出`，逐条记录 `## N. <记录 ID>` 分节，含时间、接口、模型、账号、调用方、状态、耗时、结束原因，以及 `UserInput` / `FinalPrompt` / `ReasoningContent` / `Content` / `Error` 代码块 |
| 其他值 | 返回 `400`，`detail` 为 `unsupported export format: <format>` |

响应头带 `Content-Disposition: attachment`（文件名为 `ds2api-logs-<YYYYMMDD-HHMMSS>.json|.md`）与 `Cache-Control: no-store`。导出过程中若某条记录已被删除，该条会被跳过，`count` 反映实际导出的条数。

---

## 错误响应格式

兼容路由（`/v1/*`、`/anthropic/*`）统一使用以下结构：

```json
{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": null
  }
}
```

Admin 接口保持 `{"detail":"..."}`。

Gemini 路由使用 Google 风格错误结构：

```json
{
  "error": {
    "code": 400,
    "message": "invalid json",
    "status": "INVALID_ARGUMENT"
  }
}
```

建议客户端处理逻辑：检查 HTTP 状态码 + 解析 `error` 或 `detail` 字段。

**常见状态码**：

| 状态码 | 说明 |
| --- | --- |
| `401` | 鉴权失败（key/token 无效，或 Admin JWT 过期） |
| `429` | 请求过多（超出并发上限 + 等待队列，或上游账号 thinking-only 后仍无可见输出；托管账号模式会先尝试一次切号 fresh retry；当前不附带 `Retry-After` 头） |
| `503` | 模型不可用或上游服务异常 |

---

## cURL 示例

### OpenAI 非流式

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'
```

### OpenAI 流式

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "解释一下量子纠缠"}],
    "stream": true
  }'
```

### OpenAI Responses（流式）

```bash
curl http://localhost:5001/v1/responses \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "写一个 golang 的 hello world",
    "stream": true
  }'
```

### OpenAI Embeddings

```bash
curl http://localhost:5001/v1/embeddings \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": ["第一段文本", "第二段文本"]
  }'
```

### OpenAI 带搜索

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-search",
    "messages": [{"role": "user", "content": "今天的新闻"}],
    "stream": true
  }'
```

### OpenAI Tool Calling

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "北京今天天气怎么样？"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取指定城市的天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'
```

### Gemini 非流式

```bash
curl "http://localhost:5001/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "用三句话介绍 Go 语言"}]
      }
    ]
  }'
```

### Gemini 流式

```bash
curl "http://localhost:5001/v1beta/models/gemini-2.5-flash:streamGenerateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "写一个简短摘要"}]
      }
    ]
  }'
```

### Claude 非流式

```bash
curl http://localhost:5001/anthropic/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

### Claude 流式

```bash
curl http://localhost:5001/anthropic/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "解释相对论"}],
    "stream": true
  }'
```

### Admin 登录

```bash
curl http://localhost:5001/admin/login \
  -H "Content-Type: application/json" \
  -d '{"admin_key": "admin"}'
```

### 指定账号请求

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Ds2-Target-Account: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```