easyai
9d4501bc42
ci / verify (pull_request) Successful in 15m32s
新增中国区可灵 V1 AK/SK Omni 协议与 API 2.0 兼容路径，补齐任务隔离、外部任务幂等、参数校验和 OpenAPI 文档。\n\n验证：O1 与 3.0 Omni 真实 V1 任务成功；Go、前端、依赖审计、迁移及 CI 脚本门禁通过。
80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# 可灵 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`。
|