From 08f32c4c4091f11c3398af6f26ec745d25fe744e Mon Sep 17 00:00:00 2001 From: "CJACK." <155826701+CJackHwang@users.noreply.github.com> Date: Sun, 19 Apr 2026 21:04:06 +0800 Subject: [PATCH] docs: align API docs with implemented routes --- API.en.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- API.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- README.MD | 4 ++-- README.en.md | 4 ++-- 4 files changed, 106 insertions(+), 6 deletions(-) diff --git a/API.en.md b/API.en.md index d363d3e..7d1ef36 100644 --- a/API.en.md +++ b/API.en.md @@ -108,6 +108,7 @@ Gemini-compatible clients can also send `x-goog-api-key`, `?key=`, or `?api_key= | POST | `/v1/responses` | Business | OpenAI Responses API (stream/non-stream) | | GET | `/v1/responses/{response_id}` | Business | Query stored response (in-memory TTL) | | POST | `/v1/embeddings` | Business | OpenAI Embeddings API | +| POST | `/v1/files` | Business | OpenAI Files upload (multipart/form-data) | | GET | `/anthropic/v1/models` | None | Claude model list | | POST | `/anthropic/v1/messages` | Business | Claude messages | | POST | `/anthropic/v1/messages/count_tokens` | Business | Claude token counting | @@ -131,9 +132,15 @@ Gemini-compatible clients can also send `x-goog-api-key`, `?key=`, or `?api_key= | GET | `/admin/config/export` | Admin | Export full config (`config`/`json`/`base64`) | | POST | `/admin/keys` | Admin | Add API key | | DELETE | `/admin/keys/{key}` | Admin | Delete API key | +| GET | `/admin/proxies` | Admin | List proxies | +| POST | `/admin/proxies` | Admin | Add proxy | +| PUT | `/admin/proxies/{proxyID}` | Admin | Update proxy (empty password keeps old secret) | +| DELETE | `/admin/proxies/{proxyID}` | Admin | Delete proxy (auto-unbind referenced accounts) | +| POST | `/admin/proxies/test` | Admin | Test proxy connectivity | | GET | `/admin/accounts` | Admin | Paginated account list | | POST | `/admin/accounts` | Admin | Add account | | DELETE | `/admin/accounts/{identifier}` | Admin | Delete account | +| PUT | `/admin/accounts/{identifier}/proxy` | Admin | Bind/unbind proxy for an account | | GET | `/admin/queue/status` | Admin | Account queue status | | POST | `/admin/accounts/test` | Admin | Test one account | | POST | `/admin/accounts/test-all` | Admin | Test all accounts | @@ -391,6 +398,21 @@ Business auth required. Returns OpenAI-compatible embeddings shape. > Requires `embeddings.provider`. Current supported values: `mock` / `deterministic` / `builtin`. If missing/unsupported, returns standard error shape with HTTP 501. +### `POST /v1/files` + +Business auth required. OpenAI Files-compatible upload endpoint; currently only `multipart/form-data` is supported. + +| Field | Type | Required | Notes | +| --- | --- | --- | --- | +| `file` | file | ✅ | Binary payload | +| `purpose` | string | ❌ | Forwarded purpose field | + +Constraints and behavior: + +- `Content-Type` must be `multipart/form-data` (otherwise `400`). +- Total request size limit is `100 MiB` (over-limit returns `413`). +- Success returns an OpenAI `file` object (`id/object/bytes/filename/purpose/status`, etc.) and includes `account_id` for source-account tracing. + --- ## Claude-Compatible API @@ -723,6 +745,26 @@ Exports full config in three forms: `config`, `json`, and `base64`. **Response**: `{"success": true, "total_keys": 2}` +### `GET /admin/proxies` + +Lists proxy configs (password is never returned; use `has_password` as a marker). + +### `POST /admin/proxies` + +Adds a proxy. Request accepts `id` (optional; auto-generated when omitted), `name`, `type` (`http` / `socks5`), `host`, `port`, `username`, `password`. + +### `PUT /admin/proxies/{proxyID}` + +Updates a proxy. If `password` is an empty string, the existing secret is preserved. + +### `DELETE /admin/proxies/{proxyID}` + +Deletes a proxy and automatically clears `proxy_id` on all accounts that reference it. + +### `POST /admin/proxies/test` + +Tests proxy connectivity: provide `proxy_id` to test a saved proxy; omit it to run a one-off test using proxy fields in the request body. + ### `GET /admin/accounts` **Query params**: @@ -730,7 +772,7 @@ Exports full config in three forms: `config`, `json`, and `base64`. | Param | Default | Range | | --- | --- | --- | | `page` | `1` | ≥ 1 | -| `page_size` | `10` | 1–100 | +| `page_size` | `10` | 1–5000 | | `q` | empty | Filter by identifier / email / mobile | **Response**: @@ -771,6 +813,14 @@ Returned items also include `test_status`, usually `ok` or `failed`. **Response**: `{"success": true, "total_accounts": 5}` +### `PUT /admin/accounts/{identifier}/proxy` + +Updates proxy binding for a specific account. + +- Request body: `{"proxy_id":"..."}`. +- Use empty `proxy_id` to unbind proxy. +- `identifier` supports email / mobile / token-only synthetic id. + ### `GET /admin/queue/status` ```json diff --git a/API.md b/API.md index 6c73b05..b87332d 100644 --- a/API.md +++ b/API.md @@ -108,6 +108,7 @@ Gemini 兼容客户端还可以使用 `x-goog-api-key`、`?key=` 或 `?api_key=` | 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 | `/anthropic/v1/models` | 无 | Claude 模型列表 | | POST | `/anthropic/v1/messages` | 业务 | Claude 消息接口 | | POST | `/anthropic/v1/messages/count_tokens` | 业务 | Claude token 计数 | @@ -131,9 +132,15 @@ Gemini 兼容客户端还可以使用 `x-goog-api-key`、`?key=` 或 `?api_key=` | GET | `/admin/config/export` | Admin | 导出完整配置（含 `config`/`json`/`base64`） | | POST | `/admin/keys` | 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 | 添加账号 | | 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 | 测试全部账号 | @@ -397,6 +404,21 @@ data: [DONE] > 需配置 `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` 便于定位来源账号。 + --- ## Claude 兼容接口 @@ -729,6 +751,26 @@ data: {"type":"message_stop"} **响应**：`{"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` **查询参数**： @@ -736,7 +778,7 @@ data: {"type":"message_stop"} | 参数 | 默认 | 范围 | | --- | --- | --- | | `page` | `1` | ≥ 1 | -| `page_size` | `10` | 1–100 | +| `page_size` | `10` | 1–5000 | | `q` | 空 | 按 identifier / email / mobile 过滤 | **响应**： @@ -775,6 +817,14 @@ data: {"type":"message_stop"} **响应**：`{"success": true, "total_accounts": 5}` +### `PUT /admin/accounts/{identifier}/proxy` + +更新指定账号绑定代理。 + +- 请求体：`{"proxy_id":"..."}`； +- `proxy_id` 传空字符串时表示解绑代理； +- `identifier` 支持 email / mobile / token-only 合成标识。 + ### `GET /admin/queue/status` ```json diff --git a/README.MD b/README.MD index 4fda982..31ba76c 100644 --- a/README.MD +++ b/README.MD @@ -96,14 +96,14 @@ flowchart LR | 能力 | 说明 | | --- | --- | -| OpenAI 兼容 | `GET /v1/models`、`GET /v1/models/{id}`、`POST /v1/chat/completions`、`POST /v1/responses`、`GET /v1/responses/{response_id}`、`POST /v1/embeddings` | +| OpenAI 兼容 | `GET /v1/models`、`GET /v1/models/{id}`、`POST /v1/chat/completions`、`POST /v1/responses`、`GET /v1/responses/{response_id}`、`POST /v1/embeddings`、`POST /v1/files` | | Claude 兼容 | `GET /anthropic/v1/models`、`POST /anthropic/v1/messages`、`POST /anthropic/v1/messages/count_tokens`（及快捷路径 `/v1/messages`、`/messages`） | | Gemini 兼容 | `POST /v1beta/models/{model}:generateContent`、`POST /v1beta/models/{model}:streamGenerateContent`（及 `/v1/models/{model}:*` 路径） | | 多账号轮询 | 自动 token 刷新、邮箱/手机号双登录方式 | | 并发队列控制 | 每账号 in-flight 上限 + 等待队列，动态计算建议并发值 | | DeepSeek PoW | 纯 Go 高性能实现（DeepSeekHashV1），毫秒级响应 | | Tool Calling | 防泄漏处理：非代码块高置信特征识别、`delta.tool_calls` 早发、结构化增量输出 | -| Admin API | 配置管理、运行时设置热更新、账号测试 / 批量测试、会话清理、导入导出、Vercel 同步、版本检查 | +| Admin API | 配置管理、运行时设置热更新、代理管理、账号测试 / 批量测试、会话清理、导入导出、Vercel 同步、版本检查 | | WebUI 管理台 | `/admin` 单页应用（中英文双语、深色模式） | | 运维探针 | `GET /healthz`（存活）、`GET /readyz`（就绪） | diff --git a/README.en.md b/README.en.md index 6eafc67..23c2a94 100644 --- a/README.en.md +++ b/README.en.md @@ -94,14 +94,14 @@ For the full module-by-module architecture and directory responsibilities, see [ | Capability | Details | | --- | --- | -| OpenAI compatible | `GET /v1/models`, `GET /v1/models/{id}`, `POST /v1/chat/completions`, `POST /v1/responses`, `GET /v1/responses/{response_id}`, `POST /v1/embeddings` | +| OpenAI compatible | `GET /v1/models`, `GET /v1/models/{id}`, `POST /v1/chat/completions`, `POST /v1/responses`, `GET /v1/responses/{response_id}`, `POST /v1/embeddings`, `POST /v1/files` | | Claude compatible | `GET /anthropic/v1/models`, `POST /anthropic/v1/messages`, `POST /anthropic/v1/messages/count_tokens` (plus shortcut paths `/v1/messages`, `/messages`) | | Gemini compatible | `POST /v1beta/models/{model}:generateContent`, `POST /v1beta/models/{model}:streamGenerateContent` (plus `/v1/models/{model}:*` paths) | | Multi-account rotation | Auto token refresh, email/mobile dual login | | Concurrency control | Per-account in-flight limit + waiting queue, dynamic recommended concurrency | | DeepSeek PoW | Pure Go high-performance solver (DeepSeekHashV1), ms-level response | | Tool Calling | Anti-leak handling: non-code-block feature match, early `delta.tool_calls`, structured incremental output | -| Admin API | Config management, runtime settings hot-reload, account testing/batch test, session cleanup, import/export, Vercel sync, version check | +| Admin API | Config management, runtime settings hot-reload, proxy management, account testing/batch test, session cleanup, import/export, Vercel sync, version check | | WebUI Admin Panel | SPA at `/admin` (bilingual Chinese/English, dark mode) | | Health Probes | `GET /healthz` (liveness), `GET /readyz` (readiness) |