# 可灵 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/gateway-api/kling
Authorization = Bearer <EasyAI Gateway API Key>
```

本地环境使用 `baseURL = http://localhost:8088/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`。