easyai-ai-gateway/docs/public-api-v1.md

EasyAI Gateway 公开 API V1 清单

生产公开 API 的统一 Base URL：

https://ai.51easyai.com/api/v1

下表路径均以 /api/v1 开头。调用方使用 Authorization: Bearer <API Key>；标记为“公开”的接口不要求用户登录，OIDC 与 SSF 接口按各自协议鉴权。

旧 /gateway-api、/v1、无版本路径、/kling、/v1beta、/upload 和 /api/v3 入口仅作为兼容别名保留，不再用于新接入文档。

运行状态与接口发现

方法	路径	说明
GET	/api/v1/healthz	存活检查
GET	/api/v1/readyz	就绪检查
GET	/api/v1/openapi.json	OpenAPI JSON
GET	/api/v1/openapi.yaml	OpenAPI YAML
GET	/api/v1/public/identity	公开身份配置
GET	/api/v1/public/client-customization	公开客户端配置
GET	/api/v1/public/catalog/providers	公开供应商目录
GET	/api/v1/public/catalog/base-models	公开基础模型目录
GET	/api/v1/public/skills/ai-gateway-ops-management/metadata	运维 Skill 元数据
GET	/api/v1/public/skills/ai-gateway-ops-management/download	下载运维 Skill

账号、授权与 API Key

方法	路径	说明
POST	/api/v1/auth/register	注册本地账号
POST	/api/v1/auth/login	本地账号登录
GET	/api/v1/auth/oidc/login	发起 OIDC 登录
GET	/api/v1/auth/oidc/callback	OIDC 回调
POST	/api/v1/auth/oidc/logout	OIDC 登出
DELETE	/api/v1/auth/oidc/session	删除浏览器会话
GET	/api/v1/me	当前用户
GET, POST	/api/v1/api-keys	查询、创建 API Key
GET	/api/v1/api-keys/access-rules	查询 Key 访问规则
POST	/api/v1/api-keys/access-rules/batch	批量设置 Key 访问规则
GET	/api/v1/api-keys/assignable-models	查询可分配模型
PATCH	/api/v1/api-keys/{apiKeyID}/scopes	更新 Key 权限范围
PATCH	/api/v1/api-keys/{apiKeyID}/disable	禁用 Key
DELETE	/api/v1/api-keys/{apiKeyID}	删除 Key

模型、平台与计费查询

方法	路径	说明
GET	/api/v1/model-catalog	模型能力目录
GET	/api/v1/platforms	当前用户可用平台
GET	/api/v1/models	当前用户可用模型
GET	/api/v1/playground/models	Playground 可用模型
POST	/api/v1/pricing/estimate	请求价格预估

通用与 OpenAI 兼容生成接口

这些接口默认同步返回兼容响应；需要异步执行时增加 X-Async: true，并使用任务接口取回结果。

方法	路径	说明
POST	/api/v1/chat/completions	Chat Completions，支持 SSE
POST	/api/v1/responses	Responses，支持 SSE
POST	/api/v1/embeddings	文本向量
POST	/api/v1/reranks	文本重排序
POST	/api/v1/images/generations	文生图
POST	/api/v1/images/edits	图片编辑
POST	/api/v1/videos/generations	文生视频、图生视频及多模态视频
POST	/api/v1/song/generations	歌曲生成
POST	/api/v1/music/generations	音乐生成
POST	/api/v1/speech/generations	语音生成
POST	/api/v1/voice_clone	声音克隆
GET	/api/v1/voice_clone/voices	查询克隆声音
DELETE	/api/v1/voice_clone/voices/{voiceID}	删除克隆声音
POST	/api/v1/files/upload	上传生成任务输入文件

异步任务

方法	路径	说明
GET	/api/v1/tasks	查询任务列表
GET	/api/v1/tasks/{taskID}	查询任务详情和结果
POST	/api/v1/tasks/{taskID}/cancel	取消任务
GET	/api/v1/tasks/{taskID}/events	查询任务事件
GET	/api/v1/tasks/{taskID}/param-preprocessing	查询参数预处理记录

Gemini 兼容接口

方法	路径	说明
POST	/api/v1/models/{model}:generateContent	Gemini generateContent
POST	/api/v1/gemini/upload/{version}/files	Gemini Files 启动或直接上传，version 为 v1 或 v1beta
POST	/api/v1/gemini/upload/{version}/files/{uploadID}	完成 Gemini 分段上传

可灵兼容接口

方法	路径	说明
POST	/api/v1/videos/omni-video	可灵官方 V1 Omni 创建任务
GET	/api/v1/videos/omni-video/{taskID}	可灵官方 V1 Omni 查询任务
POST	/api/v1/kling/v1/videos/omni-video	网关可灵 V1 创建任务
GET	/api/v1/kling/v1/videos/omni-video	网关可灵 V1 任务列表
GET	/api/v1/kling/v1/videos/omni-video/{taskID}	网关可灵 V1 查询任务
POST	/api/v1/kling/v2/omni-video/{model}	网关可灵 API 2.0 创建任务
GET	/api/v1/kling/v2/tasks	网关可灵 API 2.0 查询任务
POST	/api/v1/kling/v2/tasks	网关可灵 API 2.0 任务列表

可灵客户端可使用 https://ai.51easyai.com/api/v1/kling 作为 Base URL，然后继续请求 /v1/... 或 /v2/...。

火山兼容与真人资产

方法	路径	说明
POST	/api/v1/contents/generations/tasks	创建火山内容生成任务
GET	/api/v1/contents/generations/tasks	查询火山内容生成任务列表
GET	/api/v1/contents/generations/tasks/{taskID}	查询火山内容生成任务
DELETE	/api/v1/contents/generations/tasks/{taskID}	删除或取消火山内容生成任务
POST	/api/v1/video/generations	server-main 兼容视频创建接口
GET	/api/v1/ai/result/{taskID}	server-main 兼容结果查询接口
GET	/api/v1/resource/material/seedance-portrait-assets/capability	真人资产能力
GET	/api/v1/resource/material/user/materials	查询用户真人资产
POST	/api/v1/resource/material	上传真人资产
POST	/api/v1/resource/material/seedance-portrait-assets/sync	同步真人资产到平台

安全集成

方法	路径	说明
POST	/api/v1/security-events/ssf	RFC 8935 Security Event 接收端点

不属于公开 API 的路径

• /api/admin/...：管理后台接口。
• /api/workspace/...、/api/playground/...：Web/BFF 内部接口。
• /metrics：仅监控网络可访问。
• /static/...：生成结果和上传文件的资源 URL，不是 API Base URL。