OpenAPI接口文档

如何调用后台API进行开发,即将上线,敬请期待.

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 风格)

  1. 客户端建立连接后,服务端先下发 session.challenge
  2. 客户端发送 session.initialize
  3. 服务端返回 session.initialized
  4. 若开启鉴权(WS_AUTH_REQUIRED=true),客户端发送 session.authenticate
  5. 鉴权通过后,服务端返回 session.authenticated + session.ready
  6. 会话可用后再发送业务消息(messageType=command)

握手报文示例

1) 服务端 -> 客户端:challenge

{
  "type": "session.challenge",
  "sessionId": "sess_xxx",
  "authRequired": true,
  "methods": ["bearer", "ws_ticket"],
  "challenge": "a1b2c3d4...",
  "timeoutMs": 6000
}

2) 客户端 -> 服务端:initialize

{
  "type": "session.initialize",
  "protocolVersion": "1.0",
  "client": "easyai-main-web"
}

3)(可选)客户端 -> 服务端:authenticate

{
  "type": "session.authenticate",
  "method": "bearer",
  "credential": "Bearer your_ws_token"
}

4) 服务端 -> 客户端:ready

{
  "type": "session.ready",
  "sessionId": "sess_xxx",
  "welcome": {
    "channel": "draw",
    "client_id": "user_1001"
  }
}

浏览器最小示例(连接 + 握手 + 发命令)

const channel = 'draw';
const clientId = 'user_1001';
const ws = new WebSocket(
  `wss://your-domain/socket.io?channel=${encodeURIComponent(channel)}&client_id=${encodeURIComponent(clientId)}`
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('WS <-', msg);

  if (msg.type === 'session.challenge') {
    ws.send(
      JSON.stringify({
        type: 'session.initialize',
        protocolVersion: '1.0',
        client: 'web-demo',
      })
    );
    return;
  }

  if (msg.type === 'session.initialized' && msg.authRequired) {
    ws.send(
      JSON.stringify({
        type: 'session.authenticate',
        method: 'bearer',
        credential: 'Bearer your_ws_token',
      })
    );
    return;
  }

  if (msg.type === 'session.ready') {
    ws.send(
      JSON.stringify({
        messageType: 'command',
        eventName: 'agent.approval',
        payload: {
          taskId: 'task_123',
          approved: true,
        },
      })
    );
  }
};

服务端回执与心跳

  • 命令接受成功:type=command.accepted
  • 命令拒绝:type=command.rejected
  • 心跳:客户端发送字符串 ping,服务端返回字符串 pong

1. AI绘图/视频生成

接口说明

与OpenAI官方Dalle调用方式一样,用户利用接口创建token,携带token访问接口,model为工作流名称

方法 POST

路径 /v1/images/generations

请求示例

{
  "prompt": "a cat",
  "size": "1024x1024",
  "model": "text2img",
  "n": 2
}

请求参数说明

  • prompt (string, 必填): 提示词
  • model (string, 必填): 工作流名称或者模型名称
  • size (string, 可选): OpenAI 兼容的像素尺寸,例如 "1024x1024"
  • n (number, 可选): 生成图片数量
  • aspect_ratio (string, 可选): 输出图片的宽高比,例如 "1:1"、"4:3"、"16:9"
  • resolution (string, 可选): 输出分辨率档位,例如 "1K"、"2K"、"4K";具体可选值以目标模型能力为准
  • 其他参数 其他您在创建应用时定义的参数都是支持的

2. 图片编辑

接口说明

支持图片编辑功能,可以通过文件上传或URL方式提供图片和遮罩

方法 POST

路径 /v1/images/edits

请求示例

方式一:上传本地文件(multipart/form-data,以豆包 4.5 图像编辑为例)

curl -X POST "https://51easyai.com/api/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "image[]=@/path/to/image.jpg" \
  -F "prompt=让人物在海滩奔跑" \
  -F "model=doubao-4.5图像编辑" \
  -F "aspect_ratio=4:3" \
  -F "resolution=2K" \
  -F "n=1"

方式二:使用图片 URL(application/json)

{
  "image": "https://example.com/image.jpg",
  "prompt": "让人物在海滩奔跑",
  "model": "doubao-4.5图像编辑",
  "aspect_ratio": "4:3",
  "resolution": "2K",
  "n": 1
}

方式三:浏览器上传 File 对象

const formData = new FormData();
formData.append('image[]', imageFile);
formData.append('prompt', '让人物在海滩奔跑');
formData.append('model', 'doubao-4.5图像编辑');
formData.append('aspect_ratio', '4:3');
formData.append('resolution', '2K');
formData.append('n', '1');

const response = await fetch('https://51easyai.com/api/v1/images/edits', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
  },
  body: formData,
});

const result = await response.json();

不要手动设置上述请求的 Content-Type。浏览器会自动生成包含 boundary 的 multipart/form-data 请求头;手动设置后反而可能导致服务端无法读取文件。

图片比例、分辨率与像素尺寸

目的参数正确示例常见错误
控制横竖构图aspect_ratio"4:3"写成 resolution: "4:3"
控制清晰度档位resolution"2K"把它当成宽高比
指定兼容接口的像素尺寸size"1024x768"与不一致的 aspect_ratio、resolution 同时传入

例如,要生成 4:3 的 2K 图片,应传:

{
  "aspect_ratio": "4:3",
  "resolution": "2K"
}

1K、2K、4K 表示分辨率档位,不代表固定的一组宽高;服务端会结合 aspect_ratio 和模型能力换算最终像素尺寸。不同模型支持的比例和分辨率可能不同,提交前可调用 GET /v1/models/list?type=image_edit,读取目标模型 capabilities.image_edit 中的实时能力。示例中的 2K 仅用于说明参数格式。

请求参数说明

  • image (File | string | string, 必填): 图片文件(支持多文件上传)或图片URL
  • mask (File | string, 可选): 遮罩文件或遮罩URL
  • prompt (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

请求示例

curl -X POST "https://51easyai.com/api/v1/images/vectorize" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "image_url",
      "url": "https://example.com/logo.png"
    },
    "format": "svg",
    "maxColors": 16,
    "cleanupLevel": "standard"
  }'

请求参数说明

字段类型必填说明
sourceobject是来源图片信息
source.typestring是OpenAPI 调用推荐使用 image_url;站内上下文还支持 draw_history、canvas_node
source.urlstringimage_url 时是带 http:// 或 https:// 的图片 URL,必须可被服务端访问
source.historyIdstring否draw_history 来源的绘图历史记录 ID
source.outputIndexinteger否历史记录包含多张图时的索引,从 0 开始
formatstring否输出格式:svg、eps、pdf、dxf、png;默认 svg。其中 png 是兼容导出格式,不是矢量格式
maxColorsinteger否最大颜色数,0 表示自动;建议使用 0、2、4、8、16、32,范围 0~32
cleanupLevelstring否路径清理强度:low、standard、strong;默认 standard

提交响应示例

{
  "id": "history_123",
  "taskId": "history_123",
  "historyId": "history_123",
  "vectorizerTaskId": "vectorizer_456",
  "status": "running",
  "submitted": true,
  "progress": 5,
  "message": "等待转换"
}
  • 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": "chat_workflow",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "stream": true,
  "conversationId": "conv_123",
  "sessionId": "session_456"
}

请求参数说明

  • model (string, 必填): 工作流名称
  • messages (array, 必填): 对话消息数组
    • role (string): 角色,可选值: "system" | "user" | "assistant"
    • content (string | array): 纯文本,或与 Agent / OpenAI 多模态 一致的 分片数组(见下节「content 分片类型」)
  • stream (boolean, 可选): 是否流式返回,默认 true
  • conversationId (string, 可选): 会话ID
  • sessionId (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

请求示例

curl -X POST "https://51easyai.com/api/v1/embeddings" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embedding-model-alias",
    "input": ["EasyAI 是企业级 AI 平台", "向量可用于语义检索"],
    "encoding_format": "float"
  }'

请求参数说明

字段类型必填说明
modelstring是向量模型名称或别名
inputstring | string | number | number[]是单条文本、批量文本或模型支持的 Token ID
encoding_formatstring否float 或 base64;省略时由模型采用默认格式
dimensionsinteger否输出向量维度,仅对支持自定义维度的模型生效
userstring否调用方终端用户标识

响应示例

{
  "object": "list",
  "model": "embedding-model-alias",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789],
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

可通过 GET /v1/embeddings/models 获取可用向量模型,或调用 GET /v1/models/list?type=text_embedding 读取模型能力。


6. 文本重排序(Reranks)

接口说明

根据查询文本对候选文档进行相关性排序,适合在向量召回之后做精排。

方法 POST

路径 /v1/reranks

请求示例

{
  "model": "rerank-model-alias",
  "query": "EasyAI 如何接入开放接口?",
  "documents": [
    "在后台创建 API Token,并通过 Bearer Token 调用。",
    "图片矢量化支持 SVG、EPS、PDF 和 DXF。"
  ],
  "top_n": 1,
  "return_documents": true
}

请求参数说明

字段类型必填说明
modelstring是重排序模型名称或别名
querystring是查询文本
documentsarray是字符串数组,或包含 text 字段的对象数组
top_ninteger否最多返回的结果数量
return_documentsboolean否是否在结果中返回原文档
max_chunks_per_docinteger否单篇文档允许使用的最大分块数,是否生效取决于模型
userstring否调用方终端用户标识

响应示例

{
  "object": "list",
  "model": "rerank-model-alias",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.982,
      "document": "在后台创建 API Token,并通过 Bearer Token 调用。"
    }
  ],
  "usage": {
    "total_tokens": 32
  }
}

可通过 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

调用前准备

  1. 在 EasyAI 中创建 API Key,并通过 Authorization: Bearer {API_KEY} 传入。
  2. 通过 18. 获取模型清单 确认 model 名称。
  3. 如需调用指定 Agent,从 Agent 管理页面获取 agentId,并确认当前 API Key 所属用户有权使用该 Agent。
  4. 客户端生成唯一的 requestId。取消请求时必须使用同一个值。

最小可运行示例(curl)

export EASYAI_API_KEY="替换为你的 API Key"
export EASYAI_BASE_URL="https://51easyai.com/api/v1"

curl --no-buffer \
  -X POST "${EASYAI_BASE_URL}/agent/responses" \
  -H "Authorization: Bearer ${EASYAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  --data-binary @- <<'JSON'
{
  "input": "请用三点介绍 EasyAI。",
  "model": "替换为模型名称",
  "stream": true,
  "requestId": "req_agent_demo_001"
}
JSON

curl --no-buffer 会在服务端产生事件时立即打印内容。正常结束时最后一条数据为 data: [DONE]。

调用指定 Agent

{
  "input": "请根据已配置的知识库总结产品安装步骤。",
  "model": "替换为模型名称",
  "stream": true,
  "requestId": "req_agent_demo_002",
  "agentId": "替换为 Agent ID",
  "conversationId": "conversation_demo_001",
  "sessionId": "session_demo_001"
}
  • model 当前仍为必填字段。调用指定 Agent 时,Agent 配置的默认模型可能覆盖请求中的 model。
  • conversationId 用于关联已有会话标识和取消状态;sessionId 用于在多轮调用中保持同一记忆会话。多轮对话请复用这两个值,每次请求则使用新的 requestId。如需精确保留完整对话内容,仍应在 input 中传入所需历史消息。
  • 个人 Agent 使用自身已配置的技能;请求中的 skill_options 不会替换个人 Agent 的技能配置。

使用临时技能

未指定 agentId 时,可以通过 skill_options 为本次调用增加系统技能、个人技能或临时技能:

{
  "input": "请检查这段发布说明是否清晰,并给出修改稿。",
  "model": "替换为模型名称",
  "stream": true,
  "requestId": "req_agent_demo_003",
  "skill_options": {
    "system_skill_ids": ["system_skill_id_1"],
    "personal_skill_ids": ["personal_skill_id_1"],
    "ephemeral_skill": {
      "name": "发布说明审校",
      "description": "检查发布说明的完整性和可读性",
      "instructions": "先指出问题,再给出一版可直接发布的中文修改稿。",
      "references": [
        {
          "name": "写作要求",
          "content": "避免内部术语,明确说明用户可以获得什么。"
        }
      ],
      "assets": [
        {
          "name": "产品手册",
          "description": "发布说明可参考的产品资料",
          "url": "https://cdn.example.com/product-guide.pdf",
          "file_type": "application/pdf"
        }
      ]
    }
  }
}

多模态输入

建议先调用 20. 文件上传 获取可访问的 HTTPS URL,再放入 input[].content。不要直接把二进制文件附加到 Agent 接口。

{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请总结视频内容,并对照图片和报告指出差异。"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.example.com/reference.jpg",
            "detail": "auto"
          }
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://cdn.example.com/demo.mp4"
          }
        },
        {
          "type": "input_audio",
          "input_audio": {
            "url": "https://cdn.example.com/interview.mp3",
            "format": "mp3"
          }
        },
        {
          "type": "file_url",
          "file_url": {
            "url": "https://cdn.example.com/report.pdf",
            "file_name": "report.pdf"
          }
        }
      ]
    }
  ],
  "model": "替换为支持所需媒体类型的模型名称",
  "stream": true,
  "requestId": "req_agent_demo_004"
}

支持的 content 分片如下:

type字段说明
texttext文本内容,推荐写法
input_texttext兼容的文本写法;服务端会按文本处理
image_urlimage_url.url,可选 detail图片 URL
video_urlvideo_url.url,可选 detail视频 URL
input_audioinput_audio.url 或 input_audio.data,可选 format音频 URL,或 base64 音频内容
audio_urlaudio_url.url音频 URL 的兼容写法
file_urlfile_url.url,可选 file_namePDF、Office 文档等通用文件 URL;模型不支持文件时会按文件链接处理

平台会根据所选模型的图片、视频和音频理解能力处理媒体内容。模型不支持对应媒体类型时,媒体会作为文本链接提供给模型。file_url 主要用于把文件名称和 URL 提供给 Agent;如需解析文件正文,可让 Agent 使用已配置的文档解析工具。

请求参数

参数类型必填说明
inputstring | array是用户输入。可传单个字符串,也可传消息数组。使用 multipart/form-data 时,消息数组需要先转成 JSON 字符串。
modelstring是模型名称或工作流名称。可从模型清单接口获取;指定个人 Agent 时,其默认模型可能覆盖此值。
streamboolean否兼容字段,建议传 true。本接口固定返回 SSE,传 false 不会改为普通 JSON 响应。
requestIdstring否本次请求的唯一标识。服务端可自动生成,但调用方无法提前用自动生成值取消请求,因此建议始终主动传入。
agentIdstring否要调用的 Agent ID。传入后使用该 Agent 的模型、知识库、MCP 工具和技能配置,并校验当前用户的使用权限。
conversationIdstring否已有会话 ID,用于关联会话标识和取消状态;不会自动把完整历史消息追加到 input。
sessionIdstring否记忆会话标识。需要跨请求保持同一 Agent 记忆时复用同一个值。
skill_optionsobject否本次调用使用的技能选项。个人 Agent 会优先使用自身技能配置。

input 为消息数组时,每一项的字段如下:

字段类型必填说明
rolestring是推荐使用 user 或 assistant。system 消息会被忽略,系统指令应配置在 Agent 或技能中。
contentstring | array是文本或上表中的多模态分片数组。

skill_options 的字段如下:

参数类型必填说明
system_skill_idsstring[]否当前用户可使用的公开系统技能 ID 列表。
personal_skill_idsstring[]否当前用户拥有的个人技能 ID 列表。
ephemeral_skillobject否仅本次调用有效的临时技能,不会保存为个人技能。
ephemeral_skill.namestring是临时技能名称。
ephemeral_skill.descriptionstring是临时技能用途说明。
ephemeral_skill.instructionsstring是临时技能执行指令。
ephemeral_skill.referencesarray否文本参考资料,每项包含 name 和 content。
ephemeral_skill.assetsarray否静态资源,每项包含 name、description、url 和 file_type。

multipart/form-data 请求

表单方式适合已有 FormData 调用链,但该接口不直接接收二进制附件。input 和 skill_options 等对象或数组必须先序列化为 JSON 字符串;文件仍需先上传,再传 URL。

curl --no-buffer \
  -X POST "${EASYAI_BASE_URL}/agent/responses" \
  -H "Authorization: Bearer ${EASYAI_API_KEY}" \
  -H "Accept: text/event-stream" \
  -F 'input=[{"role":"user","content":"请总结这段内容"}]' \
  -F 'model=替换为模型名称' \
  -F 'stream=true' \
  -F 'requestId=req_agent_form_001' \
  -F 'skill_options={"personal_skill_ids":["personal_skill_id_1"]}'

使用 curl -F 时不要手动设置 Content-Type,curl 会自动添加包含 boundary 的正确请求头。

SSE 响应格式

响应头为 Content-Type: text/event-stream。每个事件使用以下格式发送:

data: {"type":"raw_model_stream_event","data":{"type":"output_text_delta","delta":"你好"}}

常见事件如下:

外层 type内层类型说明
raw_model_stream_eventdata.type = output_text_delta文本增量,读取 data.delta 并按顺序拼接。
raw_model_stream_eventdata.type = response_done本轮模型响应完成,data.response.output 包含完整输出,data.response.usage 包含用量。
run_item_stream_eventitem.type = tool_call_itemAgent 开始调用工具,参数通常位于 item.rawItem.arguments。
run_item_stream_eventitem.type = tool_call_output_item工具调用完成,结果通常位于 item.rawItem.output。
run_item_stream_eventitem.type = message_output_item一条完整助手消息已生成,正文位于 item.rawItem.content。
agent_updated_stream_event-运行中的 Agent 发生切换。没有使用多 Agent 协作时通常不需要处理。
error-请求在流式传输期间失败,读取 message。

文本增量示例:

{
  "type": "raw_model_stream_event",
  "data": {
    "type": "output_text_delta",
    "delta": "你好"
  }
}

工具调用示例:

{
  "type": "run_item_stream_event",
  "name": "tool_called",
  "item": {
    "type": "tool_call_item",
    "rawItem": {
      "id": "call_abc123",
      "callId": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\":\"北京\"}",
      "status": "in_progress"
    }
  }
}

模型响应完成示例:

{
  "type": "raw_model_stream_event",
  "data": {
    "type": "response_done",
    "response": {
      "id": "",
      "output": [
        {
          "type": "message",
          "role": "assistant",
          "status": "completed",
          "content": [
            {
              "type": "output_text",
              "text": "北京今天天气晴朗。"
            }
          ]
        }
      ],
      "usage": {
        "inputTokens": 120,
        "outputTokens": 18,
        "totalTokens": 138
      }
    }
  }
}

流结束时会收到:

data: [DONE]

客户端应忽略暂不认识的事件类型,避免服务端增加新事件后中断已有集成。

完整 JavaScript 调用与解析示例

以下示例适用于 Node.js 18 及以上版本,包含请求、SSE 分帧、文本拼接、错误处理和结束判断:

import { randomUUID } from 'node:crypto';

const apiKey = process.env.EASYAI_API_KEY;
const baseUrl = process.env.EASYAI_BASE_URL || 'https://51easyai.com/api/v1';

if (!apiKey) {
  throw new Error('请先设置 EASYAI_API_KEY');
}

const requestId = `req_${randomUUID()}`;
const response = await fetch(`${baseUrl}/agent/responses`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    Accept: 'text/event-stream',
  },
  body: JSON.stringify({
    input: '请用三点介绍 EasyAI。',
    model: '替换为模型名称',
    stream: true,
    requestId,
    // agentId: '替换为 Agent ID',
    // conversationId: 'conversation_demo_001',
    // sessionId: 'session_demo_001',
  }),
});

if (!response.ok) {
  throw new Error(`请求失败(HTTP ${response.status}):${await response.text()}`);
}
if (!response.body) {
  throw new Error('响应中没有可读取的数据流');
}

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let answer = '';
let finalAnswer = '';
let done = false;

function readOutputText(items) {
  const list = Array.isArray(items) ? items : [items];
  return list
    .flatMap((item) => (Array.isArray(item?.content) ? item.content : []))
    .filter((part) => part?.type === 'output_text' && part.text)
    .map((part) => part.text)
    .join('');
}

while (!done) {
  const chunk = await reader.read();
  buffer += decoder.decode(chunk.value || new Uint8Array(), {
    stream: !chunk.done,
  });

  const blocks = buffer.split(/\r?\n\r?\n/);
  buffer = blocks.pop() || '';

  for (const block of blocks) {
    const data = block
      .split(/\r?\n/)
      .filter((line) => line.startsWith('data:'))
      .map((line) => line.slice(5).trimStart())
      .join('\n');

    if (!data) continue;
    if (data === '[DONE]') {
      done = true;
      break;
    }

    const event = JSON.parse(data);
    if (
      event.type === 'raw_model_stream_event' &&
      event.data?.type === 'output_text_delta'
    ) {
      answer += event.data.delta;
      process.stdout.write(event.data.delta);
    } else if (
      event.type === 'run_item_stream_event' &&
      event.item?.type === 'message_output_item'
    ) {
      finalAnswer = readOutputText(event.item.rawItem);
    } else if (
      event.type === 'raw_model_stream_event' &&
      event.data?.type === 'response_done'
    ) {
      finalAnswer = readOutputText(event.data.response?.output);
    } else if (event.type === 'error') {
      throw new Error(event.message || 'Agent 调用失败');
    }
  }

  if (chunk.done) break;
}

const completeAnswer = answer || finalAnswer;
if (!answer && completeAnswer) {
  process.stdout.write(completeAnswer);
}
console.log(`\n\n请求 ID:${requestId}`);
console.log(`完整回答:${completeAnswer}`);

8. 取消 Agent 响应

使用发起 Agent 请求时传入的 requestId 取消仍在运行的请求。

项目值
方法POST
路径/v1/agent/responses/cancel/:requestId
完整地址https://51easyai.com/api/v1/agent/responses/cancel/:requestId
认证Authorization: Bearer {API_KEY}
curl -X POST \
  "${EASYAI_BASE_URL}/agent/responses/cancel/req_agent_demo_001" \
  -H "Authorization: Bearer ${EASYAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"conversation_demo_001"}'

参数说明

  • 路径参数 requestId(string,必填):要取消的请求 ID,必须与发起 /v1/agent/responses 请求时传入的值一致。
  • 请求体 conversationId(string,可选):如该请求关联了会话,传入同一个会话 ID,以便同步标记会话消息状态。

成功响应示例:

{
  "success": true,
  "requestId": "req_agent_demo_001",
  "cancelled": true,
  "marked": true
}

9. 视频生成

接口说明

生成视频内容,支持文生视频、图生视频、视频参考、多模态编辑(O1/Omni 模式)等能力。

方法 POST

路径 /v1/video/generations

请求示例

示例一:文生视频

{
  "model": "video_generation_workflow",
  "content": [
    {
      "type": "text",
      "text": "A beautiful sunset over the ocean"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "audio": false
}

示例二:图生视频(首帧/参考图)

{
  "model": "video_generation_workflow",
  "content": [
    {
      "type": "text",
      "text": "海浪轻轻拍打沙滩"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first_frame.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/style_ref.jpg" },
      "role": "reference"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}

示例三:视频编辑(视频参考、多模态)

{
  "model": "omni_video_workflow",
  "content": [
    {
      "type": "text",
      "text": "将视频中的天空替换成星空"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/source_video.mp4",
        "refer_type": "base",
        "keep_original_sound": "yes"
      },
      "role": "video_base"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/character_ref.jpg" },
      "role": "reference"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}

示例四:主体参考(O1 element 模式)

{
  "model": "omni_video_workflow",
  "content": [
    {
      "type": "text",
      "text": "让角色挥手打招呼"
    },
    {
      "type": "element",
      "element": {
        "system_element_id": "element_123"
      }
    }
  ]
}

请求参数说明

  • model (string, 必填): 工作流名称
  • content (array, 必填): 内容数组,每项为多模态内容块

content 项结构

字段类型说明
typestring内容类型: "text" | "image_url" | "audio_url" | "video_url" | "element"
textstring文本内容(type=text 时必填)
image_urlobject图片对象 { url: string }(type=image_url 时必填)
audio_urlobject音频对象 { url: string }(type=audio_url 时必填)
video_urlobject视频对象(type=video_url 时必填)
elementobject主体参考(type=element 时必填,O1/Omni 模式)
rolestring角色/用途标识
namestring占位符名称(如 <<<image_1>>>)
shot_indexnumber多镜头模式下的镜头索引
durationnumber多镜头模式下该分镜时长(秒)

role 取值说明(图片/视频参考)

role说明
first_frame首帧图片,用于图生视频的起始画面
last_frame尾帧图片,指定生成视频的结束画面
digital_human_frame数字人参考帧
reference风格/角色参考图
video_feature视频特征参考(风格、动作等)
video_base待编辑视频(视频编辑模式下作为源视频)
shot_prompt分镜头提示词(多镜头模式)
element主体参考(O1 新增)

video_url 扩展字段

字段类型说明
urlstring视频 URL,支持 HTTP/HTTPS 或 base64 data URI
refer_typestring参考类型: "feature" 特征参考 | "base" 待编辑视频
keep_original_soundstring是否保留原声: "yes" | "no"

element 主体参考结构

字段类型说明
system_element_idstring系统主体库中的主体 ID
inline_elementobject内联主体详情,包含 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, 可选): 时长(秒),默认 5
  • audio (boolean, 可选): 是否生成/保留音频
  • framespersecond (number, 可选): 帧率
  • watermark (boolean, 可选): 是否添加水印,默认 false
  • seed (number, 可选): 随机种子,默认 -1
  • camerafixed (boolean, 可选): 是否固定镜头,默认 false
  • ratio / 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 等待成功。

{
  "model": "<当前账号支持样片的模型调用名>",
  "content": [{ "type": "text", "text": "一只小猫在窗边伸懒腰,镜头缓慢推进" }],
  "draft": true,
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5
}

该示例为 Seedance 规格;H3 应使用其声明的样片规格。draft: false 或省略该字段仍为直接生成,普通低分辨率视频、上传视频和视频 URL 不会因此获得样片资格。

协议样片请求规格正片目标值新提交有效期
火山 Seedance V1480p1080p2026-10-28 10:00(北京时间)及之后创建的样片 14 天,此前为 7 天
RunningHub Seedance V1480p1080p保持该适配器的 7 天期限,以服务端截止时间为准
MiniMax-H3 V2720p1440p按能力声明;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 或供应商任务号代替结果引用,资格应再向服务端查询。

以下为样片任务成功响应的关键字段示例(省略其他字段,展示字段会受实例策略影响):

{
  "taskId": "0123456789abcdef01234567",
  "status": "succeeded",
  "result": {
    "videos": [{
      "type": "video",
      "url": "https://example.com/draft.mp4",
      "videoGeneration": {
        "schemaVersion": 1,
        "stage": "draft",
        "resultId": "0123456789abcdef01234567:0",
        "resolution": "480p",
        "finalResolutions": ["1080p"],
        "finalizeExpiresAt": 1794182400000
      }
    }]
  }
}

第二步:查询资格与已有正片

方法与路径:GET /v1/video/results/:resultId/finalization,将上一步的结果引用作为一个路径参数进行 URL 编码。

{
  "sourceResultId": "0123456789abcdef01234567:0",
  "eligible": true,
  "targetResolutions": ["1080p"],
  "expiresAt": 1794182400000,
  "duration": 5,
  "audio": false
}
字段含义与处理
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。

{
  "params": {
    "operation": "video.finalize",
    "sourceResultId": "0123456789abcdef01234567:0",
    "targetResolution": "1080p"
  }
}

服务端从原样片还原模型、账号、实际时长及计费参数,并按目标规格估价。样片和正片分别生成、分别计费,不能承诺两步合计一定比直接生成便宜。估价不会提交正片;实际受理时仍检查余额、配额和当前资格。

第四步:提交正片并查询结果

方法与路径:POST /v1/video/finalizations。

{
  "sourceResultId": "0123456789abcdef01234567:0",
  "targetResolution": "1080p",
  "outputFormat": "mp4",
  "watermark": false,
  "returnLastFrame": false,
  "idempotencyKey": "final-cat-20261102-001"
}
参数类型说明
sourceResultIdstring,必填服务端返回的具体样片结果引用
targetResolutionstring,必填1080p 或 1440p,还须符合来源资格
outputFormatstring,可选火山支持 mp4 / mov,默认 mp4;H3 及当前 RunningHub 适配仅使用 mp4
watermarkboolean,可选默认 false
returnLastFrameboolean,可选默认 false;当前 H3 V2 不支持设为 true
idempotencyKeystring,必填8–128 位字母、数字、下划线或连字符;同一次确认及网络重试保留同一值
serviceTierstring,可选火山 default / flex;Seedance 2.5 不支持 flex
executionExpiresAfterinteger,可选火山任务执行期限,3600–259200 秒;不是样片可引用期限
priorityinteger,可选火山任务优先级 0–9
callbackUrlstring,可选状态回调地址;火山和 H3 可设置
safetyIdentifierstring,可选火山安全标识

此接口还接受通用 options,但始终异步返回,例如:

{
  "status": "submitted",
  "task_id": "fedcba987654321001234567",
  "created": 1793577600000
}

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": [{ "type": "draft_task", "draft_task": { "id": "0123456789abcdef01234567" } }],
  "resolution": "1080p",
  "draft": false,
  "output_format": "mov",
  "watermark": false,
  "return_last_frame": true,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "priority": 0,
  "callback_url": "https://example.com/video-callback",
  "safety_identifier": "customer-123"
}
火山参数平台专用成片接口字段规则
model来源中已保存须与原样片调用名或实际模型相同
content[].draft_task.idsourceResultId须为当前账号的已完成样片,不能混入其他内容块
resolutiontargetResolution按来源目标提交;Seedance 1080p,H3 扩展为 1440p(供应商 2K)
output_formatoutputFormat默认 mp4,火山还支持 mov
return_last_framereturnLastFrameboolean,默认 false
service_tierserviceTier默认 default;模型不支持的档位拒绝
execution_expires_afterexecutionExpiresAfterinteger,3600–259200,火山默认 172800 秒
prioritypriorityinteger,0–9,火山默认 0
callback_urlcallbackUrlstring
safety_identifiersafetyIdentifierstring

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 targetResolutionJSON resolution
请求去重专用成片接口用 JSON idempotencyKey,火山参数入口用 Header Idempotency-KeyHTTP 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

请求示例

curl -X POST "https://51easyai.com/api/v1/video/upscale" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "x-async: true" \
  -d '{
    "model": "easy-proteus-standard-4",
    "video_url": "https://example.com/source.mp4",
    "target_resolution": "4k",
    "preserve_audio": true
  }'

也可以用明确的像素尺寸替代 target_resolution:

{
  "video_url": "https://example.com/source.mp4",
  "output_width": 1920,
  "output_height": 1080,
  "preserve_audio": true
}

请求参数说明

字段类型必填说明
video_urlstring是服务端可访问的源视频 HTTP/HTTPS URL
modelstring否视频增强模型,默认 easy-proteus-standard-4
enhancement_modelstring否兼容字段;建议新调用统一使用 model
target_resolutionstring否目标分辨率,常用值为 720p、1080p、2k、4k;默认 1080p
output_resolutionstring否target_resolution 的兼容字段
output_widthnumber | string否自定义输出宽度;必须与 output_height 一起传入
output_heightnumber | string否自定义输出高度;必须与 output_width 一起传入
output_frame_ratenumber | string否目标帧率,是否支持取决于所选模型
frame_interpolation_modelstring否补帧模型,是否支持取决于所选模型
slow_motion_ratenumber | string否慢动作倍率,是否支持取决于所选模型
preserve_audioboolean否是否保留原视频音频,默认 true

异步提交响应示例

{
  "task_id": "task_video_upscale_123",
  "status": "submitted",
  "message": "任务已提交,请稍后查看结果",
  "created": 1790668800000,
  "query_url": "https://51easyai.com/api/v1/ai/result/task_video_upscale_123"
}

建议忽略响应中的兼容字段 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": "A relaxing jazz melody",
  "model": "music_generation_workflow",
  "makeInstrumental": false,
  "customMode": false,
  "title": "Relaxing Jazz",
  "tags": "jazz",
  "negativeTags": "",
  "vocalGender": "f",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.5,
  "audioWeight": 0.65
}

请求参数说明

  • 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

请求示例

{
  "model": "MiniMax-Speech-2.8-HD",
  "text": "你好,欢迎使用 EasyAI 语音合成。",
  "voice_id": "male-qn-qingse",
  "speed": 1.0,
  "vol": 1.0,
  "pitch": 0,
  "emotion": "happy"
}

示例使用 MiniMax 模型与其预置音色;请以当前部署 GET /v1/models/list?type=text_to_speech 返回的模型别名和音色为准。

请求参数说明

  • model (string, 必填): 当前账号可用的语音合成模型别名,优先使用模型列表中的 alias
  • text (string): 要朗读的文本,普通合成请求应填写
  • voice_id (string): 音色 ID;预置音色取自所选模型的 capabilities.text_to_speech.voices[].id,克隆音色取自本人克隆记录的 voice_id
  • cloned_voice_id (string, 可选): 本人克隆记录的 id,用于明确指定克隆音色和原平台绑定
  • speed、vol、pitch (number, 可选): 语速、音量、音调;范围取决于模型,原音调使用 pitch: 0
  • emotion (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": "digital_human_workflow",
  "video_id": "video_123",
  "interaction_optimise": 1
}

请求参数说明

  • model (string, 必填): 工作流名称
  • video_id (string, 必填): 视频ID
  • interaction_optimise (number, 可选): 是否开启针对直播的优化,1:开启 0:关闭,默认为开启

14. 生成数字人视频

接口说明

生成数字人视频

方法 POST

路径 /v1/digital-human/generations

请求示例

{
  "model": "digital_human_workflow",
  "resource_id": "resource_123",
  "audio_url": "https://example.com/audio.mp3",
  "image_url": "https://example.com/image.jpg",
  "video_url": "https://example.com/video.mp4",
  "templ_start_strategy": "start_from_given_seconds",
  "templ_start_seconds": 0,
  "separate_vocal": true,
  "open_scenedet": false,
  "align_audio": true,
  "align_audio_reverse": false
}

请求参数说明

  • model (string, 必填): 工作流名称
  • resource_id (string, 必填): 数字人资源ID
  • audio_url (string, 必填): 音频路径
  • image_url (string, 可选): 图片URL
  • video_url (string, 可选): 视频URL
  • templ_start_strategy (string, 可选): 指定模板开始策略,可选值: "start_from_given_seconds"
  • templ_start_seconds (number, 可选): 模版视频开始时间(仅对Lite模式生效),默认 0
  • separate_vocal (boolean, 可选): 是否打开人声分离,开启后会抑制音频背景杂音
  • open_scenedet (boolean, 可选): 是否打开场景切分与说话人识别(仅对Basic模式生效)
  • align_audio (boolean, 可选): 是否开启视频循环(仅对Lite模式生效),默认 true
  • align_audio_reverse (boolean, 可选): 是否开启倒放循环(仅对Lite模式生效,需要同时开启align_audio),默认 false

15. 异步生成任务(已弃用)

接口说明

异步提交和返回任务,提交任务返回任务ID

方法 POST

路径 /v1/ai/generations

请求示例

{
  "params": {
    "prompt": "a beautiful landscape",
    "width": 1024,
    "height": 1024,
    "seed": 12345
  },
  "options": {
    "result_retrieval": "websocket"
  }
}

请求参数说明

  • params (object, 必填): ComfyUI属性参数对象
    • prompt (string, 可选): 提示词
    • width (number, 可选): 宽度
    • height (number, 可选): 高度
    • seed (number, 可选): 随机种子
    • 其他ComfyUI相关参数...
  • options (object, 可选): 选项
    • result_retrieval (string, 可选): 结果获取方式,默认 "websocket"

16. 查询异步任务

接口说明

查询图片、图片编辑、图片矢量化、视频生成、视频超分、音乐等异步任务的统一状态和结果。

方法 GET

路径 /v1/tasks/:taskId

请求示例

curl -X GET "https://51easyai.com/api/v1/tasks/task_123456" \
  -H "Authorization: Bearer {token}"

响应示例

{
  "id": "task_123456",
  "taskId": "task_123456",
  "status": "succeeded",
  "result": {
    "videos": [
      {
        "type": "video",
        "url": "https://example.com/output/upscaled.mp4"
      }
    ]
  },
  "cancellable": false,
  "submitted": true,
  "progress": 100,
  "started_at": 1790668800000,
  "finished_at": 1790668860000
}
  • 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 提供稳定的错误标识。例如:

{
  "id": "task_123456",
  "taskId": "task_123456",
  "status": "failed",
  "task_status": "failed",
  "execution_phase": "finished",
  "error_code": "upstream_completion_unknown",
  "errorMessage": "图片生成失败:未能取得完整图片结果,本次处理已结束,不收取本次生成费用。原任务记录已保留供追查。",
  "billing_status": "released",
  "charged_amount": 0,
  "billing_message": "未取得完整图片,本次不收费,预占额度已释放。",
  "retryable": false,
  "upstreamCompletionUnknown": true,
  "upstream_task_id": "original_gateway_task",
  "reconciliation": {
    "state": "needs_review",
    "reason": "upstream_task_ended",
    "deadlineAt": 1793696400000,
    "upstream_task_id": "original_gateway_task"
  }
}
  • 收到终态 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_typestring按任务类型过滤
statusstringqueued、running、succeeded、failed、cancelled
modelstring按模型名称或别名过滤
created_afterstring | number起始时间,可传 ISO 时间、秒级或毫秒级时间戳
created_beforestring | number结束时间,可传 ISO 时间、秒级或毫秒级时间戳
pageinteger页码,默认 1
page_sizeinteger每页数量,默认 20,最大 100

返回结构为 { items, total, page, page_size }。


17. 取消或删除任务

接口说明

取消尚可撤回的异步任务,或删除已经结束的任务记录。

取消方法 POST

取消路径 /v1/tasks/:taskId/cancel

请求示例

curl -X POST "https://51easyai.com/api/v1/tasks/task_123456/cancel" \
  -H "Authorization: Bearer {token}"

响应示例

{
  "taskId": "task_123456",
  "cancelled": true,
  "cancellable": false,
  "submitted": false,
  "message": "任务已取消"
}

仅仍在本地排队且尚未提交上游的任务保证可取消。若返回 cancelled: false,客户端应根据 message 继续轮询或提示用户。

删除方法 DELETE

删除路径 /v1/tasks/:taskId

curl -X DELETE "https://51easyai.com/api/v1/tasks/task_123456" \
  -H "Authorization: Bearer {token}"

运行中或已取消的任务不能删除;排队中的任务会转为取消操作,已成功或失败的任务记录可删除。

旧路径 GET /v1/ai/cancel/:taskId 仍保留用于兼容历史客户端。


18. 获取模型清单(OpenAI 兼容)

接口说明

返回当前可用的模型列表,遵循 OpenAI 官方的 models 接口规范,便于对接 OpenAI SDK 或第三方兼容客户端。

方法 GET

路径 /v1/models

请求示例

curl -X GET "https://51easyai.com/api/v1/models" \
  -H "Authorization: Bearer {token}"

响应示例

{
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "permission": [
        {
          "id": "modelperm-gpt-4-1626777600",
          "object": "model_permission",
          "created": 1626777600,
          "allow_create_engine": false,
          "allow_sampling": true,
          "allow_logprobs": true,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "gpt-4",
      "parent": null
    }
  ],
  "success": true
}

响应字段说明

  • data (array): 模型列表,每项为 OpenAI 格式的模型对象
  • success (boolean): 是否成功

响应数据模型(TypeScript)

/** GET /v1/models 响应 */
interface ModelsResponse {
  data: OpenAIModelItem[];
  success: boolean;
}

interface OpenAIModelItem {
  id: string;
  object: 'model';
  created: number;
  owned_by: string;
  permission: OpenAIModelPermission[];
  root: string;
  parent: null;
}

interface OpenAIModelPermission {
  id: string;
  object: 'model_permission';
  created: number;
  allow_create_engine: boolean;
  allow_sampling: boolean;
  allow_logprobs: boolean;
  allow_search_indices: boolean;
  allow_view: boolean;
  allow_fine_tuning: boolean;
  organization: string;
  group: null;
  is_blocking: boolean;
}

19. 按能力类型查询模型列表

接口说明

根据模型能力类型查询可用模型,返回 PlatformModel 格式的完整模型信息。不传 type 或传 all 时返回所有模型。内部使用建议优先使用本接口,可精确按能力筛选、获取更丰富的模型元数据。

方法 GET

路径 /v1/models/list

请求示例

# 获取所有模型
curl -X GET "https://51easyai.com/api/v1/models/list" \
  -H "Authorization: Bearer {token}"

# 按能力类型筛选(例如:仅文本生成模型)
curl -X GET "https://51easyai.com/api/v1/models/list?type=text_generate" \
  -H "Authorization: Bearer {token}"

请求参数说明

  • 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": [
    {
      "name": "gpt-4",
      "alias": "gpt-4",
      "description": "...",
      "types": ["text_generate", "tools_call"],
      "provider": "openai"
    }
  ],
  "count": 1
}

响应字段说明

  • modelList (array): 模型列表,每项为 PlatformModel 结构,含 name、alias、types、provider 等字段
  • count (number): 模型数量

响应数据模型(TypeScript)

/** GET /v1/models/list 响应 */
interface ModelsListResponse {
  modelList: PlatformModelWithProvider[];
  count: number;
}

/** 模型能力类型 */
type PlatformModelType =
  | 'text_generate'
  | 'text_embedding'
  | 'text_rerank'
  | 'image_generate'
  | 'image_edit'
  | 'image_vectorize'
  | 'image_analysis'
  | 'video_generate'
  | 'image_to_video'
  | 'video_edit'
  | 'video_enhance'
  | 'omni_video'
  | 'tools_call'
  | 'audio_generate'
  | 'voice_clone'
  | 'text_to_model'
  | 'image_to_model'
  | 'multiview_to_model'
  | 'mesh_edit'
  | 'digital_human_generate'
  | 'text_to_speech'
  | 'speech_to_text'
  | 'video_understanding'
  | 'audio_understanding'
  | 'omni';

/** 平台模型(含 provider,接口返回格式) */
interface PlatformModelWithProvider {
  name: string;
  alias?: string;
  description?: string;
  types: PlatformModelType[];
  icon_path?: string;
  billing_mode?: Record<string, unknown>;
  model_limits?: Record<string, unknown>;
  model_weight?: number;
  capabilities?: Partial<Record<PlatformModelType, unknown>>;
  reference_model?: string;
  permission?: { min_permission_level: number };
  enabled?: boolean;
  disabled_reason?: string;
  disabled_until?: string;
  provider?: string; // 平台提供方,接口层追加
}

20. 文件上传

接口说明

开放接口上传文件,上传后为临时文件,24 小时后自动删除。支持 multipart/form-data 二进制上传或 base64 方式。上传成功后返回可访问的 URL,可在图片编辑、视频生成、Agent 等接口中作为 image_url、url 等参数使用。

方法 POST

路径 /v1/files/upload

请求示例

方式一:multipart/form-data 二进制上传

curl -X POST "https://51easyai.com/api/v1/files/upload" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/image.jpg" \
  -F "fileName=my-image.jpg"

方式二:base64 图片上传(FormData)

curl -X POST "https://51easyai.com/api/v1/files/upload" \
  -H "Authorization: Bearer {token}" \
  -F "file=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" \
  -F "fileName=custom-name.png"

请求参数说明

  • file (File | string, 必填): 文件内容
    • 二进制:multipart/form-data 中 file 字段,直接上传文件流
    • Base64:file 字段传入 base64 字符串,支持 data:image/xxx;base64, 前缀(仅图片)
  • fileName (string, 可选): 保存时的文件名,不传时使用原文件名或自动生成

限制说明

  • 单文件大小:100MB
  • 支持类型:图片(image/)、音频(audio/)、视频(video/*)及通用文件
  • 存储策略:临时存储,24 小时后自动删除

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true,
    "url": "https://51easyai.com/api/files/xxx/xxx/image.jpg"
  }
}

响应字段说明

  • 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 为同步接口,不使用异步请求头。

异步模式示例

curl -X POST /v1/images/generations \
  -H "Authorization: Bearer {token}" \
  -H "x-async: true" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat",
    "model": "text2img"
  }'

异步回调模式

除了通过查询接口获取任务结果外,系统还支持通过HTTP回调的方式主动推送任务结果到指定URL。

配置方式

在管理后台的系统配置 -> 运营配置 -> 任务调度 -> 任务回调地址中配置回调URL。

配置路径: 管理后台 → 系统配置 → 运营配置 → 任务调度 → 任务回调地址

配置说明:

  • 配置后,系统会在任务状态更新时(包括进行中、成功、失败等状态)向该URL发送POST请求
  • 回调URL必须是可公网访问的HTTP/HTTPS地址
  • 建议配置HTTPS地址以保证数据安全

回调处理机制

  • 任务状态的消息队列消费者会自动将任务结果推送到配置的回调URL
  • 系统使用POST请求发送回调数据,Content-Type为 application/json
  • 系统会自动重试3次,如果3次都失败则放弃回调
  • 回调数据即为任务状态数据,格式见下方说明

回调数据格式

回调请求的请求体为 IGenerateStatus 格式的JSON数据,结构如下:

{
  "queue_status": {
    "task_id": "task_123456",
    "request_id": "req_789",
    "server": "server_001",
    "status": "success",
    "queue": 0,
    "data": {
      "task_id": "task_123456",
      "status": "success",
      "output": [
        "https://example.com/output/image1.jpg",
        "https://example.com/output/image2.jpg"
      ],
      "output_content": [
        {
          "type": "image",
          "url": "https://example.com/output/image1.jpg",
          "mediaSize": {
            "type": "image",
            "width": 1024,
            "height": 1024,
            "status": 1
          }
        }
      ],
      "type": "image",
      "started_at": 1699123456789,
      "finished_at": 1699123466789,
      "billings": []
    },
    "output_content": [
      {
        "type": "image",
        "url": "https://example.com/output/image1.jpg"
      }
    ],
    "message": "任务执行成功",
    "time_remained": 0,
    "progress": 100
  },
  "node_status": {
    "executeId": "exec_123",
    "nodeId": "node_456",
    "customWorkflowId": "workflow_789",
    "status": "success",
    "message": "节点执行成功",
    "result": {},
    "nodeData": {
      "params": {}
    }
  },
  "usage": {
    "total_tokens": 1000,
    "input_tokens": 500,
    "output_tokens": 500
  },
  "callback_url": "https://your-callback-url.com/api/callback",
  "user": {
    "_id": "user_123",
    "sso_id": "sso_456"
  },
  "generate_info": {
    "input": {
      "prompt": "a cat",
      "model": "text2img"
    },
    "workflow": {
      "_id": "workflow_789"
    }
  },
  "billings": [
    {
      "billing_type": "image",
      "billing_model": {},
      "generateParams": {},
      "platform": {
        "name": "平台名称",
        "id": "platform_id",
        "code": "platform_code"
      },
      "billing_params": {},
      "result": {
        "token": 100
      }
    }
  ]
}

回调数据字段说明

顶层字段

  • queue_status (object, 可选): 队列状态信息,包含任务执行状态和结果
  • node_status (object, 可选): 工作流节点执行状态(仅在工作流任务中存在)
  • usage (object, 可选): 使用量统计(OPENAI兼容的计费数据)
  • callback_url (string, 可选): 回调地址
  • user (object, 可选): 用户信息
    • _id (string): 业务系统的用户ID
    • sso_id (string, 可选): 主应用的用户ID
  • generate_info (object, 可选): 生成相关信息
    • input (object): 扩展输入参数
    • workflow (object): 工作流信息
      • _id (string): 工作流ID
  • billings (array, 可选): 账单信息数组

queue_status 字段说明

  • task_id (string): 任务ID
  • request_id (string, 可选): 请求ID
  • server (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): 任务ID
  • request_id (string, 可选): 请求ID
  • status (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, 可选): 输出URL
  • b64_json (string, 可选): Base64编码的JSON数据
  • content (string, 可选): 生成的内容
  • role (string, 可选): 角色
  • filename (string, 可选): 文件名
  • mediaSize (object, 可选): 媒体尺寸
  • uploaded (boolean, 可选): 是否已上传
  • has_audio (boolean, 可选): 是否有音频

回调示例

成功状态回调示例

{
  "queue_status": {
    "task_id": "task_123456",
    "status": "success",
    "progress": 100,
    "data": {
      "task_id": "task_123456",
      "status": "success",
      "output": ["https://example.com/output/image.jpg"],
      "output_content": [
        {
          "type": "image",
          "url": "https://example.com/output/image.jpg",
          "mediaSize": {
            "type": "image",
            "width": 1024,
            "height": 1024,
            "status": 1
          }
        }
      ],
      "type": "image",
      "started_at": 1699123456789,
      "finished_at": 1699123466789
    }
  },
  "user": {
    "_id": "user_123"
  }
}

失败状态回调示例

{
  "queue_status": {
    "task_id": "task_123456",
    "status": "failed",
    "message": "任务执行失败",
    "original_error_message": "Internal server error",
    "data": {
      "task_id": "task_123456",
      "status": "failed",
      "message": "任务执行失败",
      "original_error_message": "Internal server error"
    }
  },
  "user": {
    "_id": "user_123"
  }
}

进行中状态回调示例

{
  "queue_status": {
    "task_id": "task_123456",
    "status": "process",
    "queue": 2,
    "progress": 50,
    "time_remained": 30,
    "message": "任务处理中"
  },
  "user": {
    "_id": "user_123"
  }
}

回调接口实现建议

  1. 接口要求:
    • 接收POST请求
    • Content-Type: application/json
    • 返回HTTP 200状态码表示接收成功
    • 建议在3秒内响应,避免超时
  2. 数据验证:
    • 验证任务ID的有效性
    • 验证用户ID的权限
    • 保存任务结果到数据库
  3. 幂等性处理:
    • 系统可能会重复发送回调(虽然会自动重试),建议根据 task_id 做幂等性处理
    • 可以只处理 status 为 "success" 或 "failed" 的最终状态
  4. 错误处理:
    • 如果回调接口返回非200状态码,系统会重试3次
    • 建议记录回调日志,便于排查问题

注意事项

  1. 所有接口都需要在请求头中携带有效的认证token
  2. 文件上传接口支持multipart/form-data格式
  3. 图片编辑接口支持文件上传和URL两种方式
  4. 异步任务可以通过查询接口获取结果,也可以配置回调URL接收推送
  5. 部分接口支持流式返回(如聊天接口)
  6. 回调URL配置后,系统会在任务状态更新时自动推送结果,无需轮询查询

工作流上传

建议使用ComfyUI-EasyAI插件进行工作流上传