Midjourney API 快速入门

🎯 理解核心概念

MidJourney API 模拟 Discord 按钮交互。与普通 REST API 不同，它是一个状态机，每次操作都会返回新的按钮供下一步使用。

4 个核心接口

接口	用途	使用时机
`POST /mj/submit/imagine`	文生图	所有流程的起点
`GET /mj/task/{id}/fetch`	查询任务状态 & 获取按钮	每次提交后轮询
`POST /mj/submit/action`	点击按钮（放大、变体、缩放等）	对图片进行操作时
`POST /mj/submit/modal`	提交额外输入	仅当状态为 `MODAL` 时

📊 完整工作流程图

┌─────────────────────────────────────────────────────────────────────────────┐
│                         MIDJOURNEY API 工作流程                              │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌──────────────────┐
  │  POST /submit/   │  ← 第1步：提交 prompt，获取 task_id
  │     imagine      │
  └────────┬─────────┘
           │ 返回: { "result": "task_id_1" }
           ▼
  ┌──────────────────┐
  │ GET /task/{id}/  │  ← 第2步：轮询直到 status = "SUCCESS"
  │      fetch       │
  └────────┬─────────┘
           │ 返回: imageUrl + buttons[] (U1,U2,U3,U4,V1,V2,V3,V4,🔄)
           ▼
  ┌──────────────────┐
  │  POST /submit/   │  ← 第3步：使用 customId 点击按钮
  │     action       │
  └────────┬─────────┘
           │ 返回: { "result": "task_id_2" }
           ▼
  ┌──────────────────┐
  │ GET /task/{id}/  │  ← 第4步：轮询新任务
  │      fetch       │
  └────────┬─────────┘
           │
           ├─── status = "SUCCESS" → 完成！获取 imageUrl
           │
           └─── status = "MODAL" → 需要额外输入（见第5步）
                      │
                      ▼
           ┌──────────────────┐
           │  POST /submit/   │  ← 第5步：提交蒙版/提示词
           │      modal       │
           └────────┬─────────┘
                    │ 返回: { "result": "task_id_3" }
                    ▼
           ┌──────────────────┐
           │ GET /task/{id}/  │  ← 第6步：轮询直到 SUCCESS
           │      fetch       │
           └──────────────────┘

🔑 核心概念：按钮与 customId

每个成功的任务都会返回 buttons 数组。每个按钮都有一个 customId，用于触发下一个操作。

/mj/task/{id}/fetch 响应示例：

{
  "status": "SUCCESS",
  "imageUrl": "https://api.deerapi.com/mj/image/xxx",
  "buttons": [
    { "customId": "MJ::JOB::upsample::1::abc123", "label": "U1" },
    { "customId": "MJ::JOB::upsample::2::abc123", "label": "U2" },
    { "customId": "MJ::JOB::variation::1::abc123", "label": "V1" },
    { "customId": "MJ::JOB::reroll::0::abc123", "emoji": "🔄" }
  ]
}

⚠️ 重要： customId 不是固定值，每个任务都不同。必须从 buttons 数组中获取。

📋 各阶段按钮参考

IMAGINE 后（4 宫格图）

初始图片生成完成后返回以下按钮：

按钮	customId 格式	操作	结果
U1-U4	`MJ::JOB::upsample::1::xxx`	放大单张图片	高清单图
V1-V4	`MJ::JOB::variation::1::xxx`	生成变体	新的 4 宫格
🔄	`MJ::JOB::reroll::0::xxx::SOLO`	重新生成	新的 4 宫格

UPSCALE 后（单张图片）

放大后可使用编辑工具：

按钮	需要 Modal？
Upscale (Subtle) / Upscale (2x)	❌ 否
Upscale (Creative) / Upscale (4x)	❌ 否
Vary (Subtle) 🪄	❌ 否
Vary (Strong) 🪄	❌ 否
Vary (Region) 🖌️	✅ 是（需要蒙版）
Zoom Out 2x / 1.5x 🔍	❌ 否
Custom Zoom 🔍	✅ 是（需要提示词）
⬅️➡️⬆️⬇️ Pan	❌ 否
Animate 🎞️	❌ 否
🔄 Reroll	❌ 否

注意： 按钮名称和 customId 格式可能因 prompt 中指定的 MJ 版本而异（如 --v 6.1 vs --v 5.2）。务必从 API 响应中读取按钮。

⚠️ Inpaint (Vary Region) 按钮只有在 Upscale 后才会出现！

⚡ 完整示例：生成 & 放大

第 1 步：提交 Imagine 请求

响应：

{ "code": 1, "result": "1768464763141701" }

第 2 步：轮询任务状态

响应（完成时）：

{
  "status": "SUCCESS",
  "imageUrl": "https://api.deerapi.com/mj/image/1768464763141701",
  "buttons": [
    { "customId": "MJ::JOB::upsample::1::5f20922e-xxx", "label": "U1" },
    { "customId": "MJ::JOB::upsample::2::5f20922e-xxx", "label": "U2" },
    ...
  ]
}

第 3 步：点击 U1 放大

响应：

{ "code": 1, "result": "1768464800000000" }

第 4 步：轮询新任务 & 获取结果

当调用 /mj/submit/action 后任务状态变为 MODAL 而非 SUCCESS 时，必须调用 /mj/submit/modal 提供额外输入。

操作	按钮	需要提交
局部重绘	Vary (Region)	`maskBase64`（PNG 蒙版）+ `prompt`
自定义缩放	🔍 Custom Zoom	`prompt`（如 "your prompt --zoom 2"）

示例：局部重绘流程

🚀 速度模式选择

在路径前添加速度前缀：

模式	路径前缀	示例
Fast	`/mj-fast`	`/mj-fast/mj/submit/imagine`
Turbo	`/mj-turbo`	`/mj-turbo/mj/submit/imagine`
Relax	（默认）	`/mj/submit/imagine`

🔗 其他独立入口

以下 API 是独立入口，不遵循 imagine → action 流程：

接口	用途
`POST /mj/submit/blend`	2-5 张图片融合
`POST /mj/submit/describe`	图片反推提示词
`POST /mj/submit/video`	图片转视频
`POST /mj/submit/edits`	遮罩编辑图片

❓ 常见问题

问题	可能原因	解决方案
找不到 Vary (Region) 按钮	正在查看 4 宫格图	先点击 U1-U4 放大，再查看按钮
任务状态卡在 `MODAL`	操作需要额外输入	调用 `/mj/submit/modal` 提交数据
`customId` 无效	使用了过期或硬编码的值	从 `/mj/task/{id}/fetch` 响应获取最新值
`buttons` 数组为空	任务仍在进行中	等待 `status: "SUCCESS"` 后再读取按钮

🎯 理解核心概念#

4 个核心接口#

📊 完整工作流程图#

🔑 核心概念：按钮与 customId#

📋 各阶段按钮参考#

IMAGINE 后（4 宫格图）#

UPSCALE 后（单张图片）#

⚡ 完整示例：生成 & 放大#

第 1 步：提交 Imagine 请求#

第 2 步：轮询任务状态#

第 3 步：点击 U1 放大#

第 4 步：轮询新任务 & 获取结果#

⚠️ 什么时候需要 Modal？#

需要 Modal 的操作#

🚀 速度模式选择#

🔗 其他独立入口#

❓ 常见问题#