OpenAPI接口文档

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

EasyAI平台支持开放API，并且兼容OpenAI格式的绘图接口规范，轻松接入！

API的应用场景

二开形成新的应用、小程序或者APP，提供接口
接入硬件产品如AI相机、AI试装
接入企业内部其他生产系统

基础信息

基础路径: /v1
认证方式: 需要在请求头中携带 Authorization: Bearer {token}
异步模式: 支持通过请求头 x-async: true 或 async: true 启用异步模式（立即返回任务ID，不等待任务完成）

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, 可选): 图片大小，例如 "1024x1024"
n (number, 可选): 生成图片数量
aspect_ratio (string, 可选): 图片比例（FLUX图像比例）
resolution (string, 可选): 分辨率，可选值: "1K" | "2K" | "4K" | "8K"

2. 图片编辑

接口说明

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

方法 POST

路径 /v1/images/edits

请求示例

方式一：使用文件上传（multipart/form-data）

curl -X POST /v1/images/edits \
  -H "Authorization: Bearer {token}" \
  -F "image[]=@/path/to/image.jpg" \
  -F "mask=@/path/to/mask.png" \
  -F "prompt=make it more colorful" \
  -F "model=image_edit_workflow" \
  -F "size=1024x1024"

方式二：使用URL（application/json）

{
  "image": "https://example.com/image.jpg",
  "mask": "https://example.com/mask.png",
  "prompt": "make it more colorful",
  "model": "image_edit_workflow",
  "size": "1024x1024"
}

请求参数说明

image (File | string | string, 必填): 图片文件（支持多文件上传）或图片URL
mask (File | string, 可选): 遮罩文件或遮罩URL
prompt (string, 必填): 编辑提示词
model (string, 必填): 工作流名称
size (string, 可选): 图片大小
aspect_ratio (string, 可选): 图片比例
resolution (string, 可选): 分辨率
seed (number, 可选): 随机种子
n (number, 可选): 生成数量
_metadata (string, 可选): JSON字符串格式的元数据

文件上传字段

files 或 image[]: 图片文件（最多16个）
mask: 遮罩文件（最多1个）
文件大小限制: 20MB
支持格式: jpg, jpeg, png, webp

3. 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): 消息内容
stream (boolean, 可选): 是否流式返回，默认 true
conversationId (string, 可选): 会话ID
sessionId (string, 可选): 会话ID

4. 视频生成

接口说明

生成视频内容

方法 POST

路径 /v1/video/generations

请求示例

{
  "model": "video_generation_workflow",
  "content": [
    {
      "type": "text",
      "text": "A beautiful sunset over the ocean"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      },
      "role": "first_frame"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "audio": false,
  "framespersecond": 24,
  "watermark": false,
  "seed": -1
}

请求参数说明

model (string, 必填): 工作流名称
content (array, 必填): 内容数组
- type (string): 内容类型，可选值: "text" | "image_url" | "audio_url" | "video_url"
- text (string, 可选): 文本内容
- image_url (object, 可选): 图片URL对象
- role (string, 可选): 角色，可选值: "first_frame" | "last_frame" | "digital_human_frame" | "reference"
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

5. 音乐生成

接口说明

同步提交和返回结果

方法 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，保留两位小数

6. 语音合成

接口说明

同步提交和返回结果

方法 POST

路径 /v1/speech/generations

请求示例

{
  "model": "tts_workflow",
  "text": "Hello, this is a test speech synthesis",
  "text_file_id": "file_123",
  "voice_id": "voice_001",
  "speed": 1.0,
  "vol": 1.0,
  "pitch": 1.0,
  "emotion": "happy"
}

请求参数说明

model (string, 必填): 模型名称
text (string, 必填): 要合成的文本
text_file_id (string, 可选): 文本文件ID
voice_id (string, 必填): 语音ID
speed (number, 可选): 语速
vol (number, 可选): 音量
pitch (number, 可选): 音调
emotion (string, 可选): 情感

7. 创建数字人

接口说明

创建数字人形象

方法 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:关闭，默认为开启

8. 生成数字人视频

接口说明

生成数字人视频

方法 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

9. 异步生成任务弃用，可以用/v1/images/generations添加xasyc请求头的方式替代

接口说明

异步提交和返回任务，提交任务返回任务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"

10. 查询异步任务结果

接口说明

查询异步任务的结果

方法 GET

路径 /v1/ai/result/:taskId

请求示例

GET /v1/ai/result/task_123456

路径参数说明

taskId (string, 必填): 任务ID

11. 取消任务

接口说明

取消正在执行的任务，基于API接口的任务不支持取消

方法 GET

路径 /v1/ai/cancel/:taskId

请求示例

GET /v1/ai/cancel/task_123456

路径参数说明

taskId (string, 必填): 任务ID

异步模式说明

所有支持异步的接口（图片生成、图片编辑、视频生成、音乐生成、语音合成、数字人视频生成）都可以通过请求头启用异步模式：

请求头: x-async: true 或 async: true 或 X-Async: true
行为:
- 异步模式（header存在且值为 "true" 或 "1"）: 立即返回任务ID，不等待任务完成
- 同步模式（默认）: 等待任务完成后返回结果

异步模式示例

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

回调接口实现建议

接口要求:
- 接收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插件进行工作流上传

开源项目

行业第一个AIGC开源项目，可供AIGC项目的开发学习。如果你想快速构建自己的落地的商业项目，建议选择更加成熟的商业版或者企业版

推广与合作

下一个十年的造富机遇！面向广大AIGC先驱者，利用自己的掌握的AIGC场景实现能力，实现商用落地变现。

API的应用场景
基础信息
1. AI绘图/视频生成
2. 图片编辑
3. AI对话
4. 视频生成
5. 音乐生成
6. 语音合成
7. 创建数字人
8. 生成数字人视频
9. 异步生成任务弃用，可以用/v1/images/generations添加xasyc请求头的方式替代
10. 查询异步任务结果
11. 取消任务
异步模式说明
异步回调模式
注意事项
工作流上传

Star on GitHub Create Issues