133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
# 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` 提供。
|