青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
GET/mj/task/{id}/fetch

根据任务ID 查询任务状态

查询单个 MJ 任务的状态、结果图片、失败原因和可执行按钮。

API Key application/json
MJ 异步任务协议

调用与返回说明

读取 指定 ID 获取任务。MJ 接口采用“提交任务 → 保存任务 ID → 查询/回调 → 读取结果或执行后续动作”的异步模式，不是同步返回图片或视频。

请求时注意

  • 所有 MJ 接口都要在 Header 中发送 Authorization: Bearer <API_KEY>。生产环境请从服务端环境变量读取 Key。
  • 请求地址使用当前站点配置的 API Base URL 拼接本文 endpoint；不要把 /v1 误加到 /mj 路径，也不要重复拼接 Base URL。
  • 只查询已保存的任务 ID；任务 ID 不能被 URL 编码破坏。
  • 轮询应设置间隔、总超时和最大次数，避免对未完成任务高频请求。

返回时注意

  • 先检查 HTTP 状态，再检查响应体中的 code 或 status。提交接口的 code=1 通常表示成功接收，result 才是后续查询使用的任务 ID。
  • SUCCESS 才表示结果完整；FAILURE 读取 failReason；CANCEL 表示已取消；MODAL 表示需要继续提交 Modal。
  • buttons[].customId 是 Action 的唯一可靠输入，按钮 label 仅用于展示。
  • 任务查询的终态包括 SUCCESS、FAILURE、CANCEL；MODAL 表示需要继续提交 Modal。不要只根据 progress=100% 判定成功。
Request

请求

/mj/task/{id}/fetch

Body

可选

GET 请求无需 JSON 请求体，只需发送页面列出的请求头和路径、查询参数。

路径、查询与 Header 参数

参数位置类型必填说明示例
idPathstring是任务 ID。TASK_ID
AuthorizationHeaderstring是必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。Bearer YOUR_API_KEY
Response

返回响应 200

HTTP 成功不等于任务成功；请继续检查响应体中的 code 或 status。
响应 200json
响应 200object
idstring

任务 ID。

statusstring

任务状态：NOT_START、SUBMITTED、MODAL、IN_PROGRESS、FAILURE、SUCCESS、CANCEL。

progressstring

任务进度，例如 0%、50%、100%；这是展示字段，不应替代 status 判定。

imageUrlstring

主图链接。任务成功后读取；失败或未完成时可能为空。

imageUrlsarray<string>

多图结果的链接列表；字段可能按任务类型返回或为空。

元素string
actionstring

任务类型，例如 IMAGINE、UPSCALE、VARIATION、BLEND、DESCRIBE。

customIdstring

当前任务动作标识。

botTypestring

使用的机器人类型，例如 MID_JOURNEY 或 NIJI_JOURNEY。

promptstring

原始提示词。

promptEnstring

服务端生成或转换后的英文提示词。

descriptionstring

任务状态描述。

failReasonstring

失败原因；只有 FAILURE 等失败状态时重点读取。

submitTimeinteger

提交时间戳，通常为毫秒时间戳。

startTimeinteger

开始处理时间戳。

finishTimeinteger

完成或结束时间戳。

buttons[]array<object>

任务可执行按钮列表。Action 的 customId 必须从这里读取，不能自行拼接。

maskBase64string

任务相关蒙版信息，可能为空。

buttonsarray<object>
元素array<object>

任务可执行按钮列表。Action 的 customId 必须从这里读取，不能自行拼接。

customIdstring

按钮动作标识，提交 Action 时作为 customId。

labelstring

按钮文案，例如 U1、U2、V1。

emojistring

按钮图标，可能为空。

propertiesobject
finalPromptstring

最终使用的提示词。

finalZhPromptstring

最终中文提示词，可能为空。

MJ 异步任务协议

调用与返回说明

读取 指定 ID 获取任务。MJ 接口采用“提交任务 → 保存任务 ID → 查询/回调 → 读取结果或执行后续动作”的异步模式，不是同步返回图片或视频。

请求时注意

  • 所有 MJ 接口都要在 Header 中发送 Authorization: Bearer <API_KEY>。生产环境请从服务端环境变量读取 Key。
  • 请求地址使用当前站点配置的 API Base URL 拼接本文 endpoint；不要把 /v1 误加到 /mj 路径，也不要重复拼接 Base URL。
  • 只查询已保存的任务 ID；任务 ID 不能被 URL 编码破坏。
  • 轮询应设置间隔、总超时和最大次数，避免对未完成任务高频请求。

返回时注意

  • 先检查 HTTP 状态，再检查响应体中的 code 或 status。提交接口的 code=1 通常表示成功接收，result 才是后续查询使用的任务 ID。
  • SUCCESS 才表示结果完整；FAILURE 读取 failReason；CANCEL 表示已取消；MODAL 表示需要继续提交 Modal。
  • buttons[].customId 是 Action 的唯一可靠输入，按钮 label 仅用于展示。
  • 任务查询的终态包括 SUCCESS、FAILURE、CANCEL；MODAL 表示需要继续提交 Modal。不要只根据 progress=100% 判定成功。