Midjourney API 接口文档

版本: v1.2
最后更新: 2026-08-04
Base URL: https://platform.dataeyes.ai
认证方式: Bearer Token

1. 概述

本平台提供 Midjourney 图像生成能力的 API 封装，覆盖以下能力：

能力	说明
文生图 (Imagine)	根据文本提示词生成图像（四宫格）
放大 / 变体 / 重绘 (Action)	对四宫格执行 U1-U4 放大、V1-V4 变体、Reroll 重绘
编辑图片 (Edits)	对外部传入的图片进行改图或局部重绘
多图混合 (Blend)	将 2~5 张图片混合为一张新图
图生文 (Describe)	分析图片反推提示词
换脸 / 上传 / Seed 等	换脸、图片上传、获取 Seed、批量查询等扩展能力

所有绘图类接口均为异步任务模式：提交任务 → 返回任务ID → 轮询查询 → 获取结果。

2. 认证与通用约定

2.1 请求头

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

Header	必填	值	说明
`Authorization`	是	`Bearer {API_KEY}`	API 密钥认证
`Content-Type`	是	`application/json`	请求体格式（POST 接口）
`User-Agent`	是	任意合法 UA 字符串	需要携带，否则会被安全防护拦截返回 403

2.2 通用响应格式

提交类接口统一返回：

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

字段	类型	说明
`code`	int	状态码，`1` 表示成功，其他值见错误码说明
`description`	string	状态描述信息
`result`	string	任务ID（上传图片接口为链接数组）
`properties`	object	附加信息（队列数、实例ID等）

查询类接口返回任务对象，字段见《查询任务状态（Fetch）》。

3. 接口总览

各接口的详细参数、示例请参见对应的接口文档页。

3.1 核心流程接口

接口	方法与路径	说明
文生图 (Imagine)	`POST /mj/submit/imagine`	提交绘图任务，生成四宫格
查询任务状态 (Fetch)	`GET /mj/task/{id}/fetch`	查询任务状态、进度、结果与可执行操作
执行操作 (Action)	`POST /mj/submit/action`	放大 (U1-U4)、变体 (V1-V4)、重绘等后续操作
获取生成图片 (Image)	`GET /mj/image/{id}`	直接获取任务生成的图片文件

3.2 扩展能力接口

接口	方法与路径	说明
提交弹窗确认 (Modal)	`POST /mj/submit/modal`	二段式操作确认（局部重绘、Custom Zoom），Action 返回 `code=21` 后调用
编辑图片 (Edits)	`POST /mj/submit/edits`	编辑外部传入的图片（改图/局部重绘）
多图混合 (Blend)	`POST /mj/submit/blend`	混合 2~5 张图片，支持 `PORTRAIT`/`SQUARE`/`LANDSCAPE` 比例
图生文 (Describe)	`POST /mj/submit/describe`	分析图片反推提示词，完成后返回 4 条建议提示词
提示词缩短 (Shorten)	`POST /mj/submit/shorten`	提示词分析与缩短
图生视频 (Video)	`POST /mj/submit/video`	基于任务图片生成视频
上传图片 (Upload)	`POST /mj/submit/upload-discord-images`	上传图片获取链接，可用于垫图
换脸 (FaceSwap)	`POST /mj/insight-face/swap`	将源图人脸替换到目标图
批量查询任务	`POST /mj/task/list-by-condition`	按任务ID列表批量查询
获取图片 Seed	`GET /mj/task/{id}/image-seed`	获取图片 seed 值，用于 `--seed` 参数

注意:
1.
各接口需账户开通对应模型权限后方可调用；若调用返回 model_not_found，请联系客服开通。
2.
图片链接过期时，请使用 GET /mj/image/{id} 重新获取图片。

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 — 提交绘图任务：POST /mj/submit/imagine，发送提示词，获得 taskId。

Step 2 — 轮询任务状态：GET /mj/task/{taskId}/fetch，以 3-5 秒间隔轮询，直到 status 为 SUCCESS（通常需要 30~120 秒）。建议策略：首次 5 秒后查询，之后每 3 秒一次，最多轮询 5 分钟；status 为 SUCCESS 或 FAILURE 时终止。

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

Step 4 — 提交后续操作（可选）：POST /mj/submit/action，传入原始 taskId 和从 buttons 中获取的完整 customId。返回新的 taskId，再次轮询直至完成。

任意时刻可通过 GET /mj/image/{taskId} 下载已完成任务的图片。

5. customId 格式说明

customId 由服务端为每次任务动态生成，不同任务之间不通用，不可手动拼接，必须从 Fetch 接口的 buttons 数组中原样复制。

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 实际示例

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

5.3 四宫格位置对照

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

6. 任务状态枚举

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

7. 错误码说明

code	description	原因与处理
`1`	提交成功	正常
`21`	任务已存在	需二次确认的操作（如局部重绘），配合 Modal 接口提交确认
`22`	排队中	队列繁忙，等待执行
`23`	队列已满	稍后重试
`24`	提示词包含敏感内容	修改提示词后重试
其他	见 description 字段	根据描述排查

8. 完整代码示例

8.1 Python 完整流程

8.2 cURL 完整流程

9. 常见问题 (FAQ)

Q1: customId 可以手动拼接吗？

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

Q2: 为什么请求返回 403？

请检查是否携带了 User-Agent 请求头。安全防护会拦截没有 UA 的请求。

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`	较慢（排队）	低

Q6: 调用接口返回 model_not_found 怎么办？

该接口对应的模型权限尚未开通，请联系客服为账户开通后再调用。

文档结束

Midjourney API 接口文档

目录#

1. 概述#

2. 认证与通用约定#

2.1 请求头#

2.2 通用响应格式#

3. 接口总览#

3.1 核心流程接口#

3.2 扩展能力接口#

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 模式有什么区别？#

Q6: 调用接口返回 model_not_found 怎么办？#

目录