feat(kling): 接入 Omni 视频兼容接口

2026-07-22 00:25:05 +08:00
parent b04a7d9d3d
commit 5a71643099
10 changed files with 1886 additions and 7 deletions
@@ -0,0 +1,132 @@
+# Kling Omni 兼容接口
+
+EasyAI AI Gateway 提供 Kling 旧版 Omni 协议兼容接口。调用方继续使用 Gateway API Key，任务仍经过网关候选选择、异步队列、审计和计费；响应中的 `task_id` 是网关任务 UUID，不是上游任务 ID。
+
+## 模型与参数映射
+
+| 请求 `model_name` | 网关模型别名 | TranStreams 原生 `model_name` | 时长范围 |
+| --- | --- | --- | --- |
+| `kling-video-o1`、`kling-o1` | `kling-o1` | `kling-video-o1` | 3–10 秒 |
+| `kling-v3-omni`、`kling-3.0-omni` | `kling-3.0-omni` | `kling-v3-omni` | 3–15 秒 |
+
+网关别名用于候选匹配，原生模型名用于发往 TranStreams 的 Kling Omni 请求；两类名称不会混用。
+
+`kling-video-o1` 的纯文生视频和首帧生视频只接受 5 或 10 秒；3–10 秒中的其他整数需要使用普通参考图等支持该时长的 Omni 输入。`kling-v3-omni` 接受 3–15 秒。
+
+真实上游结果表明 `kling-video-o1` 不生成音频，因此该模型的 `sound=on` 会返回 `1201`，标准接口的 `audio=true` 也会在参数预处理阶段失败，避免静默返回无声视频。`kling-v3-omni` 支持 `sound=on/off`。
+
+`mode` 映射为网关分辨率：`std` = 720p，`pro` = 1080p，`4k` = 2160p。4K 只有在平台模型能力也声明支持时才能执行。`sound=on/off` 映射为 `audio=true/false`，`duration` 同时接受 JSON 字符串和整数。
+
+兼容字段包括：`prompt`、`multi_shot`、`shot_type`、`multi_prompt`、`image_list`、`element_list`、`video_list`、`sound`、`mode`、`aspect_ratio`、`duration`、`watermark_info`、`external_task_id`。`callback_url` 可以省略或传空字符串；非空值会返回业务码 `1201`，本期不投递回调。
+
+## 创建任务
+
+`POST /v1/videos/omni-video` 固定异步受理，不需要 `X-Async`，成功返回 HTTP 200。
+
+```bash
+curl -sS -X POST "$GATEWAY_BASE_URL/v1/videos/omni-video" \
+  -H "Authorization: Bearer $GATEWAY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model_name": "kling-v3-omni",
+    "prompt": "A quiet street in the rain with natural ambient sound",
+    "mode": "pro",
+    "aspect_ratio": "9:16",
+    "duration": "5",
+    "sound": "on",
+    "watermark_info": {"enabled": false},
+    "external_task_id": "client-job-001"
+  }'
+```
+
+```json
+{
+  "code": 0,
+  "message": "SUCCEED",
+  "request_id": "...",
+  "data": {
+    "task_id": "00000000-0000-0000-0000-000000000000",
+    "task_info": {"external_task_id": "client-job-001"},
+    "task_status": "submitted",
+    "created_at": 0,
+    "updated_at": 0
+  }
+}
+```
+
+## 查询任务
+
+使用创建任务时的同一个 Gateway API Key 轮询。跨用户查询与不存在的任务统一返回 HTTP 404 和业务码 `1203`。
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $GATEWAY_API_KEY" \
+  "$GATEWAY_BASE_URL/v1/videos/omni-video/$TASK_ID"
+```
+
+`task_status` 为 `submitted`、`processing`、`succeed` 或 `failed`。成功时结果位于 `data.task_result.videos`：
+
+```json
+{
+  "code": 0,
+  "message": "SUCCEED",
+  "request_id": "...",
+  "data": {
+    "task_id": "00000000-0000-0000-0000-000000000000",
+    "task_status": "succeed",
+    "task_result": {
+      "videos": [
+        {
+          "id": "...",
+          "url": "https://.../video.mp4",
+          "watermark_url": "https://.../watermark.mp4",
+          "duration": "5"
+        }
+      ]
+    }
+  }
+}
+```
+
+## 网关标准视频接口
+
+标准接口仍为 `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" \
+  -H "Authorization: Bearer $GATEWAY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "X-Async: true" \
+  -d '{
+    "model": "kling-o1",
+    "prompt": "A product reveal in a daylight studio",
+    "resolution": "1080p",
+    "aspect_ratio": "9:16",
+    "duration": 5,
+    "audio": true,
+    "watermark": false,
+    "runMode": "real"
+  }'
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $GATEWAY_API_KEY" \
+  "$GATEWAY_BASE_URL/api/v1/tasks/$TASK_ID"
+```
+
+## 错误格式
+
+所有兼容接口错误都返回同一包络：
+
+```json
+{
+  "code": 1201,
+  "message": "duration must be between 3 and 10 seconds",
+  "request_id": "..."
+}
+```
+
+业务码分类：`1001/1002` 为鉴权错误，`1101/1103` 为余额或权限错误，`1201/1203` 为参数或资源错误，`1302/1303` 为限流错误，`5000/5001` 为网关或上游服务错误。HTTP 状态码仍反映错误类型。
+
+OpenAPI 文档由服务的 `/openapi.json` 和 `/openapi.yaml` 提供。