# Kling Omni 兼容接口

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` | 时长范围 |
| --- | --- | --- | --- |
| `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 /api/v1/videos/omni-video` 固定异步受理，不需要 `X-Async`，成功返回 HTTP 200。

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/api/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_ORIGIN/api/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_PUBLIC_API_BASE/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_PUBLIC_API_BASE/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 文档由服务的 `/api/v1/openapi.json` 和 `/api/v1/openapi.yaml` 提供。