Midjourney API 接口文档
版本: v1.2
最后更新: 2026-08-04
Base URL:https://platform.dataeyes.ai
认证方式: Bearer Token
目录
1. 概述
| 能力 | 说明 |
|---|---|
| 文生图 (Imagine) | 根据文本提示词生成图像（四宫格） |
| 放大 / 变体 / 重绘 (Action) | 对四宫格执行 U1-U4 放大、V1-V4 变体、Reroll 重绘 |
| 编辑图片 (Edits) | 对外部传入的图片进行改图或局部重绘 |
| 多图混合 (Blend) | 将 2~5 张图片混合为一张新图 |
| 图生文 (Describe) | 分析图片反推提示词 |
| 换脸 / 上传 / Seed 等 | 换脸、图片上传、获取 Seed、批量查询等扩展能力 |
2. 认证与通用约定
2.1 请求头
| 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等） |
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 │
└──────────────┘POST /mj/submit/imagine，发送提示词，获得 taskId。GET /mj/task/{taskId}/fetch，以 3-5 秒间隔轮询，直到 status 为 SUCCESS（通常需要 30~120 秒）。建议策略：首次 5 秒后查询，之后每 3 秒一次，最多轮询 5 分钟；status 为 SUCCESS 或 FAILURE 时终止。buttons 数组包含所有可执行操作，每个按钮的 customId 是提交 Action 的必要参数。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 秒 |
Q4: imageUrl 中 www.yourdomain.com 是什么？
GET /mj/image/{taskId} 接口，无需解析 imageUrl 字段。Q5: FAST / RELAX / TURBO 模式有什么区别？
| 模式 | 速度 | 消耗 |
|---|---|---|
TURBO | 最快 | 高 |
FAST | 较快 | 中 |
RELAX | 较慢（排队） | 低 |
Q6: 调用接口返回 model_not_found 怎么办？
