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，不等待任务完成）

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. Agent 流式响应 (responses)

接口说明

Agent 智能体流式响应接口，支持多模态输入（文本、图片），可配置技能选项，返回 SSE 格式的流式数据。

方法 POST

路径 /v1/responses

请求示例

方式一：application/json

{
  "input": "你好，请介绍一下你自己",
  "model": "gpt-4",
  "stream": true,
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "requestId": "req_1234567890",
  "agentId": "agent_1234567890",
  "skill_options": {
    "personal_skill_ids": ["skill_1", "skill_2"],
    "ephemeral_skill": {
      "name": "数据分析助手",
      "description": "帮助用户分析数据",
      "instructions": "你是一个专业的数据分析助手，请帮助用户分析数据。",
      "references": [
        {
          "name": "参考文档1",
          "content": "这是参考文档的内容..."
        }
      ]
    }
  }
}

方式二：input 为消息数组

{
  "input": [
    {
      "role": "user",
      "content": "你好，请介绍一下你自己"
    }
  ],
  "model": "gpt-4",
  "stream": true
}

请求参数说明

input (string | array, 必填): 用户输入
- 字符串: 单条文本内容
- JSON 字符串: 可传入需解析的消息数组字符串
- 数组: 消息数组，每项为 { role: "user" | "assistant" | "system", content: string }
model (string, 必填): 模型名称或工作流名称
stream (boolean, 可选): 是否流式返回，默认 true
images (string, 可选): 图片 URL 数组，支持多模态输入
requestId (string, 可选): 请求 ID，用于追踪和取消请求；不传时由服务端生成
agentId (string, 可选): 智能体 ID，用于 RAG 检索
skill_options (object, 可选): 技能选项
- personal_skill_ids (string, 可选): 选中的个人技能 ID 列表
- ephemeral_skill (object, 可选): 临时技能（仅本次对话有效，不存储）
  - name (string): 技能名称
  - description (string): 技能描述
  - instructions (string): 技能指令
  - references (array, 可选): 临时引用，每项 { name: string, content: string }
  - assets (array, 可选): 临时静态资源，每项 { name, description, url, file_type }

响应说明

响应头: Content-Type: text/event-stream，采用 SSE 流式输出
每行格式: data: <JSON>\n\n
事件内容为 JSON 对象，直至收到 data: [DONE]\n\n 表示结束
错误时推送: data: {"type":"error","message":"...","code":500}\n\n

响应事件类型与格式

Agent 接口会根据运行模式返回不同格式的流式事件：

一、Base Agent 模式（RunStreamEvent）

当未指定 agentId 或未命中 RAG 流程时，事件格式如下。

事件类型	说明
`run_item_stream_event`	运行过程中的输出项事件

run_item_stream_event 下的 item 类型

item.type	说明
`tool_call_item`	工具调用开始
`tool_call_output_item`	工具调用结果（rawItem.type 可为 `function_call_result`）
`message_output_item`	消息输出（rawItem.type 为 `message`，含 `content` 数组）

示例：tool_call_item

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

示例：tool_call_output_item

{
  "type": "run_item_stream_event",
  "item": {
    "type": "tool_call_output_item",
    "rawItem": {
      "type": "function_call_result",
      "callId": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\":\"北京\"}",
      "output": "北京今日晴，25°C",
      "status": "completed"
    }
  }
}

示例：message_output_item（最终文本回复）

{
  "type": "run_item_stream_event",
  "item": {
    "type": "message_output_item",
    "rawItem": {
      "type": "message",
      "content": [
        { "type": "output_text", "text": "北京今天天气晴朗，气温约25°C。" }
      ]
    }
  }
}

二、RAG Agent 模式（ResponseStreamEvent）

当指定 agentId 且命中知识库时，使用 OpenAI Responses API，事件类型兼容 OpenAI 规范，主要包括：

事件 type	说明
`response.created`	响应已创建
`response.in_progress`	响应处理中
`response.output_item.added`	新增输出项（如 message、function_call）
`response.output_item.done`	输出项完成
`response.output_text.delta`	文本流式增量（含 `delta`、`snapshot`）
`response.text.done`	文本输出完成
`response.content_part.added`	内容块新增
`response.content_part.done`	内容块完成
`response.completed`	响应完成
`response.failed`	响应失败
`response.error`	错误事件

示例：response.output_text.delta

{
  "type": "response.output_text.delta",
  "delta": "你好",
  "output_index": 0,
  "output_item_index": 0,
  "content_index": 0
}

示例：response.output_item.added（message）

{
  "type": "response.output_item.added",
  "item": {
    "type": "message",
    "id": "msg_xxx",
    "role": "assistant",
    "content": [
      { "type": "output_text", "text": "" }
    ]
  },
  "output_index": 0
}

错误事件示例

{
  "type": "error",
  "message": "Upstream error: Connection timeout",
  "code": 500
}

结束标记

data: [DONE]

FormData 说明

支持 multipart/form-data，其中 input、skill_options 可为 JSON 字符串，服务端会解析。

5. 取消 Agent 响应

接口说明

取消正在进行的 Agent 流式响应请求，需使用发起请求时传入或返回的 requestId。

方法 POST

路径 /v1/responses/cancel/:requestId

请求示例

POST /v1/responses/cancel/req_1234567890

路径参数说明

requestId (string, 必填): 要取消的请求 ID（与 /v1/responses 中的 requestId 一致）

6. 视频生成

接口说明

生成视频内容，支持文生视频、图生视频、视频参考、多模态编辑（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 项结构

字段	类型	说明
`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, 可选): 时长（秒），默认 5
audio (boolean, 可选): 是否生成/保留音频
framespersecond (number, 可选): 帧率
watermark (boolean, 可选): 是否添加水印，默认 false
seed (number, 可选): 随机种子，默认 -1
camerafixed (boolean, 可选): 是否固定镜头，默认 false
camera_control (string, 可选): 镜头控制类型
negative_prompt (string, 可选): 负面提示词（可灵）
cfg_scale (number, 可选): CFG 权重（可灵）

7. 音乐生成

接口说明

同步提交和返回结果

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

8. 语音合成

接口说明

同步提交和返回结果

方法 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, 可选): 情感

9. 创建数字人

接口说明

创建数字人形象

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

10. 生成数字人视频

接口说明

生成数字人视频

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

11. 异步生成任务弃用，可以用/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"

12. 查询异步任务结果

接口说明

查询异步任务的结果

方法 GET

路径 /v1/ai/result/:taskId

请求示例

GET /v1/ai/result/task_123456

路径参数说明

taskId (string, 必填): 任务ID

13. 取消任务

接口说明

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

方法 GET

路径 /v1/ai/cancel/:taskId

请求示例

GET /v1/ai/cancel/task_123456

路径参数说明

taskId (string, 必填): 任务ID

14. 获取模型清单（OpenAI 兼容）

接口说明

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

使用建议：本接口主要为兼容 OpenAI 格式设计，参数较少，返回结构固定。内部使用或需要按能力筛选模型时，建议使用下方「按能力类型查询模型列表」接口。

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

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

接口说明

根据模型能力类型查询可用模型，返回 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：文本对话
- image_generate：图像生成
- image_edit：图像编辑
- image_analysis：图像理解
- video_generate：视频生成
- 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'
  | 'image_generate'
  | 'image_edit'
  | 'image_analysis'
  | 'video_generate'
  | 'image_to_video'
  | 'video_edit'
  | 'omni_video'
  | 'tools_call'
  | 'audio_generate'
  | 'text_to_model'
  | 'image_to_model'
  | 'multiview_to_model'
  | 'digital_human_generate'
  | 'text_to_speech'
  | 'speech_to_text'
  | 'video_understanding';

/** 平台模型（含 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; // 平台提供方，接口层追加
}

16. 文件上传

接口说明

开放接口上传文件，上传后为临时文件，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, 可选): 保存时的文件名，不传时使用原文件名或自动生成

限制说明

单文件大小：20MB
支持类型：图片（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，不等待任务完成
- 同步模式（默认）: 等待任务完成后返回结果

异步模式示例

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项目的开发学习。如果你想快速构建自己的落地的商业项目，建议选择更加成熟的商业版或者企业版

Agent 脚本开发指南

结合 Agent 脚本执行工具与 Sandbox 沙箱服务，开发可在 Agent 对话中运行的 Python / JavaScript 脚本