Midjourney API 接口文档

版本: v1.0
最后更新: 2026-06-15
Base URL: https://cloud.ve2s.ai
认证方式: Bearer Token

1. 概述

本接口提供 Midjourney 图像生成能力的 API 封装，支持以下核心功能：

功能	说明
Imagine	根据文本提示词生成图像（四宫格）
Upscale (U1-U4)	将四宫格中指定图像放大为高清大图
Variation (V1-V4)	基于四宫格中指定图像生成变体
Reroll	使用相同提示词重新生成四宫格

2. 认证与通用约定

2.1 请求头

所有请求必须包含以下 Header：

Header	必填	值	说明
`Authorization`	是	`Bearer {API_KEY}`	API 密钥认证
`Content-Type`	是	`application/json`	请求体格式
`User-Agent`	是	任意合法 UA 字符串	必须携带，否则会被 Cloudflare 拦截返回 403

2.2 通用响应格式

{
  "code": 1,
  "description": "提交成功",
  "result": "任务ID",
  "properties": { ... }
}

字段	类型	说明
`code`	int	状态码，`1` 表示成功，其他值表示失败
`description`	string	状态描述信息
`result`	string	任务ID（提交类接口返回）
`properties`	object	附加信息（队列数、实例ID等）

3. 接口列表

3.1 提交绘图任务 (Imagine)

根据文本提示词提交 Midjourney 绘图任务。

请求

POST /mj/submit/imagine

请求体

字段	类型	必填	说明
`prompt`	string	是	Midjourney 提示词，支持原生参数如 `--v 6.1`、`--ar 16:9`
`botType`	string	否	机器人类型，默认 `MID_JOURNEY`，可选 `NIJI_JOURNEY`
`accountFilter`	object	否	账户过滤条件
`accountFilter.modes`	string[]	否	生成模式，可选 `FAST`、`RELAX`、`TURBO`

请求示例

响应示例

{
  "code": 1,
  "description": "提交成功",
  "result": "1781524258075013",
  "properties": {
    "discordInstanceId": "273d9093c1c54b6b",
    "discordChannelId": "273d9093c1c54b6b"
  }
}

3.2 查询任务状态 (Fetch)

查询指定任务的执行状态、进度和结果。

请求

GET /mj/task/{taskId}/fetch

路径参数

参数	类型	说明
`taskId`	string	提交任务时返回的任务ID

请求示例

响应示例

{
  "id": "1781524258075013",
  "action": "IMAGINE",
  "prompt": "a futuristic cityscape at sunset --v 6.1",
  "promptEn": "a futuristic cityscape at sunset --v 6.1",
  "description": "提交成功",
  "status": "SUCCESS",
  "progress": "100%",
  "submitTime": 1781524258075,
  "startTime": 1781524259689,
  "finishTime": 1781524294590,
  "imageUrl": "www.yourdomain.com/mj/image/1781524258075013",
  "failReason": "",
  "buttons": [
    {
      "customId": "MJ::JOB::upsample::1::675515df-961f-411e-8e9b-d81ac68427f5",
      "emoji": "",
      "label": "U1",
      "type": 2,
      "style": 2
    },
    {
      "customId": "MJ::JOB::reroll::0::675515df-961f-411e-8e9b-d81ac68427f5::SOLO",
      "emoji": "🔄",
      "label": "",
      "type": 2,
      "style": 2
    }
  ],
  "properties": {
    "finalPrompt": "a futuristic cityscape at sunset --v 6.1 --fast",
    "finalZhPrompt": ""
  }
}

响应字段说明

字段	类型	说明
`id`	string	任务唯一标识
`action`	string	任务类型：`IMAGINE`、`UPSCALE`、`VARIATION`、`REROLL`
`prompt`	string	原始提示词
`status`	string	任务状态，详见任务状态枚举
`progress`	string	进度百分比，如 `0%`、`50%`、`100%`
`imageUrl`	string	生成图片的访问路径（需替换为实际域名前缀）
`failReason`	string	失败原因（仅失败时有值）
`buttons`	array	可执行操作列表，包含 U1-U4、V1-V4、Reroll 等按钮信息
`buttons[].customId`	string	操作唯一标识，提交 Action 时必须原样传入
`buttons[].label`	string	按钮显示文本（U1、V2 等）
`submitTime`	int64	提交时间戳（毫秒）
`startTime`	int64	开始执行时间戳（毫秒）
`finishTime`	int64	完成时间戳（毫秒）

3.3 提交操作任务 (Action)

对已完成的任务执行后续操作（放大、变体、重绘）。

请求

POST /mj/submit/action

请求体

字段	类型	必填	说明
`taskId`	string	是	原始任务ID
`customId`	string	是	从 Fetch 接口 `buttons` 数组中获取的完整 `customId`，不可手动拼接

重要: customId 包含每次任务生成的唯一 UUID，不同任务之间不通用。必须从 Fetch 接口的 buttons 数组中原样复制。

请求示例

响应示例

{
  "code": 1,
  "description": "排队中，前面还有5个任务",
  "result": "1781524431429700",
  "properties": {
    "numberOfQueues": 5,
    "discordInstanceId": "273d9093c1c54b6b",
    "discordChannelId": "273d9093c1c54b6b"
  }
}

Action 提交后会返回新的任务ID，后续通过该新ID轮询状态。

3.4 获取生成图片 (Image)

直接获取任务生成的图片文件。

请求

GET /mj/image/{taskId}

路径参数

参数	类型	说明
`taskId`	string	任务ID

请求示例

响应: 二进制图片文件（Content-Type: image/png）

4. 完整调用流程

┌─────────────────────────────────────────────────────────────────┐
│                      Midjourney API 调用流程                      │
└─────────────────────────────────────────────────────────────────┘

  Step 1                Step 2                Step 3              Step 4
┌─────────┐     ┌──────────────────┐    ┌──────────────┐    ┌──────────────┐
│ Imagine  │────>│  轮询 Fetch 状态   │───>│  获取 buttons │───>│ 提交 Action  │
│ 提交绘图  │     │  等待 SUCCESS     │    │  提取 customId│    │ (可选操作)   │
└─────────┘     └──────────────────┘    └──────────────┘    └──────────────┘
     │                   │                      │                    │
     v                   v                      v                    v
  返回 taskId       返回完整任务信息         buttons 数组         返回新 taskId
                   含 imageUrl              含 customId           ─────┐
                                                                      │
                                                                      v
                                                              ┌──────────────┐
                                                              │ 轮询新任务状态 │
                                                              │ 等待 SUCCESS  │
                                                              └──────────────┘

详细步骤说明

Step 1 — 提交绘图任务

发送提示词，获得 taskId（如 1781524258075013）。

Step 2 — 轮询任务状态

以 3~~5 秒间隔轮询，直到 status 变为 SUCCESS（通常需要 30~~120 秒）。

建议轮询策略：

间隔: 首次 5 秒，之后每 3 秒

超时: 最多轮询 5 分钟

终止条件: status 为 SUCCESS 或 FAILURE

Step 3 — 提取可用操作

任务完成后，响应中的 buttons 数组包含所有可执行操作。每个按钮的 customId 是提交 Action 的必要参数。

Step 4 — 提交后续操作（可选）

传入原始 taskId 和从 buttons 中获取的完整 customId。提交后返回新的 taskId，需再次轮询直至完成。

5. customId 格式说明

customId 由 Midjourney 动态生成，每次任务都不同。格式如下：

5.1 格式模板

MJ::JOB::{action}::{index}::{uuid}[::SOLO]

组成部分	说明
`MJ::JOB`	固定前缀
`{action}`	操作类型：`upsample`、`variation`、`reroll`
`{index}`	操作序号：`1`-`4` 对应四宫格位置，reroll 固定为 `0`
`{uuid}`	任务唯一标识符（UUID v4），每次生成不同
`::SOLO`	仅 reroll 操作包含此后缀

5.2 实际示例

以任务 1781524258075013 为例，Fetch 返回的 buttons 中包含以下 customId：

操作	label	customId
放大第1张	U1	`MJ::JOB::upsample::1::675515df-961f-411e-8e9b-d81ac68427f5`
放大第2张	U2	`MJ::JOB::upsample::2::675515df-961f-411e-8e9b-d81ac68427f5`
放大第3张	U3	`MJ::JOB::upsample::3::675515df-961f-411e-8e9b-d81ac68427f5`
放大第4张	U4	`MJ::JOB::upsample::4::675515df-961f-411e-8e9b-d81ac68427f5`
重新生成	🔄	`MJ::JOB::reroll::0::675515df-961f-411e-8e9b-d81ac68427f5::SOLO`
变体第1张	V1	`MJ::JOB::variation::1::675515df-961f-411e-8e9b-d81ac68427f5`
变体第2张	V2	`MJ::JOB::variation::2::675515df-961f-411e-8e9b-d81ac68427f5`
变体第3张	V3	`MJ::JOB::variation::3::675515df-961f-411e-8e9b-d81ac68427f5`
变体第4张	V4	`MJ::JOB::variation::4::675515df-961f-411e-8e9b-d81ac68427f5`

5.3 四宫格位置对照

┌─────────┬─────────┐
│  1 (U1) │  2 (U2) │
│  (V1)   │  (V2)   │
├─────────┼─────────┤
│  3 (U3) │  4 (U4) │
│  (V3)   │  (V4)   │
└─────────┴─────────┘

再次强调: 不要尝试手动拼接 customId。UUID 部分由 Midjourney 服务端生成，必须通过 Fetch 接口的 buttons 数组获取。

6. 任务状态枚举

status	说明	是否终态
`NOT_START`	未开始	否
`SUBMITTED`	已提交	否
`IN_PROGRESS`	执行中（可通过 `progress` 字段查看百分比）	否
`SUCCESS`	执行成功	是
`FAILURE`	执行失败（查看 `failReason` 获取原因）	是

7. 错误码说明

code	description	原因与处理
`1`	提交成功	正常
`21`	任务已存在	重复提交，使用已有 taskId 查询
`22`	排队中	队列繁忙，等待执行
`23`	队列已满	稍后重试
`24`	提示词包含敏感内容	修改提示词后重试
其他	见 description 字段	根据描述排查

8. 完整代码示例

8.1 Python 完整流程

8.2 cURL 完整流程

9. 常见问题 (FAQ)

Q1: customId 可以手动拼接吗？

不可以。 customId 中的 UUID 由 Midjourney 服务端为每次任务动态生成，不同任务的 UUID 不同。必须通过 Fetch 接口的 buttons 数组获取完整的 customId。

Q2: 为什么请求返回 403？

请检查是否携带了 User-Agent 请求头。Cloudflare 前置防护会拦截没有 UA 的请求，返回 403 error code: 1010。

Q3: 任务一般需要多久完成？

操作	预估耗时
Imagine（四宫格）	30~120 秒
Upscale（放大）	15~60 秒
Variation（变体）	30~120 秒
Reroll（重绘）	30~120 秒

实际耗时取决于队列长度和所选模式（FAST/TURBO/RELAX）。

Q4: imageUrl 中 `www.yourdomain.com` 是什么？

这是占位域名。实际获取图片请使用 GET /mj/image/{taskId} 接口，无需解析 imageUrl 字段。

Q5: FAST / RELAX / TURBO 模式有什么区别？

模式	速度	消耗
`TURBO`	最快	高
`FAST`	较快	中
`RELAX`	较慢（排队）	低

文档结束

Midjourney API 接口文档

目录#

1. 概述#

2. 认证与通用约定#

2.1 请求头#

2.2 通用响应格式#

3. 接口列表#

3.1 提交绘图任务 (Imagine)#

3.2 查询任务状态 (Fetch)#

3.3 提交操作任务 (Action)#

3.4 获取生成图片 (Image)#

4. 完整调用流程#

详细步骤说明#

5. customId 格式说明#

5.1 格式模板#

5.2 实际示例#

5.3 四宫格位置对照#

6. 任务状态枚举#

7. 错误码说明#

8. 完整代码示例#

8.1 Python 完整流程#

8.2 cURL 完整流程#

9. 常见问题 (FAQ)#

Q1: customId 可以手动拼接吗？#

Q2: 为什么请求返回 403？#

Q3: 任务一般需要多久完成？#

Q4: imageUrl 中 www.yourdomain.com 是什么？#

Q5: FAST / RELAX / TURBO 模式有什么区别？#

目录

1. 概述

2. 认证与通用约定

2.1 请求头

2.2 通用响应格式

3. 接口列表

3.1 提交绘图任务 (Imagine)

3.2 查询任务状态 (Fetch)

3.3 提交操作任务 (Action)

3.4 获取生成图片 (Image)

4. 完整调用流程

详细步骤说明

5. customId 格式说明

5.1 格式模板

5.2 实际示例

5.3 四宫格位置对照

6. 任务状态枚举

7. 错误码说明

8. 完整代码示例

8.1 Python 完整流程

8.2 cURL 完整流程

9. 常见问题 (FAQ)

Q1: customId 可以手动拼接吗？

Q2: 为什么请求返回 403？

Q3: 任务一般需要多久完成？

Q4: imageUrl 中 `www.yourdomain.com` 是什么？

Q5: FAST / RELAX / TURBO 模式有什么区别？