feat(kling): 接入O1与3.0 Omni兼容接口

新增中国区可灵 V1 AK/SK Omni 协议与 API 2.0 兼容路径，补齐任务隔离、外部任务幂等、参数校验和 OpenAPI 文档。\n\n验证：O1 与 3.0 Omni 真实 V1 任务成功；Go、前端、依赖审计、迁移及 CI 脚本门禁通过。
2026-07-21 23:35:07 +08:00
parent e280c0875c
commit a596685e15
15 changed files with 2118 additions and 23 deletions
@@ -0,0 +1,79 @@
+# 可灵 O1 / 3.0 Omni 兼容接口
+
+网关兼容中国区可灵 V1 AK/SK Omni API 和 API 2.0 的调用路径。调用方只需要把可灵客户端的 `baseURL` 改为网关地址，并把认证改为 EasyAI Gateway API Key；中国区可灵 AK/SK 仅保存在网关平台配置中，不下发给调用方。
+
+生产环境统一配置：
+
+```text
+baseURL = https://ai.51easyai.com/api/kling
+Authorization = Bearer <EasyAI Gateway API Key>
+```
+
+本地环境使用 `baseURL = http://localhost:8088/api/kling`。旧的 `/kling` 前缀继续作为兼容别名保留。
+
+## V1（AK/SK 旧版协议兼容）
+
+创建任务：
+
+```http
+POST /v1/videos/omni-video
+Authorization: Bearer <EasyAI Gateway API Key>
+Content-Type: application/json
+
+{
+  "model_name": "kling-video-o1",
+  "prompt": "一只白色纸鹤飞过清晨的湖面",
+  "mode": "pro",
+  "duration": "5",
+  "aspect_ratio": "16:9",
+  "sound": "off",
+  "external_task_id": "client-task-001"
+}
+```
+
+`model_name` 支持：
+
+- `kling-video-o1`：O1，时长 3–10 秒；不带参考素材的纯文本任务只支持 5 或 10 秒。
+- `kling-v3-omni`：3.0 Omni，时长 3–15 秒，支持多镜头。
+
+查询和列表接口：
+
+```http
+GET /v1/videos/omni-video/{task_id}
+GET /v1/videos/omni-video?pageNum=1&pageSize=30
+```
+
+V1 支持并透传 `prompt`、`multi_shot`、`shot_type`、`multi_prompt`、`image_list`、`element_list`、`video_list`、`voice_list`、`sound`、`mode`、`aspect_ratio`、`duration`、`watermark_info`、`callback_url` 和 `external_task_id`。网关会校验模型时长、引用素材数量、参考视频数量以及参考视频与原生音频的互斥约束。
+
+## API 2.0
+
+创建任务：
+
+```http
+POST /omni-video/kling-o1
+POST /omni-video/kling-v3-omni
+```
+
+同时提供带显式版本前缀的等价别名：
+
+```http
+POST /v2/omni-video/kling-o1
+POST /v2/omni-video/kling-v3-omni
+```
+
+任务查询和列表：
+
+```http
+GET  /tasks?task_ids=<task_id>
+GET  /tasks?external_task_ids=<external_task_id>
+POST /tasks
+```
+
+上述任务接口也提供 `/v2/tasks` 别名。API 2.0 请求使用 `contents`、`settings` 和 `options`；网关会转换到相同的 V1 AK/SK 上游链路，因此 O1 和 3.0 Omni 使用同一套中国区平台凭据。
+
+## 安全约束
+
+- 调用方只使用 EasyAI Gateway API Key，不接触上游 AK/SK。
+- 任务查询按用户和当前 API Key 隔离，不能读取其他 Key 创建的任务。
+- `external_task_id` 在同一用户的可灵兼容任务范围内唯一。
+- 真实联调测试是显式启用且会产生可灵费用；测试凭据只放在 `.env.local`。