GET/mj/task/{id}/fetch

根据任务ID 查询任务状态

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

API Key HTTP

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% 判定成功。

请求示例

curl https://top.qingyuntop.ai/mj/task/{id}/fetch \
  -H "Authorization: Bearer ${QINGYUN_TOP_API_KEY}"

请求参数

参数	位置	类型	必填	说明	示例
`Authorization`	Header	string	是	必填。Bearer API Key，例如 Bearer ${QINGYUN_TOP_API_KEY}。不要把真实 Key 写入前端、日志或代码仓库。	-
`id`	Path	string	是	任务 ID。	TASK_ID

返回响应 (200)

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

参数	位置	类型	必填	说明	示例
`id`	响应 JSON	string	否	任务 ID。	-
`status`	响应 JSON	string	否	任务状态：NOT_START、SUBMITTED、MODAL、IN_PROGRESS、FAILURE、SUCCESS、CANCEL。	-
`progress`	响应 JSON	string	否	任务进度，例如 0%、50%、100%；这是展示字段，不应替代 status 判定。	-
`imageUrl`	响应 JSON	string	否	主图链接。任务成功后读取；失败或未完成时可能为空。	-
`imageUrls`	响应 JSON	array<string>	否	多图结果的链接列表；字段可能按任务类型返回或为空。	-
`action`	响应 JSON	string	否	任务类型，例如 IMAGINE、UPSCALE、VARIATION、BLEND、DESCRIBE。	-
`customId`	响应 JSON	string	否	当前任务动作标识。	-
`botType`	响应 JSON	string	否	使用的机器人类型，例如 MID_JOURNEY 或 NIJI_JOURNEY。	-
`prompt`	响应 JSON	string	否	原始提示词。	-
`promptEn`	响应 JSON	string	否	服务端生成或转换后的英文提示词。	-
`description`	响应 JSON	string	否	任务状态描述。	-
`failReason`	响应 JSON	string	否	失败原因；只有 FAILURE 等失败状态时重点读取。	-
`submitTime`	响应 JSON	integer	否	提交时间戳，通常为毫秒时间戳。	-
`startTime`	响应 JSON	integer	否	开始处理时间戳。	-
`finishTime`	响应 JSON	integer	否	完成或结束时间戳。	-
`buttons[]`	响应 JSON	array<object>	否	任务可执行按钮列表。Action 的 customId 必须从这里读取，不能自行拼接。	-
`buttons[].customId`	响应 JSON	string	否	按钮动作标识，提交 Action 时作为 customId。	-
`buttons[].label`	响应 JSON	string	否	按钮文案，例如 U1、U2、V1。	-
`buttons[].emoji`	响应 JSON	string	否	按钮图标，可能为空。	-
`maskBase64`	响应 JSON	string	否	任务相关蒙版信息，可能为空。	-
`properties.finalPrompt`	响应 JSON	string	否	最终使用的提示词。	-
`properties.finalZhPrompt`	响应 JSON	string	否	最终中文提示词，可能为空。	-

响应示例

{
  "id": "TASK_ID",
  "action": "IMAGINE",
  "botType": "MID_JOURNEY",
  "prompt": "a cat in a red jacket",
  "status": "SUCCESS",
  "progress": "100%",
  "imageUrl": "https://example.com/result.png",
  "imageUrls": ["https://example.com/result.png"],
  "description": "Success",
  "failReason": "",
  "buttons": [
    {"customId": "MJ::JOB::upsample::1::UUID", "label": "U1", "emoji": ""},
    {"customId": "MJ::JOB::variation::1::UUID", "label": "V1", "emoji": ""}
  ]
}

来源原始接口定义（用于追溯）

以下内容来自 Apifox 快照，可能包含兼容层字段或旧示例；公开调用请以本页的协议说明和当前模型列表为准。

{
  "method": "get",
  "path": "/mj/task/{id}/fetch",
  "description": "查询单个 MJ 任务的状态、结果图片、失败原因和可执行按钮。",
  "parameters": {
    "header": [
      {
        "name": "Authorization",
        "type": "string",
        "required": true,
        "description": "Bearer API Key。所有 MJ 接口都必须携带；不要把真实 Key 写入前端、日志或代码仓库。",
        "sampleValue": "Bearer ${QINGYUN_TOP_API_KEY}"
      }
    ],
    "path": [
      {
        "name": "id",
        "type": "string",
        "required": true,
        "description": "任务 ID。",
        "sampleValue": "TASK_ID"
      }
    ]
  },
  "responses": [
    {
      "code": 200,
      "name": "成功或业务结果",
      "contentType": "json",
      "jsonSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "任务 ID。"
          },
          "status": {
            "type": "string",
            "description": "任务状态：NOT_START、SUBMITTED、MODAL、IN_PROGRESS、FAILURE、SUCCESS、CANCEL。"
          },
          "progress": {
            "type": "string",
            "description": "任务进度，例如 0%、50%、100%；这是展示字段，不应替代 status 判定。"
          },
          "imageUrl": {
            "type": "string",
            "description": "主图链接。任务成功后读取；失败或未完成时可能为空。"
          },
          "imageUrls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "多图结果的链接列表；字段可能按任务类型返回或为空。"
          },
          "action": {
            "type": "string",
            "description": "任务类型，例如 IMAGINE、UPSCALE、VARIATION、BLEND、DESCRIBE。"
          },
          "customId": {
            "type": "string",
            "description": "当前任务动作标识。"
          },
          "botType": {
            "type": "string",
            "description": "使用的机器人类型，例如 MID_JOURNEY 或 NIJI_JOURNEY。"
          },
          "prompt": {
            "type": "string",
            "description": "原始提示词。"
          },
          "promptEn": {
            "type": "string",
            "description": "服务端生成或转换后的英文提示词。"
          },
          "description": {
            "type": "string",
            "description": "任务状态描述。"
          },
          "failReason": {
            "type": "string",
            "description": "失败原因；只有 FAILURE 等失败状态时重点读取。"
          },
          "submitTime": {
            "type": "integer",
            "description": "提交时间戳，通常为毫秒时间戳。"
          },
          "startTime": {
            "type": "integer",
            "description": "开始处理时间戳。"
          },
          "finishTime": {
            "type": "integer",
            "description": "完成或结束时间戳。"
          },
          "buttons[]": {
            "type": "array<object>",
            "description": "任务可执行按钮列表。Action 的 customId 必须从这里读取，不能自行拼接。"
          },
          "maskBase64": {
            "type": "string",
            "description": "任务相关蒙版信息，可能为空。"
          }
        },
        "x-apifox-orders": [
          "id",
          "status",
          "progress",
          "imageUrl",
          "imageUrls",
          "action",
          "customId",
          "botType",
          "prompt",
          "promptEn",
          "description",
          "failReason",
          "submitTime",
          "startTime",
          "finishTime",
          "buttons[]",
          "maskBase64"
        ]
      },
      "description": "HTTP 成功不等于任务成功；请继续检查响应体中的 code 或 status。"
    }
  ],
  "responseExamples": [
    {
      "name": "规范示例",
      "mediaType": "application/json",
      "data": "{\n  \"id\": \"TASK_ID\",\n  \"action\": \"IMAGINE\",\n  \"botType\": \"MID_JOURNEY\",\n  \"prompt\": \"a cat in a red jacket\",\n  \"status\": \"SUCCESS\",\n  \"progress\": \"100%\",\n  \"imageUrl\": \"https://example.com/result.png\",\n  \"imageUrls\": [\"https://example.com/result.png\"],\n  \"description\": \"Success\",\n  \"failReason\": \"\",\n  \"buttons\": [\n    {\"customId\": \"MJ::JOB::upsample::1::UUID\", \"label\": \"U1\", \"emoji\": \"\"},\n    {\"customId\": \"MJ::JOB::variation::1::UUID\", \"label\": \"V1\", \"emoji\": \"\"}\n  ]\n}"
    }
  ]
}