BCAI/easyai-ai-gateway
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(api): 统一公开接口为 /api/v1 前缀

Browse Source 
将通用生成、Gemini、可灵、火山、健康检查与 OpenAPI 的推荐入口统一到 /api/v1，并保留历史路径作为兼容别名。同步更新代理配置、接入文档、接口清单和前缀回归测试。\n\n验证：go vet ./...；go test ./...；pnpm openapi；pnpm lint；pnpm test；pnpm build；公开 OpenAPI 71 个方法与接口清单机器比对一致。
This commit is contained in:
easyai
2026-07-22 08:48:32 +08:00
parent f7a5f2e808
commit 7c5a999e32
38 changed files with 2294 additions and 5169 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design.md
+4 -4
View File
@@ -91,7 +91,7 @@ flowchart LR
QUEUE --> PG
QUEUE --> CALLBACK -->|POST task progress callback to server-main| WSGW
QUEUE -->|settlement event| BILL
API -->|POST /v1/files/upload| FILES
API -->|POST /api/v1/files/upload| FILES
```
## 4. Monorepo 方案
@@ -1785,9 +1785,9 @@ SimulationClient 根据 `simulation_profile` 生成确定性行为：
- `/chat/completions`
- `/images/generations`
- `/video/generations`
- `/v1/chat/completions`
- `/v1/images/generations`
- `/v1/video/generations`
- `/api/v1/chat/completions`
- `/api/v1/images/generations`
- `/api/v1/video/generations`
内部 `OpenaiService` 变成薄门面：
docs/kling-compatible-api.md
+2 -2
View File
@@ -5,11 +5,11 @@
生产环境统一配置：
```text
baseURL = https://ai.51easyai.com/gateway-api/kling
baseURL = https://ai.51easyai.com/api/v1/kling
Authorization = Bearer <EasyAI Gateway API Key>
```
本地环境使用 `baseURL = http://localhost:8088/kling`。
本地环境使用 `baseURL = http://localhost:8088/api/v1/kling`。旧 `/gateway-api/kling` 和 `/kling` 路径仅作为兼容别名保留。
## V1（AK/SK 旧版协议兼容）
docs/kling-omni-compatible.md
+12 -6
View File
@@ -2,6 +2,12 @@
EasyAI AI Gateway 提供 Kling 旧版 Omni 协议兼容接口。调用方继续使用 Gateway API Key，任务仍经过网关候选选择、异步队列、审计和计费；响应中的 `task_id` 是网关任务 UUID，不是上游任务 ID。
```bash
export GATEWAY_ORIGIN="https://ai.51easyai.com"
export GATEWAY_PUBLIC_API_BASE="$GATEWAY_ORIGIN/api/v1"
export GATEWAY_API_KEY="<EasyAI Gateway API Key>"
```
## 模型与参数映射
| 请求 `model_name` | 网关模型别名 | TranStreams 原生 `model_name` | 时长范围 |
@@ -21,10 +27,10 @@ EasyAI AI Gateway 提供 Kling 旧版 Omni 协议兼容接口。调用方继续
## 创建任务
`POST /v1/videos/omni-video` 固定异步受理，不需要 `X-Async`，成功返回 HTTP 200。
`POST /api/v1/videos/omni-video` 固定异步受理，不需要 `X-Async`，成功返回 HTTP 200。
```bash
curl -sS -X POST "$GATEWAY_BASE_URL/v1/videos/omni-video" \
curl -sS -X POST "$GATEWAY_ORIGIN/api/v1/videos/omni-video" \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
@@ -61,7 +67,7 @@ curl -sS -X POST "$GATEWAY_BASE_URL/v1/videos/omni-video" \
```bash
curl -sS \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
"$GATEWAY_BASE_URL/v1/videos/omni-video/$TASK_ID"
"$GATEWAY_ORIGIN/api/v1/videos/omni-video/$TASK_ID"
```
`task_status` 为 `submitted`、`processing`、`succeed` 或 `failed`。成功时结果位于 `data.task_result.videos`：
@@ -93,7 +99,7 @@ curl -sS \
标准接口仍为 `POST /api/v1/videos/generations`。异步调用需要 `X-Async: true`，再通过 `GET /api/v1/tasks/{taskId}` 轮询。
```bash
curl -sS -X POST "$GATEWAY_BASE_URL/api/v1/videos/generations" \
curl -sS -X POST "$GATEWAY_PUBLIC_API_BASE/videos/generations" \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Async: true" \
@@ -112,7 +118,7 @@ curl -sS -X POST "$GATEWAY_BASE_URL/api/v1/videos/generations" \
```bash
curl -sS \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
"$GATEWAY_BASE_URL/api/v1/tasks/$TASK_ID"
"$GATEWAY_PUBLIC_API_BASE/tasks/$TASK_ID"
```
## 错误格式
@@ -129,4 +135,4 @@ curl -sS \
业务码分类：`1001/1002` 为鉴权错误，`1101/1103` 为余额或权限错误，`1201/1203` 为参数或资源错误，`1302/1303` 为限流错误，`5000/5001` 为网关或上游服务错误。HTTP 状态码仍反映错误类型。
OpenAPI 文档由服务的 `/openapi.json` 和 `/openapi.yaml` 提供。
OpenAPI 文档由服务的 `/api/v1/openapi.json` 和 `/api/v1/openapi.yaml` 提供。
docs/public-api-v1.md
+137
View File
@@ -0,0 +1,137 @@
# EasyAI Gateway 公开 API V1 清单
生产公开 API 的统一 Base URL：
```text
https://ai.51easyai.com/api/v1
```
下表路径均以 `/api/v1` 开头。调用方使用 `Authorization: Bearer <API Key>`；标记为“公开”的接口不要求用户登录，OIDC 与 SSF 接口按各自协议鉴权。
旧 `/gateway-api`、`/v1`、无版本路径、`/kling`、`/v1beta`、`/upload` 和 `/api/v3` 入口仅作为兼容别名保留，不再用于新接入文档。
## 运行状态与接口发现
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v1/healthz` | 存活检查 |
| GET | `/api/v1/readyz` | 就绪检查 |
| GET | `/api/v1/openapi.json` | OpenAPI JSON |
| GET | `/api/v1/openapi.yaml` | OpenAPI YAML |
| GET | `/api/v1/public/identity` | 公开身份配置 |
| GET | `/api/v1/public/client-customization` | 公开客户端配置 |
| GET | `/api/v1/public/catalog/providers` | 公开供应商目录 |
| GET | `/api/v1/public/catalog/base-models` | 公开基础模型目录 |
| GET | `/api/v1/public/skills/ai-gateway-ops-management/metadata` | 运维 Skill 元数据 |
| GET | `/api/v1/public/skills/ai-gateway-ops-management/download` | 下载运维 Skill |
## 账号、授权与 API Key
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/auth/register` | 注册本地账号 |
| POST | `/api/v1/auth/login` | 本地账号登录 |
| GET | `/api/v1/auth/oidc/login` | 发起 OIDC 登录 |
| GET | `/api/v1/auth/oidc/callback` | OIDC 回调 |
| POST | `/api/v1/auth/oidc/logout` | OIDC 登出 |
| DELETE | `/api/v1/auth/oidc/session` | 删除浏览器会话 |
| GET | `/api/v1/me` | 当前用户 |
| GET, POST | `/api/v1/api-keys` | 查询、创建 API Key |
| GET | `/api/v1/api-keys/access-rules` | 查询 Key 访问规则 |
| POST | `/api/v1/api-keys/access-rules/batch` | 批量设置 Key 访问规则 |
| GET | `/api/v1/api-keys/assignable-models` | 查询可分配模型 |
| PATCH | `/api/v1/api-keys/{apiKeyID}/scopes` | 更新 Key 权限范围 |
| PATCH | `/api/v1/api-keys/{apiKeyID}/disable` | 禁用 Key |
| DELETE | `/api/v1/api-keys/{apiKeyID}` | 删除 Key |
## 模型、平台与计费查询
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v1/model-catalog` | 模型能力目录 |
| GET | `/api/v1/platforms` | 当前用户可用平台 |
| GET | `/api/v1/models` | 当前用户可用模型 |
| GET | `/api/v1/playground/models` | Playground 可用模型 |
| POST | `/api/v1/pricing/estimate` | 请求价格预估 |
## 通用与 OpenAI 兼容生成接口
这些接口默认同步返回兼容响应；需要异步执行时增加 `X-Async: true`，并使用任务接口取回结果。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/chat/completions` | Chat Completions，支持 SSE |
| POST | `/api/v1/responses` | Responses，支持 SSE |
| POST | `/api/v1/embeddings` | 文本向量 |
| POST | `/api/v1/reranks` | 文本重排序 |
| POST | `/api/v1/images/generations` | 文生图 |
| POST | `/api/v1/images/edits` | 图片编辑 |
| POST | `/api/v1/videos/generations` | 文生视频、图生视频及多模态视频 |
| POST | `/api/v1/song/generations` | 歌曲生成 |
| POST | `/api/v1/music/generations` | 音乐生成 |
| POST | `/api/v1/speech/generations` | 语音生成 |
| POST | `/api/v1/voice_clone` | 声音克隆 |
| GET | `/api/v1/voice_clone/voices` | 查询克隆声音 |
| DELETE | `/api/v1/voice_clone/voices/{voiceID}` | 删除克隆声音 |
| POST | `/api/v1/files/upload` | 上传生成任务输入文件 |
## 异步任务
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v1/tasks` | 查询任务列表 |
| GET | `/api/v1/tasks/{taskID}` | 查询任务详情和结果 |
| POST | `/api/v1/tasks/{taskID}/cancel` | 取消任务 |
| GET | `/api/v1/tasks/{taskID}/events` | 查询任务事件 |
| GET | `/api/v1/tasks/{taskID}/param-preprocessing` | 查询参数预处理记录 |
## Gemini 兼容接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/models/{model}:generateContent` | Gemini generateContent |
| POST | `/api/v1/gemini/upload/{version}/files` | Gemini Files 启动或直接上传，`version` 为 `v1` 或 `v1beta` |
| POST | `/api/v1/gemini/upload/{version}/files/{uploadID}` | 完成 Gemini 分段上传 |
## 可灵兼容接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/videos/omni-video` | 可灵官方 V1 Omni 创建任务 |
| GET | `/api/v1/videos/omni-video/{taskID}` | 可灵官方 V1 Omni 查询任务 |
| POST | `/api/v1/kling/v1/videos/omni-video` | 网关可灵 V1 创建任务 |
| GET | `/api/v1/kling/v1/videos/omni-video` | 网关可灵 V1 任务列表 |
| GET | `/api/v1/kling/v1/videos/omni-video/{taskID}` | 网关可灵 V1 查询任务 |
| POST | `/api/v1/kling/v2/omni-video/{model}` | 网关可灵 API 2.0 创建任务 |
| GET | `/api/v1/kling/v2/tasks` | 网关可灵 API 2.0 查询任务 |
| POST | `/api/v1/kling/v2/tasks` | 网关可灵 API 2.0 任务列表 |
可灵客户端可使用 `https://ai.51easyai.com/api/v1/kling` 作为 Base URL，然后继续请求 `/v1/...` 或 `/v2/...`。
## 火山兼容与真人资产
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/contents/generations/tasks` | 创建火山内容生成任务 |
| GET | `/api/v1/contents/generations/tasks` | 查询火山内容生成任务列表 |
| GET | `/api/v1/contents/generations/tasks/{taskID}` | 查询火山内容生成任务 |
| DELETE | `/api/v1/contents/generations/tasks/{taskID}` | 删除或取消火山内容生成任务 |
| POST | `/api/v1/video/generations` | server-main 兼容视频创建接口 |
| GET | `/api/v1/ai/result/{taskID}` | server-main 兼容结果查询接口 |
| GET | `/api/v1/resource/material/seedance-portrait-assets/capability` | 真人资产能力 |
| GET | `/api/v1/resource/material/user/materials` | 查询用户真人资产 |
| POST | `/api/v1/resource/material` | 上传真人资产 |
| POST | `/api/v1/resource/material/seedance-portrait-assets/sync` | 同步真人资产到平台 |
## 安全集成
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/security-events/ssf` | RFC 8935 Security Event 接收端点 |
## 不属于公开 API 的路径
- `/api/admin/...`：管理后台接口。
- `/api/workspace/...`、`/api/playground/...`：Web/BFF 内部接口。
- `/metrics`：仅监控网络可访问。
- `/static/...`：生成结果和上传文件的资源 URL，不是 API Base URL。
docs/runbooks/production-ci-cd.md
+4 -2
View File
@@ -126,9 +126,11 @@ dispatcher 以完整 Git SHA 发布 Registry Tag，并把 Registry 返回的 dig
## 发布后验证
宿主 Nginx 的 `ai.51easyai.com` TLS server 必须包含仓库中的 `deploy/nginx/ai.51easyai.com-api-v1.inc` 等价规则，保留完整 URI 转发到 `127.0.0.1:8088`。修改前先备份现有配置，执行 `nginx -t` 成功后才能 reload。
```bash
curl -fsS https://ai.51easyai.com/gateway-api/healthz
curl -fsS https://ai.51easyai.com/gateway-api/readyz
curl -fsS https://ai.51easyai.com/api/v1/healthz
curl -fsS https://ai.51easyai.com/api/v1/readyz
ssh root@110.42.51.33 'cd /root/easyai-ai-gateway-deploy && ./gateway-ops.sh ps'
```
docs/seedance-portrait-assets.md
+6 -4
View File
@@ -33,10 +33,12 @@
## 火山任务兼容路由
- `POST /api/v3/contents/generations/tasks`
- `GET /api/v3/contents/generations/tasks`
- `GET /api/v3/contents/generations/tasks/{taskID}`
- `DELETE /api/v3/contents/generations/tasks/{taskID}`
- `POST /api/v1/contents/generations/tasks`
- `GET /api/v1/contents/generations/tasks`
- `GET /api/v1/contents/generations/tasks/{taskID}`
- `DELETE /api/v1/contents/generations/tasks/{taskID}`
旧 `/api/v3/contents/generations/tasks` 路径仅作为火山客户端兼容别名保留。
列表接口兼容火山的 `page_num`、`page_size`、`filter.status`、`filter.task_ids`（可重复）和 `filter.model`，并返回官方 `items`、`total` 字段；`data`、`page` 是保留的网关附加字段。
docs/server-main-integration.md
+1 -1
View File
@@ -36,7 +36,7 @@ Content-Type: application/json
### 1.2 文件上传
```http
POST /v1/files/upload
POST /api/v1/files/upload
Authorization: Bearer ${USER_JWT_OR_SK}
Content-Type: multipart/form-data
docs/test/loopback-test-checklist.md
+2 -2
View File
@@ -53,7 +53,7 @@
| ID | 任务 | 接口 / 方式 | 成功判定 | 状态 | 结果记录 |
| --- | --- | --- | --- | --- | --- |
| SETUP-01 | 确认服务可用 | `GET /healthz`、`GET /readyz` | `healthz.ok=true`，`readyz.ok=true` | 未执行 | 待填写 |
| SETUP-01 | 确认服务可用 | `GET /api/v1/healthz`、`GET /api/v1/readyz` | `healthz.ok=true`，`readyz.ok=true` | 未执行 | 待填写 |
| SETUP-02 | 准备管理员权限 | 本地注册 / 登录，必要时将测试用户提升为 `admin` 或 `manager` | `GET /api/v1/me` 返回 `role` 具备 `manager` 权限 | 未执行 | 待填写 |
| SETUP-03 | 记录用户提供的真实平台、模型和 KEY | `GET /api/v1/platforms`、`GET /api/v1/models` | Chat 模型、`doubao-4.5图像编辑`、`豆包Seedance-1.5-pro` 均已启用，并能被管理员看到 | 未执行 | 待填写 |
| SETUP-04 | 创建内部测试用户组 | `POST /api/v1/user-groups` | 创建 `loopback-allow-group`、`loopback-deny-group`、`loopback-limit-group` | 未执行 | 待填写 |
@@ -91,7 +91,7 @@
| ID | 能力 | 请求 | 成功判定 | 状态 | 结果记录 |
| --- | --- | --- | --- | --- | --- |
| TASK-CHAT-01 | Chat 成功 | `POST /api/v1/chat/completions`，真实 Chat 模型 | `task.status=succeeded`，`result.object=chat.completion`，`choices[0].message.content` 非空 | 未执行 | taskId、requestId、content 摘要、charge 待填写 |
| TASK-CHAT-02 | Chat 兼容路由成功 | `POST /v1/chat/completions`，真实 Chat 模型 | HTTP 200，返回 `object=chat.completion`，内容非空 | 未执行 | requestId、content 摘要待填写 |
| TASK-CHAT-02 | Chat 同步兼容响应成功 | `POST /api/v1/chat/completions`，真实 Chat 模型 | HTTP 200，返回 `object=chat.completion`，内容非空 | 未执行 | requestId、content 摘要待填写 |
| TASK-IMAGE-01 | 文生图成功 | `POST /api/v1/images/generations`，模型 `doubao-4.5图像编辑` 或用户补充的文生图模型 | `task.status=succeeded`，`result.id` 非空，`data[0].url` 或文件 URL 可访问 | 未执行 | taskId、image URL、charge 待填写 |
| TASK-IMAGE-02 | 图生图成功 | `POST /api/v1/images/edits`，模型 `doubao-4.5图像编辑`，传入测试源图和 mask | `task.status=succeeded`，`result.id` 非空，`data[0].url` 或文件 URL 可访问 | 未执行 | taskId、source URL、mask URL、image URL、charge 待填写 |
| TASK-VIDEO-01 | 文生视频成功 | `POST /api/v1/videos/generations`，模型 `豆包Seedance-1.5-pro`，仅传 prompt | `task.status=succeeded`，返回可下载或可播放的视频结果，任务事件完整 | 未执行 | taskId、video URL、duration、charge 待填写 |