Files

T

easyai 7c5a999e32 feat(api): 统一公开接口为 /api/v1 前缀

将通用生成、Gemini、可灵、火山、健康检查与 OpenAPI 的推荐入口统一到 /api/v1，并保留历史路径作为兼容别名。同步更新代理配置、接入文档、接口清单和前缀回归测试。\n\n验证：go vet ./...；go test ./...；pnpm openapi；pnpm lint；pnpm test；pnpm build；公开 OpenAPI 71 个方法与接口清单机器比对一致。

2026-07-22 08:48:32 +08:00

4.7 KiB

Raw Blame History

Kling Omni 兼容接口

EasyAI AI Gateway 提供 Kling 旧版 Omni 协议兼容接口。调用方继续使用 Gateway API Key，任务仍经过网关候选选择、异步队列、审计和计费；响应中的 task_id 是网关任务 UUID，不是上游任务 ID。

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。

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"
  }'

{
  "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。

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：

{
  "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} 轮询。

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"
  }'

curl -sS \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  "$GATEWAY_PUBLIC_API_BASE/tasks/$TASK_ID"

错误格式

所有兼容接口错误都返回同一包络：

{
  "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 提供。

4.7 KiB Raw Blame History Unescape Escape