OpenAPI接口文档
如何调用后台API进行开发,即将上线,敬请期待.
EasyAI平台支持开放API,并且兼容OpenAI格式的绘图接口规范,轻松接入!
API的应用场景
- 二开形成新的应用、小程序或者APP,提供接口
- 接入硬件产品如AI相机、AI试装
- 接入企业内部其他生产系统
基础信息
- 基础路径:
/v1,EasyAI官方API的完整BaseURL为https://51easyai.com/api/v1 - 认证方式: 需要在请求头中携带
Authorization: Bearer {token} - 异步模式: 支持通过请求头
x-async: true或async: true启用异步模式(立即返回任务ID,不等待任务完成) - 消费记录: 少量交互列表查询与历史/批量记录下载请查看 消费记录查询与异步下载。历史消费使用异步导出任务,禁止循环费用列表接口抓取全量。
- 3D 模型: 文生 3D、图生 3D、多视图生成及模型编辑请查看 3D 模型 API
- 语音与音色: 完整参数、音色 ID 查询、情绪选项及自定义音色请查看 语音合成与音色 API
- 视频样片与正片: 先生成样片,再查询资格、预估费用并生成正片,见本文「9.1 视频样片与正片」。该流程与视频超分使用不同接口。
WebSocket 网关(新协议)
连接地址
- 域名部署(Nginx 反代)推荐:
wss://<your-domain>/socket.io?channel=<channel>&client_id=<clientId> - 本地直连调试:
ws://127.0.0.1:3002?channel=draw&client_id=user_1001 - 说明:网关本体是原生 WebSocket(
ws),/socket.io仅作为你部署层定义的反向代理路径 - 说明:
channel:通道隔离维度(如draw、login、admin)client_id:客户端标识(用于定向推送)
握手流程(MCP 风格)
- 客户端建立连接后,服务端先下发
session.challenge - 客户端发送
session.initialize - 服务端返回
session.initialized - 若开启鉴权(
WS_AUTH_REQUIRED=true),客户端发送session.authenticate - 鉴权通过后,服务端返回
session.authenticated+session.ready - 会话可用后再发送业务消息(
messageType=command)
握手报文示例
1) 服务端 -> 客户端:challenge
2) 客户端 -> 服务端:initialize
3)(可选)客户端 -> 服务端:authenticate
4) 服务端 -> 客户端:ready
浏览器最小示例(连接 + 握手 + 发命令)
服务端回执与心跳
- 命令接受成功:
type=command.accepted - 命令拒绝:
type=command.rejected - 心跳:客户端发送字符串
ping,服务端返回字符串pong
1. AI绘图/视频生成
接口说明
与OpenAI官方Dalle调用方式一样,用户利用接口创建token,携带token访问接口,model为工作流名称
方法 POST
路径 /v1/images/generations
请求示例
请求参数说明
prompt(string, 必填): 提示词model(string, 必填): 工作流名称或者模型名称size(string, 可选): OpenAI 兼容的像素尺寸,例如"1024x1024"n(number, 可选): 生成图片数量aspect_ratio(string, 可选): 输出图片的宽高比,例如"1:1"、"4:3"、"16:9"resolution(string, 可选): 输出分辨率档位,例如"1K"、"2K"、"4K";具体可选值以目标模型能力为准其他参数其他您在创建应用时定义的参数都是支持的
aspect_ratio 与 resolution 含义不同:aspect_ratio 控制画面比例,resolution 控制清晰度档位。不要把 "4:3" 传给 resolution。同一请求建议使用 aspect_ratio + resolution,或只使用兼容字段 size,不要同时传入互相冲突的尺寸参数。
2. 图片编辑
接口说明
支持图片编辑功能,可以通过文件上传或URL方式提供图片和遮罩
方法 POST
路径 /v1/images/edits
请求示例
方式一:上传本地文件(multipart/form-data,以豆包 4.5 图像编辑为例)
方式二:使用图片 URL(application/json)
方式三:浏览器上传 File 对象
不要手动设置上述请求的 Content-Type。浏览器会自动生成包含 boundary 的 multipart/form-data 请求头;手动设置后反而可能导致服务端无法读取文件。
图片比例、分辨率与像素尺寸
| 目的 | 参数 | 正确示例 | 常见错误 |
|---|---|---|---|
| 控制横竖构图 | aspect_ratio | "4:3" | 写成 resolution: "4:3" |
| 控制清晰度档位 | resolution | "2K" | 把它当成宽高比 |
| 指定兼容接口的像素尺寸 | size | "1024x768" | 与不一致的 aspect_ratio、resolution 同时传入 |
例如,要生成 4:3 的 2K 图片,应传:
1K、2K、4K 表示分辨率档位,不代表固定的一组宽高;服务端会结合 aspect_ratio 和模型能力换算最终像素尺寸。不同模型支持的比例和分辨率可能不同,提交前可调用 GET /v1/models/list?type=image_edit,读取目标模型 capabilities.image_edit 中的实时能力。示例中的 2K 仅用于说明参数格式。
浏览器的 File 对象不能直接放进 JSON 请求体。上传本地文件时必须使用 FormData;使用 application/json 时,image 必须是服务端可访问的图片 URL(或 URL 数组)。另外,JSON 请求中的 n 应传数字 1,不要传字符串 "1"。
请求参数说明
image(File | string | string, 必填): 图片文件(支持多文件上传)或图片URLmask(File | string, 可选): 遮罩文件或遮罩URLprompt(string, 必填): 编辑提示词model(string, 必填): 工作流名称size(string, 可选): OpenAI 兼容的像素尺寸,例如"1024x1024";与aspect_ratio、resolution冲突时结果可能被模型归一化aspect_ratio(string, 可选): 输出图片的宽高比,例如"1:1"、"4:3"、"16:9"resolution(string, 可选): 输出分辨率档位,例如"1K"、"2K"、"4K";具体可选值以目标模型能力为准seed(number, 可选): 随机种子n(number, 可选): 生成数量_metadata(string, 可选): JSON字符串格式的元数据
文件上传字段
files或image[]: 图片文件(最多16个)mask: 遮罩文件(最多1个)- 接口层最多接收 16 张图片,目标模型的数量限制可能更低
- 单个文件大小限制: 20MB
- 支持格式: jpg, jpeg, png, webp
3. 图片矢量化
接口说明
将 PNG、JPG、WebP 等位图转换为 SVG、EPS、PDF、DXF 等格式。该接口固定创建异步任务,提交成功后使用返回的公共 taskId 查询结果。
方法 POST
路径 /v1/images/vectorize
请求示例
请求参数说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
source | object | 是 | 来源图片信息 |
source.type | string | 是 | OpenAPI 调用推荐使用 image_url;站内上下文还支持 draw_history、canvas_node |
source.url | string | image_url 时是 | 带 http:// 或 https:// 的图片 URL,必须可被服务端访问 |
source.historyId | string | 否 | draw_history 来源的绘图历史记录 ID |
source.outputIndex | integer | 否 | 历史记录包含多张图时的索引,从 0 开始 |
format | string | 否 | 输出格式:svg、eps、pdf、dxf、png;默认 svg。其中 png 是兼容导出格式,不是矢量格式 |
maxColors | integer | 否 | 最大颜色数,0 表示自动;建议使用 0、2、4、8、16、32,范围 0~32 |
cleanupLevel | string | 否 | 路径清理强度:low、standard、strong;默认 standard |
OpenAPI 调用方通常只需要传 source.type=image_url 和 source.url。如果图片只存在于本地,请先使用 文件上传 获取 HTTPS URL。
提交响应示例
taskId、id、historyId是同一个公共任务 ID;轮询时使用其中的taskId。vectorizerTaskId是矢量化服务内部任务 ID,不要用它调用统一任务查询接口。- 使用
GET /v1/tasks/{taskId}查询结果。SVG/PNG 通常出现在result.images,EPS/PDF/DXF 通常出现在result.files。
4. AI对话
接口说明
与OpenAI官方Chat调用方式一样,用户利用接口创建token,携带token访问接口,model为工作流名称
方法 POST
路径 /v1/chat/completions
请求示例
请求参数说明
model(string, 必填): 工作流名称messages(array, 必填): 对话消息数组role(string): 角色,可选值:"system"|"user"|"assistant"content(string | array): 纯文本,或与 Agent / OpenAI 多模态 一致的 分片数组(见下节「content分片类型」)
stream(boolean, 可选): 是否流式返回,默认 trueconversationId(string, 可选): 会话IDsessionId(string, 可选): 会话ID
多模态说明(/v1/chat/completions)
- 建议先调用 20. 文件上传 拿到 HTTPS 可访问 URL,再填入
image_url/video_url/input_audio/file_url等字段。 - 部分类型也支持 base64:服务端会对
input_audio.data、file.file_data以及部分场景下的video_url.url(base64)做上传并替换为公网 URL,再转发下游模型。 - 若所选模型在平台上未标注图像/视频/音频理解能力,服务端可能将对应分片降级为纯文本链接,避免上游报错。
5. 文本向量(Embeddings)
接口说明
兼容 OpenAI Embeddings 请求和响应格式,可将单条或批量文本转换为向量。
方法 POST
路径 /v1/embeddings
请求示例
请求参数说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 向量模型名称或别名 |
input | string | string | number | number[] | 是 | 单条文本、批量文本或模型支持的 Token ID |
encoding_format | string | 否 | float 或 base64;省略时由模型采用默认格式 |
dimensions | integer | 否 | 输出向量维度,仅对支持自定义维度的模型生效 |
user | string | 否 | 调用方终端用户标识 |
响应示例
可通过 GET /v1/embeddings/models 获取可用向量模型,或调用 GET /v1/models/list?type=text_embedding 读取模型能力。
6. 文本重排序(Reranks)
接口说明
根据查询文本对候选文档进行相关性排序,适合在向量召回之后做精排。
方法 POST
路径 /v1/reranks
请求示例
请求参数说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 重排序模型名称或别名 |
query | string | 是 | 查询文本 |
documents | array | 是 | 字符串数组,或包含 text 字段的对象数组 |
top_n | integer | 否 | 最多返回的结果数量 |
return_documents | boolean | 否 | 是否在结果中返回原文档 |
max_chunks_per_doc | integer | 否 | 单篇文档允许使用的最大分块数,是否生效取决于模型 |
user | string | 否 | 调用方终端用户标识 |
响应示例
可通过 GET /v1/reranks/models 获取可用重排序模型,或调用 GET /v1/models/list?type=text_rerank。
7. Agent 流式响应 (responses)
调用 EasyAI Agent,使用 Agent 已配置的模型、知识库、MCP 工具和技能完成任务。接口固定以 SSE 返回运行过程和最终结果。
| 项目 | 值 |
|---|---|
| 方法 | POST |
| 路径 | /v1/agent/responses |
| 完整地址 | https://51easyai.com/api/v1/agent/responses |
| 认证 | Authorization: Bearer {API_KEY} |
| 请求类型 | 推荐 application/json;也支持 multipart/form-data 表单字段 |
| 响应类型 | text/event-stream |
Agent 接口是 /v1/agent/responses。/v1/responses 是 OpenAI Responses 兼容接口,用于直接调用模型,不会按 Agent 配置运行知识库、MCP 工具和技能。两个接口不能混用。
调用前准备
- 在 EasyAI 中创建 API Key,并通过
Authorization: Bearer {API_KEY}传入。 - 通过 18. 获取模型清单 确认
model名称。 - 如需调用指定 Agent,从 Agent 管理页面获取
agentId,并确认当前 API Key 所属用户有权使用该 Agent。 - 客户端生成唯一的
requestId。取消请求时必须使用同一个值。
最小可运行示例(curl)
curl --no-buffer 会在服务端产生事件时立即打印内容。正常结束时最后一条数据为 data: [DONE]。
调用指定 Agent
model当前仍为必填字段。调用指定 Agent 时,Agent 配置的默认模型可能覆盖请求中的model。conversationId用于关联已有会话标识和取消状态;sessionId用于在多轮调用中保持同一记忆会话。多轮对话请复用这两个值,每次请求则使用新的requestId。如需精确保留完整对话内容,仍应在input中传入所需历史消息。- 个人 Agent 使用自身已配置的技能;请求中的
skill_options不会替换个人 Agent 的技能配置。
使用临时技能
未指定 agentId 时,可以通过 skill_options 为本次调用增加系统技能、个人技能或临时技能:
多模态输入
建议先调用 20. 文件上传 获取可访问的 HTTPS URL,再放入 input[].content。不要直接把二进制文件附加到 Agent 接口。
支持的 content 分片如下:
type | 字段 | 说明 |
|---|---|---|
text | text | 文本内容,推荐写法 |
input_text | text | 兼容的文本写法;服务端会按文本处理 |
image_url | image_url.url,可选 detail | 图片 URL |
video_url | video_url.url,可选 detail | 视频 URL |
input_audio | input_audio.url 或 input_audio.data,可选 format | 音频 URL,或 base64 音频内容 |
audio_url | audio_url.url | 音频 URL 的兼容写法 |
file_url | file_url.url,可选 file_name | PDF、Office 文档等通用文件 URL;模型不支持文件时会按文件链接处理 |
平台会根据所选模型的图片、视频和音频理解能力处理媒体内容。模型不支持对应媒体类型时,媒体会作为文本链接提供给模型。file_url 主要用于把文件名称和 URL 提供给 Agent;如需解析文件正文,可让 Agent 使用已配置的文档解析工具。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
input | string | array | 是 | 用户输入。可传单个字符串,也可传消息数组。使用 multipart/form-data 时,消息数组需要先转成 JSON 字符串。 |
model | string | 是 | 模型名称或工作流名称。可从模型清单接口获取;指定个人 Agent 时,其默认模型可能覆盖此值。 |
stream | boolean | 否 | 兼容字段,建议传 true。本接口固定返回 SSE,传 false 不会改为普通 JSON 响应。 |
requestId | string | 否 | 本次请求的唯一标识。服务端可自动生成,但调用方无法提前用自动生成值取消请求,因此建议始终主动传入。 |
agentId | string | 否 | 要调用的 Agent ID。传入后使用该 Agent 的模型、知识库、MCP 工具和技能配置,并校验当前用户的使用权限。 |
conversationId | string | 否 | 已有会话 ID,用于关联会话标识和取消状态;不会自动把完整历史消息追加到 input。 |
sessionId | string | 否 | 记忆会话标识。需要跨请求保持同一 Agent 记忆时复用同一个值。 |
skill_options | object | 否 | 本次调用使用的技能选项。个人 Agent 会优先使用自身技能配置。 |
input 为消息数组时,每一项的字段如下:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | 推荐使用 user 或 assistant。system 消息会被忽略,系统指令应配置在 Agent 或技能中。 |
content | string | array | 是 | 文本或上表中的多模态分片数组。 |
skill_options 的字段如下:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
system_skill_ids | string[] | 否 | 当前用户可使用的公开系统技能 ID 列表。 |
personal_skill_ids | string[] | 否 | 当前用户拥有的个人技能 ID 列表。 |
ephemeral_skill | object | 否 | 仅本次调用有效的临时技能,不会保存为个人技能。 |
ephemeral_skill.name | string | 是 | 临时技能名称。 |
ephemeral_skill.description | string | 是 | 临时技能用途说明。 |
ephemeral_skill.instructions | string | 是 | 临时技能执行指令。 |
ephemeral_skill.references | array | 否 | 文本参考资料,每项包含 name 和 content。 |
ephemeral_skill.assets | array | 否 | 静态资源,每项包含 name、description、url 和 file_type。 |
multipart/form-data 请求
表单方式适合已有 FormData 调用链,但该接口不直接接收二进制附件。input 和 skill_options 等对象或数组必须先序列化为 JSON 字符串;文件仍需先上传,再传 URL。
使用 curl -F 时不要手动设置 Content-Type,curl 会自动添加包含 boundary 的正确请求头。
SSE 响应格式
响应头为 Content-Type: text/event-stream。每个事件使用以下格式发送:
常见事件如下:
外层 type | 内层类型 | 说明 |
|---|---|---|
raw_model_stream_event | data.type = output_text_delta | 文本增量,读取 data.delta 并按顺序拼接。 |
raw_model_stream_event | data.type = response_done | 本轮模型响应完成,data.response.output 包含完整输出,data.response.usage 包含用量。 |
run_item_stream_event | item.type = tool_call_item | Agent 开始调用工具,参数通常位于 item.rawItem.arguments。 |
run_item_stream_event | item.type = tool_call_output_item | 工具调用完成,结果通常位于 item.rawItem.output。 |
run_item_stream_event | item.type = message_output_item | 一条完整助手消息已生成,正文位于 item.rawItem.content。 |
agent_updated_stream_event | - | 运行中的 Agent 发生切换。没有使用多 Agent 协作时通常不需要处理。 |
error | - | 请求在流式传输期间失败,读取 message。 |
文本增量示例:
工具调用示例:
模型响应完成示例:
流结束时会收到:
客户端应忽略暂不认识的事件类型,避免服务端增加新事件后中断已有集成。
完整 JavaScript 调用与解析示例
以下示例适用于 Node.js 18 及以上版本,包含请求、SSE 分帧、文本拼接、错误处理和结束判断:
8. 取消 Agent 响应
使用发起 Agent 请求时传入的 requestId 取消仍在运行的请求。
| 项目 | 值 |
|---|---|
| 方法 | POST |
| 路径 | /v1/agent/responses/cancel/:requestId |
| 完整地址 | https://51easyai.com/api/v1/agent/responses/cancel/:requestId |
| 认证 | Authorization: Bearer {API_KEY} |
参数说明
- 路径参数
requestId(string,必填):要取消的请求 ID,必须与发起/v1/agent/responses请求时传入的值一致。 - 请求体
conversationId(string,可选):如该请求关联了会话,传入同一个会话 ID,以便同步标记会话消息状态。
成功响应示例:
9. 视频生成
接口说明
生成视频内容,支持文生视频、图生视频、视频参考、多模态编辑(O1/Omni 模式)等能力。
方法 POST
路径 /v1/video/generations
请求示例
示例一:文生视频
示例二:图生视频(首帧/参考图)
示例三:视频编辑(视频参考、多模态)
示例四:主体参考(O1 element 模式)
请求参数说明
model(string, 必填): 工作流名称content(array, 必填): 内容数组,每项为多模态内容块
content 项结构
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 内容类型: "text" | "image_url" | "audio_url" | "video_url" | "element" |
text | string | 文本内容(type=text 时必填) |
image_url | object | 图片对象 { url: string }(type=image_url 时必填) |
audio_url | object | 音频对象 { url: string }(type=audio_url 时必填) |
video_url | object | 视频对象(type=video_url 时必填) |
element | object | 主体参考(type=element 时必填,O1/Omni 模式) |
role | string | 角色/用途标识 |
name | string | 占位符名称(如 <<<image_1>>>) |
shot_index | number | 多镜头模式下的镜头索引 |
duration | number | 多镜头模式下该分镜时长(秒) |
role 取值说明(图片/视频参考)
| role | 说明 |
|---|---|
first_frame | 首帧图片,用于图生视频的起始画面 |
last_frame | 尾帧图片,指定生成视频的结束画面 |
digital_human_frame | 数字人参考帧 |
reference | 风格/角色参考图 |
video_feature | 视频特征参考(风格、动作等) |
video_base | 待编辑视频(视频编辑模式下作为源视频) |
shot_prompt | 分镜头提示词(多镜头模式) |
element | 主体参考(O1 新增) |
video_url 扩展字段
| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 视频 URL,支持 HTTP/HTTPS 或 base64 data URI |
refer_type | string | 参考类型: "feature" 特征参考 | "base" 待编辑视频 |
keep_original_sound | string | 是否保留原声: "yes" | "no" |
element 主体参考结构
| 字段 | 类型 | 说明 |
|---|---|---|
system_element_id | string | 系统主体库中的主体 ID |
inline_element | object | 内联主体详情,包含 name、description、frontal_image_url、refer_images 等 |
通用参数
aspect_ratio(string, 可选): 宽高比,默认 "adaptive",可选: "16:9" | "9:16" | "4:3" | "3:4" | "1:1" | "21:9" | "9:21" | "adaptive" | "keep_ratio"resolution(string, 可选): 分辨率,默认 "720p",可选: "480p" | "720p" | "1080p" | "1440p" | "2160p"duration(number, 可选): 时长(秒),默认 5audio(boolean, 可选): 是否生成/保留音频framespersecond(number, 可选): 帧率watermark(boolean, 可选): 是否添加水印,默认 falseseed(number, 可选): 随机种子,默认 -1camerafixed(boolean, 可选): 是否固定镜头,默认 falseratio/camera_fixed:火山原生宽高比与固定镜头字段;aspect_ratio/camerafixed继续兼容。普通生成和样片生成均保留原生参数,不能被内部默认值覆盖。camera_control(string, 可选): 镜头控制类型negative_prompt(string, 可选): 负面提示词(可灵)cfg_scale(number, 可选): CFG 权重(可灵)
9.1 视频样片与正片
本节为 EasyAI AIGC 平台接口,完整地址以 https://51easyai.com/api/v1 开头,沿用 Bearer Token 认证。独立 AI 网关的入口和字段不同,见本节末尾对照。以下示例说明接口结构,不代表当前账号已经开通模型或供应商能力。
本轮 H3 网关接入、火山参数兼容及期限调整的实现与文档正在同批交付,尚未发布业务服务;未升级实例继续使用原有接口。下文新增的兼容参数须由包含该能力的版本提供,不能仅凭文档站更新判断实例已支持。
第一步:确认能力并生成样片
通过 GET /v1/video/capabilities/:modelType 查询当前账号可用模型,按实际场景选择 video_generate、image_to_video 或 omni_video。所选模型及账号绑定必须显式开启 draft_mode,且其 input_modes 包含本次输入方式;目录中存在模型不等于当前账号可生成样片。
在原 POST /v1/video/generations 请求顶层增加布尔值 draft: true,并使用能力声明的 draft_resolution。建议携带 x-async: true,保存返回的 task_id,通过 GET /v1/tasks/:taskId 等待成功。
该示例为 Seedance 规格;H3 应使用其声明的样片规格。draft: false 或省略该字段仍为直接生成,普通低分辨率视频、上传视频和视频 URL 不会因此获得样片资格。
| 协议 | 样片请求规格 | 正片目标值 | 新提交有效期 |
|---|---|---|---|
| 火山 Seedance V1 | 480p | 1080p | 2026-10-28 10:00(北京时间)及之后创建的样片 14 天,此前为 7 天 |
| RunningHub Seedance V1 | 480p | 1080p | 保持该适配器的 7 天期限,以服务端截止时间为准 |
| MiniMax-H3 V2 | 720p | 1440p | 按能力声明;validity_seconds: 0 不设置固定任务引用期限,但样片及原始参考素材仍须可读 |
H3 界面显示的 768P / 2K 与 API 契约值不同;请求使用上表协议值,实际像素尺寸以生成产物为准。EasyAI 转接保留远端样片的有效期,不从转接时间重新计算。
火山期限从供应商原始 created_at 计算,不能用本地查询或重试时间续期。H3 使用原始生成上下文及样片视频的 base_video 方式生成 2K 正片,不依赖需要额外白名单的 MiniMax source_task_id 方式,也不把任意上传视频作为 H3 样片。依据:火山样片规则、MiniMax 再生成接口。
样片成功后,从任务的 result.videos[] 读取对应视频的 videoGeneration.resultId,例如 0123456789abcdef01234567:0,后续将此值原样作为 sourceResultId。公开元数据还可包含 schemaVersion、stage、resolution、finalResolutions、createdAt 和 finalizeExpiresAt;时间为 Unix 毫秒。不能用任务 ID、视频 URL 或供应商任务号代替结果引用,资格应再向服务端查询。
以下为样片任务成功响应的关键字段示例(省略其他字段,展示字段会受实例策略影响):
第二步:查询资格与已有正片
方法与路径:GET /v1/video/results/:resultId/finalization,将上一步的结果引用作为一个路径参数进行 URL 编码。
| 字段 | 含义与处理 |
|---|---|
eligible | 是否可以新建正片;提交时服务端仍会再次校验 |
targetResolutions | 可选目标,提交值必须来自该列表 |
expiresAt | 可选的新提交截止时间,Unix 毫秒;不能自行为无此字段的 V2 样片补上七天期限 |
existingTaskId / existingStatus / existingOutput | 已有关联正片任务时返回;继续查询或查看该任务,不直接再次提交 |
retryAfterTaskId | 曾有失败的正片任务,供确认原任务后决定是否发起新一次生成 |
reason | 不可新建的原因,如过期、原账号或模型不可用、源素材失效 |
已有进行中或已完成正片时,接口会优先返回已有任务,eligible 为 false;这不等于已有视频不可查看。来源不存在或无权访问返回 404,其他资格拒绝可能通过 eligible: false 和 reason 返回。这里的 existingStatus 使用平台历史状态,不应当作统一任务接口的 status 枚举;轮询仍用 GET /v1/tasks/:taskId。
第三步:单独预估正片费用
方法与路径:POST /v1/integration-platform/models/estimatedBilling。
服务端从原样片还原模型、账号、实际时长及计费参数,并按目标规格估价。样片和正片分别生成、分别计费,不能承诺两步合计一定比直接生成便宜。估价不会提交正片;实际受理时仍检查余额、配额和当前资格。
第四步:提交正片并查询结果
方法与路径:POST /v1/video/finalizations。
| 参数 | 类型 | 说明 |
|---|---|---|
sourceResultId | string,必填 | 服务端返回的具体样片结果引用 |
targetResolution | string,必填 | 1080p 或 1440p,还须符合来源资格 |
outputFormat | string,可选 | 火山支持 mp4 / mov,默认 mp4;H3 及当前 RunningHub 适配仅使用 mp4 |
watermark | boolean,可选 | 默认 false |
returnLastFrame | boolean,可选 | 默认 false;当前 H3 V2 不支持设为 true |
idempotencyKey | string,必填 | 8–128 位字母、数字、下划线或连字符;同一次确认及网络重试保留同一值 |
serviceTier | string,可选 | 火山 default / flex;Seedance 2.5 不支持 flex |
executionExpiresAfter | integer,可选 | 火山任务执行期限,3600–259200 秒;不是样片可引用期限 |
priority | integer,可选 | 火山任务优先级 0–9 |
callbackUrl | string,可选 | 状态回调地址;火山和 H3 可设置 |
safetyIdentifier | string,可选 | 火山安全标识 |
此接口还接受通用 options,但始终异步返回,例如:
submitted 仅表示任务已受理,不能当作已生成视频。继续调用 GET /v1/tasks/fedcba987654321001234567,直到 status: "succeeded",从 result.videos[] 读取正片;样片保留,正片另建任务。结果元数据可通过 videoGeneration.sourceResultId 关联原样片。
成片请求不接受新的 model、prompt、content、duration、audio、seed、platform_id 等生成参数,也不能换账号或模型版本。需要调整这些内容时,应重新生成样片。
同一用户使用相同 idempotencyKey 和相同成片请求会返回原 task_id;相同键对应不同来源、目标或选项时返回 409。接口不会仅凭相同 sourceResultId 合并所有新请求,所以客户端还须复用资格查询得到的已有任务。断网、查询超时或等待恢复时,先查询原任务,不更换键重复提交。确认失败且决定重新生成时才使用新键,该操作可能产生新的费用。截止时间限制新提交;已被供应商受理的原任务继续查询,不因到期自动重新生成。
火山请求参数兼容入口
也可在原 POST /v1/video/generations 中使用火山的参数结构生成正片。样片创建仍使用普通生成参数加 draft: true;正片请求的 content 仅包含一个 draft_task,其中 id 填本平台返回的样片 task_id(也兼容其具体 resultId),不能填其他账号或任意供应商任务号。响应和查询路径保持 EasyAI 原格式,不改为火山响应。
| 火山参数 | 平台专用成片接口字段 | 规则 |
|---|---|---|
model | 来源中已保存 | 须与原样片调用名或实际模型相同 |
content[].draft_task.id | sourceResultId | 须为当前账号的已完成样片,不能混入其他内容块 |
resolution | targetResolution | 按来源目标提交;Seedance 1080p,H3 扩展为 1440p(供应商 2K) |
output_format | outputFormat | 默认 mp4,火山还支持 mov |
return_last_frame | returnLastFrame | boolean,默认 false |
service_tier | serviceTier | 默认 default;模型不支持的档位拒绝 |
execution_expires_after | executionExpiresAfter | integer,3600–259200,火山默认 172800 秒 |
priority | priority | integer,0–9,火山默认 0 |
callback_url | callbackUrl | string |
safety_identifier | safetyIdentifier | string |
watermark 为 boolean,默认 false;draft 须省略或为 false。原提示词、素材、时长、比例、种子和音频从样片复用,不得在正片请求重新提交。H3 使用相同的引用参数结构,但只能生成本模型的 1440p / 2K,不支持 MOV、独立尾帧或火山专属调度/安全参数;显式请求不支持选项时返回错误,不静默丢弃。RunningHub 当前成片适配不接收新增的火山调度选项。
可通过 Header Idempotency-Key 保持同一次确认的请求身份;平台该兼容入口使用与专用成片接口相同的 8–128 位规则。未提供时每次请求视为新一次生成。建议携带 x-async: true,并保存受理响应的 task_id 继续查询;网络失败或样片到期后优先查询原正片任务,不反复提交。火山原生任务查询、取消及响应格式不在本次兼容范围内。
与独立 AI 网关的区别
| 项目 | AIGC 平台(本节) | 独立 AI 网关 |
|---|---|---|
| 常用完整生成路径 | /api/v1/video/generations | /api/v1/videos/generations |
| 火山参数正片提交 | /api/v1/video/generations | /api/v1/videos/generations |
| 平台专用正片提交 | /api/v1/video/finalizations,继续兼容 | 网关继续使用视频生成入口 |
| 来源字段 | JSON sourceResultId,具体结果引用 | JSON source_task_id,本账号的网关样片任务 ID |
| 目标字段 | JSON targetResolution | JSON resolution |
| 请求去重 | 专用成片接口用 JSON idempotencyKey,火山参数入口用 Header Idempotency-Key | HTTP Header Idempotency-Key |
| 样片正片协议 | Seedance V1、H3 V2,依实际绑定 | Volces / RunningHub Seedance,以及 MiniMax 原生 H3 V2(720p → 1440p) |
两端的火山风格参数均使用 content[].draft_task.id,但必须填写各自返回的样片任务身份,不能跨产品混用 ID。网关还兼容 source_task_id;平台专用成片接口仍使用 sourceResultId。网关请求结构、完整示例及限制见其仓库 docs/public-api-v1.md 的「视频样片与正片」;两种产品的接口说明不代表已经部署到某个实例。
10. 视频高清 / 超分
接口说明
对已有视频进行高清修复和分辨率提升。处理时间通常较长,建议开启异步模式并通过统一任务接口轮询。
方法 POST
路径 /v1/video/upscale
请求示例
也可以用明确的像素尺寸替代 target_resolution:
请求参数说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
video_url | string | 是 | 服务端可访问的源视频 HTTP/HTTPS URL |
model | string | 否 | 视频增强模型,默认 easy-proteus-standard-4 |
enhancement_model | string | 否 | 兼容字段;建议新调用统一使用 model |
target_resolution | string | 否 | 目标分辨率,常用值为 720p、1080p、2k、4k;默认 1080p |
output_resolution | string | 否 | target_resolution 的兼容字段 |
output_width | number | string | 否 | 自定义输出宽度;必须与 output_height 一起传入 |
output_height | number | string | 否 | 自定义输出高度;必须与 output_width 一起传入 |
output_frame_rate | number | string | 否 | 目标帧率,是否支持取决于所选模型 |
frame_interpolation_model | string | 否 | 补帧模型,是否支持取决于所选模型 |
slow_motion_rate | number | string | 否 | 慢动作倍率,是否支持取决于所选模型 |
preserve_audio | boolean | 否 | 是否保留原视频音频,默认 true |
target_resolution 与 output_width + output_height 任选一种即可;同时传入时,完整的宽高参数优先。不同模型支持的分辨率和操作可能不同,提交前请调用 GET /v1/models/list?type=video_enhance 读取 capabilities.video_enhance。
异步提交响应示例
建议忽略响应中的兼容字段 query_url,直接使用 GET /v1/tasks/{task_id}。成功后视频位于 result.videos。
当前内置模型包括:
easy-proteus-standard-4:通用标准增强,默认模型。easy-starlight-fast-2:速度优先。easy-starlight-hq-1:画质优先,耗时通常更长。easy-starlight-mini-1:轻量修复增强。
模型清单可能由部署方调整,应以 GET /v1/models/list?type=video_enhance 的实时返回为准。
11. 音乐生成
接口说明
同步提交和返回结果
方法 POST
路径 /v1/song/generations
请求示例
请求参数说明
prompt(string, 必填): 音频生成内容model(string, 必填): 模型名称makeInstrumental(boolean, 可选): 是否生成无声音的音频customMode(boolean, 可选): 是否使用自定义模型title(string, 可选): 歌曲标题tags(string, 必填): 风格标签negativeTags(string, 必填): 负面标签vocalGender(string, 可选): 人声性别偏好,"m" 男声,"f" 女声styleWeight(number, 可选): 对风格的遵循强度,范围 0-1,保留两位小数weirdnessConstraint(number, 可选): 创意/离散程度,范围 0-1,保留两位小数audioWeight(number, 可选): 音频要素权重,范围 0-1,保留两位小数
12. 语音合成
接口说明
将文本转换为音频,默认等待完成后返回音频 URL;请求头 x-async: true 可启用异步模式。
完整接入流程、参数表、返回示例和音色克隆接口请查看 语音合成与音色 API。
方法 POST
路径 /v1/speech/generations
请求示例
示例使用 MiniMax 模型与其预置音色;请以当前部署 GET /v1/models/list?type=text_to_speech 返回的模型别名和音色为准。
请求参数说明
model(string, 必填): 当前账号可用的语音合成模型别名,优先使用模型列表中的aliastext(string): 要朗读的文本,普通合成请求应填写voice_id(string): 音色 ID;预置音色取自所选模型的capabilities.text_to_speech.voices[].id,克隆音色取自本人克隆记录的voice_idcloned_voice_id(string, 可选): 本人克隆记录的id,用于明确指定克隆音色和原平台绑定speed、vol、pitch(number, 可选): 语速、音量、音调;范围取决于模型,原音调使用pitch: 0emotion(string, 可选): 模型支持的情绪字符串,例如 MiniMax 的happy;不需要申请 ID,省略时由模型自动选择voice_modify(object, 可选): MiniMax 声线微调(pitch、intensity、timbre,整数 -100~100)及单选音效sound_effects;仅 MP3/WAV/FLAC 支持audio_format、sample_rate、bit_rate、channel(可选): 输出格式、采样率、MP3 码率、声道;MiniMax 的取值、格式组合及原生字段映射见 详细参数表pronunciation_dict、language_boost(可选): MiniMax 发音词典与语言增强,私有部署需包含 2026-10-14 的参数补齐实现
如何获取音色和自定义音色
- 预置音色:
GET /v1/models/list?type=text_to_speech,读取所选模型的音色列表。 - 自定义音色:
POST /v1/voice_clone,提交录音创建克隆音色;GET /v1/voice_clone/voices查询本人记录,再将cloned_voice_id或voice_id用于合成。 - 模型支持参考音频时,也可传
reference_audio_url;参考音频与voice_id/cloned_voice_id互斥。具体能力与示例见 详细文档。
13. 创建数字人
接口说明
创建数字人形象
方法 POST
路径 /v1/digital-human/create
请求示例
请求参数说明
model(string, 必填): 工作流名称video_id(string, 必填): 视频IDinteraction_optimise(number, 可选): 是否开启针对直播的优化,1:开启 0:关闭,默认为开启
14. 生成数字人视频
接口说明
生成数字人视频
方法 POST
路径 /v1/digital-human/generations
请求示例
请求参数说明
model(string, 必填): 工作流名称resource_id(string, 必填): 数字人资源IDaudio_url(string, 必填): 音频路径image_url(string, 可选): 图片URLvideo_url(string, 可选): 视频URLtempl_start_strategy(string, 可选): 指定模板开始策略,可选值: "start_from_given_seconds"templ_start_seconds(number, 可选): 模版视频开始时间(仅对Lite模式生效),默认 0separate_vocal(boolean, 可选): 是否打开人声分离,开启后会抑制音频背景杂音open_scenedet(boolean, 可选): 是否打开场景切分与说话人识别(仅对Basic模式生效)align_audio(boolean, 可选): 是否开启视频循环(仅对Lite模式生效),默认 truealign_audio_reverse(boolean, 可选): 是否开启倒放循环(仅对Lite模式生效,需要同时开启align_audio),默认 false
15. 异步生成任务(已弃用)
接口说明
异步提交和返回任务,提交任务返回任务ID
该接口仅为旧版 ComfyUI 调用保留。新接入请调用对应的图片、视频、音乐等业务接口,并通过请求头 x-async: true 开启异步模式。
方法 POST
路径 /v1/ai/generations
请求示例
请求参数说明
params(object, 必填): ComfyUI属性参数对象prompt(string, 可选): 提示词width(number, 可选): 宽度height(number, 可选): 高度seed(number, 可选): 随机种子- 其他ComfyUI相关参数...
options(object, 可选): 选项result_retrieval(string, 可选): 结果获取方式,默认 "websocket"
16. 查询异步任务
接口说明
查询图片、图片编辑、图片矢量化、视频生成、视频超分、音乐等异步任务的统一状态和结果。
方法 GET
路径 /v1/tasks/:taskId
请求示例
响应示例
status:统一状态,可能为queued、running、succeeded、failed、cancelled。result:按媒体类型分组为images、videos、audios、files。cancellable:当前任务是否仍可取消;应以该字段为准,不要仅根据status猜测。- 失败时可能返回
errorMessage、error_code、upstream_status_code、upstream_request_id等可排障字段。
图片生成失败与预占释放
网关已经结束处理、但没有取回完整图片时,任务返回 failed,不再继续显示为执行中。errorMessage(旧结果接口为 message)说明当前结果及下一步操作;如果返回 user_message,也可用于展示。error_code 提供稳定的错误标识。例如:
- 收到终态
failed后,客户端应停止显示生成进度;retryable=false表示不要自动重新提交生成,也不要自动切换渠道再生成。 - 未取得完整图片且本次处理已结束时,主站返回失败,不收取本次生成费用并释放预占。
billing_status=released和charged_amount=0表示已经核实释放;若暂时释放失败则返回billing_status=release_pending,后台持续重试,此时不提前声明释放完成。 upstreamCompletionUnknown=true表示尚不能确认供应商是否完成生成;供应商成本由平台独立追查,不改变本次客户不收费的结论。原任务记录、上游编号和诊断证据继续保留,不因迟到回调重新扣费。reconciliation.state=needs_review表示本次自动处理已结束;deadlineAt是进入该核对状态的时点,不表示仍应等待生成。- 旧路径
/v1/ai/result/:taskId的同一任务使用status=failed和message返回原因,保留相同的错误码、阶段及核对标记。单次查询断线或暂时不可用属于查询错误,不能据此判定原生成任务失败或重发生成。
查询任务列表
路径 /v1/tasks
支持以下查询参数:
| 参数 | 类型 | 说明 |
|---|---|---|
task_type | string | 按任务类型过滤 |
status | string | queued、running、succeeded、failed、cancelled |
model | string | 按模型名称或别名过滤 |
created_after | string | number | 起始时间,可传 ISO 时间、秒级或毫秒级时间戳 |
created_before | string | number | 结束时间,可传 ISO 时间、秒级或毫秒级时间戳 |
page | integer | 页码,默认 1 |
page_size | integer | 每页数量,默认 20,最大 100 |
返回结构为 { items, total, page, page_size }。
旧路径 GET /v1/ai/result/:taskId 仍保留用于兼容历史客户端;新接入统一使用 GET /v1/tasks/:taskId。
17. 取消或删除任务
接口说明
取消尚可撤回的异步任务,或删除已经结束的任务记录。
取消方法 POST
取消路径 /v1/tasks/:taskId/cancel
请求示例
响应示例
仅仍在本地排队且尚未提交上游的任务保证可取消。若返回 cancelled: false,客户端应根据 message 继续轮询或提示用户。
删除方法 DELETE
删除路径 /v1/tasks/:taskId
运行中或已取消的任务不能删除;排队中的任务会转为取消操作,已成功或失败的任务记录可删除。
旧路径 GET /v1/ai/cancel/:taskId 仍保留用于兼容历史客户端。
18. 获取模型清单(OpenAI 兼容)
接口说明
返回当前可用的模型列表,遵循 OpenAI 官方的 models 接口规范,便于对接 OpenAI SDK 或第三方兼容客户端。
使用建议:本接口主要为兼容 OpenAI 格式设计,参数较少,返回结构固定。内部使用或需要按能力筛选模型时,建议使用下方「按能力类型查询模型列表」接口。
方法 GET
路径 /v1/models
请求示例
响应示例
响应字段说明
data(array): 模型列表,每项为 OpenAI 格式的模型对象success(boolean): 是否成功
响应数据模型(TypeScript)
19. 按能力类型查询模型列表
接口说明
根据模型能力类型查询可用模型,返回 PlatformModel 格式的完整模型信息。不传 type 或传 all 时返回所有模型。内部使用建议优先使用本接口,可精确按能力筛选、获取更丰富的模型元数据。
方法 GET
路径 /v1/models/list
请求示例
请求参数说明
type(string, 可选): 模型能力类型,不传或为all时返回所有模型。常用可选值:text_generate:文本对话text_embedding:文本向量text_rerank:文本重排序image_generate:图像生成image_edit:图像编辑image_vectorize:图片矢量化image_analysis:图像理解video_generate:视频生成video_enhance:视频高清 / 超分video_understanding:视频理解tools_call:工具调用audio_generate:音乐生成text_to_speech:语音合成digital_human_generate:数字人omni_video:多模态视频all:所有模型
响应示例
响应字段说明
modelList(array): 模型列表,每项为 PlatformModel 结构,含name、alias、types、provider等字段count(number): 模型数量
响应数据模型(TypeScript)
20. 文件上传
接口说明
开放接口上传文件,上传后为临时文件,24 小时后自动删除。支持 multipart/form-data 二进制上传或 base64 方式。上传成功后返回可访问的 URL,可在图片编辑、视频生成、Agent 等接口中作为 image_url、url 等参数使用。
方法 POST
路径 /v1/files/upload
请求示例
方式一:multipart/form-data 二进制上传
方式二:base64 图片上传(FormData)
请求参数说明
file(File | string, 必填): 文件内容- 二进制:
multipart/form-data中file字段,直接上传文件流 - Base64:
file字段传入 base64 字符串,支持data:image/xxx;base64,前缀(仅图片)
- 二进制:
fileName(string, 可选): 保存时的文件名,不传时使用原文件名或自动生成
限制说明
- 单文件大小:100MB
- 支持类型:图片(image/)、音频(audio/)、视频(video/*)及通用文件
- 存储策略:临时存储,24 小时后自动删除
响应示例
响应字段说明
success(boolean): 是否上传成功url(string): 上传后的文件可访问 URL,可在其他 API 中直接使用
异步模式说明
所有支持异步的接口(图片生成、图片编辑、视频生成、视频高清/超分、音乐生成、语音合成、数字人视频生成)都可以通过请求头启用异步模式:
- 请求头:
x-async: true或async: true或X-Async: true - 行为:
- 异步模式(header存在且值为 "true" 或 "1"): 立即返回任务ID,不等待任务完成
- 同步模式(默认): 等待任务完成后返回结果
图片矢量化 /v1/images/vectorize 始终为异步任务,不需要额外传 x-async。文本向量 /v1/embeddings 和文本重排序 /v1/reranks 为同步接口,不使用异步请求头。
异步模式示例
异步回调模式
除了通过查询接口获取任务结果外,系统还支持通过HTTP回调的方式主动推送任务结果到指定URL。
配置方式
在管理后台的系统配置 -> 运营配置 -> 任务调度 -> 任务回调地址中配置回调URL。
配置路径: 管理后台 → 系统配置 → 运营配置 → 任务调度 → 任务回调地址
配置说明:
- 配置后,系统会在任务状态更新时(包括进行中、成功、失败等状态)向该URL发送POST请求
- 回调URL必须是可公网访问的HTTP/HTTPS地址
- 建议配置HTTPS地址以保证数据安全
回调处理机制
- 任务状态的消息队列消费者会自动将任务结果推送到配置的回调URL
- 系统使用POST请求发送回调数据,Content-Type为
application/json - 系统会自动重试3次,如果3次都失败则放弃回调
- 回调数据即为任务状态数据,格式见下方说明
回调数据格式
回调请求的请求体为 IGenerateStatus 格式的JSON数据,结构如下:
回调数据字段说明
顶层字段
queue_status(object, 可选): 队列状态信息,包含任务执行状态和结果node_status(object, 可选): 工作流节点执行状态(仅在工作流任务中存在)usage(object, 可选): 使用量统计(OPENAI兼容的计费数据)callback_url(string, 可选): 回调地址user(object, 可选): 用户信息_id(string): 业务系统的用户IDsso_id(string, 可选): 主应用的用户ID
generate_info(object, 可选): 生成相关信息input(object): 扩展输入参数workflow(object): 工作流信息_id(string): 工作流ID
billings(array, 可选): 账单信息数组
queue_status 字段说明
task_id(string): 任务IDrequest_id(string, 可选): 请求IDserver(string, 可选): 服务器标识status(string): 任务状态,可选值:"submitted"|"started"|"process"|"success"|"failed"|"rejected"|"cancelled"queue(number, 可选): 队列位置data(object, 可选): 任务结果数据(DrawResponse格式)output_content(array, 可选): 输出内容数组(GeneralOutput格式)message(string, 可选): 状态消息original_error_message(string, 可选): 原始错误信息time_remained(number, 可选): 剩余时间(秒)progress(number, 可选): 进度百分比(0-100)
data 字段(DrawResponse)说明
task_id(string): 任务IDrequest_id(string, 可选): 请求IDstatus(string): 任务状态output(array, 可选): 输出URL数组output_content(array, 可选): 输出内容数组(GeneralOutput格式)billings(array, 可选): 账单信息type(string, 可选): 文件类型,可选值:"image"|"audio"|"video"|"text"|"3d"|"file"message(string, 可选): 消息original_error_message(string, 可选): 原始错误信息started_at(number, 可选): 开始时间戳(毫秒)finished_at(number, 可选): 结束时间戳(毫秒)mediaSize(object, 可选): 媒体尺寸type(string): 文件类型width(number): 宽度height(number): 高度status(number): 状态
queue_info(object, 可选): 队列信息queue(number, 可选): 队列位置taskId(string, 可选): 任务ID
output_content 字段(GeneralOutput)说明
type(string, 可选): 输出类型url(string, 可选): 输出URLb64_json(string, 可选): Base64编码的JSON数据content(string, 可选): 生成的内容role(string, 可选): 角色filename(string, 可选): 文件名mediaSize(object, 可选): 媒体尺寸uploaded(boolean, 可选): 是否已上传has_audio(boolean, 可选): 是否有音频
回调示例
成功状态回调示例
失败状态回调示例
进行中状态回调示例
回调接口实现建议
- 接口要求:
- 接收POST请求
- Content-Type:
application/json - 返回HTTP 200状态码表示接收成功
- 建议在3秒内响应,避免超时
- 数据验证:
- 验证任务ID的有效性
- 验证用户ID的权限
- 保存任务结果到数据库
- 幂等性处理:
- 系统可能会重复发送回调(虽然会自动重试),建议根据
task_id做幂等性处理 - 可以只处理
status为"success"或"failed"的最终状态
- 系统可能会重复发送回调(虽然会自动重试),建议根据
- 错误处理:
- 如果回调接口返回非200状态码,系统会重试3次
- 建议记录回调日志,便于排查问题
注意事项
- 所有接口都需要在请求头中携带有效的认证token
- 文件上传接口支持multipart/form-data格式
- 图片编辑接口支持文件上传和URL两种方式
- 异步任务可以通过查询接口获取结果,也可以配置回调URL接收推送
- 部分接口支持流式返回(如聊天接口)
- 回调URL配置后,系统会在任务状态更新时自动推送结果,无需轮询查询
工作流上传
建议使用ComfyUI-EasyAI插件进行工作流上传