接口说明

接口地址

POST /v1/midjourney/generations
POST /v1/midjourney/generations/{action}
GET  /v1/midjourney/{task_id}

Midjourney 是一套围绕"生成 → 查询 → 对结果做二次操作"的异步任务协议:提交请求立即返回 202 和任务对象(此时处于 SUBMITTED 状态),用返回的 task_id 轮询查询接口,直到任务进入终态(SUCCESS 或 FAILURE);部分操作会先进入中间态 MODAL,需要再提交一次才能继续。

鉴权方式与其他接口一致,见鉴权。

工作流总览

imagine(生成)
  └─ SUCCESS → 四宫格 grid_image_url + buttons
       ├─ upscale / variation / high_variation / low_variation(引用 index 或 buttons 中的 custom_id)
       ├─ reroll / pan / zoom(引用 buttons 中的 custom_id)
       ├─ remix_strong / remix_subtle
       ├─ inpaint → MODAL → modal(局部重绘,两步流程)
       └─ video(把某一张结果做成视频)

• 只有原始 imagine(或 blend/zoom/reroll 等同样产出新一组四宫格候选图的任务) 的查询响应才带 buttons 数组;upscale/variation 等选中单张图的结果不带 buttons。需要用 custom_id 引用二次操作时,必须从产出该四宫格的那个任务的响应里取,不能从 upscale 之类的下游结果里取。
• 全部 16 个操作端点的字段、父任务要求与示例见操作详解。

提交 imagine

POST /v1/midjourney/generations
POST /v1/midjourney/generations/imagine

两个路径等价。请求体为 JSON:

除上述字段外,平台还支持一组结构化参数,作为 -- 前缀写法的等价 JSON 字段透传给上游(平台本身不校验取值范围,非法值由上游处理;仅在 prompt 文本内联写 --ar 已经过真实调用验证,以下结构化字段建议优先用于替代对应的 -- 写法,遇到与 prompt 内联写法冲突时以上游实际行为为准):

版本与 Niji

version 传主版本号字符串。当前上游可用:"8.2"、"8.1"、"7"、"6.1"、"5.2"、"5.1"。

要用 Niji(动漫模型),传 niji: true 加 version: "7" 或 "6",上游会归一化为 Niji 7 / Niji 6。不要只传 niji: true 而不给版本。

{"prompt": "anime girl in a moonlit garden", "niji": true, "version": "7", "size": "9:16"}

版本会影响哪些操作可用:pan 只在 v6/v6.1/v7/v8.1/v8.2/niji6 上有效,remix_strong/remix_subtle 只在 v8.1/v8.2 上有效。详见操作详解。

版本不影响价格——各版本同档同价。

提交成功返回 202,响应体:

{"code": 200, "data": [{"task_id": "mj_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "submitted"}]}

查询任务

GET /v1/midjourney/{task_id}

task_id 为提交响应中的值(mj_ 前缀 + UUID)。任务不存在、或不属于当前 API Key 所在账户 → 404 task_not_found。

状态机

响应字段

所有状态都包含:

进入终态后追加:

SUCCESS 时,按操作类型追加以下之一:

• describe:仅 description(反推的提示词文本),不返回任何媒体字段。
• 产出新一组四宫格候选图的操作(imagine/blend/zoom/reroll/pan/variation 系列/remix 系列/inpaint→modal 的最终结果):grid_image_url(四宫格预览图)+ image_urls(数组,四张单图)。
• 产出单张图的操作(如 upscale):仅 image_urls(数组,一张)。
• video:仅 video_urls(数组)。

FAILURE 时追加:

容易搞错的几件事

upscale 不是放大。 它是从四宫格里把第 N 张切出来,本地合成、毫秒返回、几乎不会失败——真正烧算力的是上一步 imagine。要真正的 2 倍高清图,得走 HD upscale,那才是 60-120 秒的真实放大。两者同价。

variation 和 high_variation 不是"弱一点/强一点"的同一个操作。 variation 作用在四宫格上(等价 V1-V4),high_variation/low_variation 作用在 upscale 之后的单图上。父任务给错,上游会拒。

inpaint 免费不等于局部重绘免费。 inpaint 那一步确实是 0,但上游对 inpaint 和 modal 是分别计费两次的,这两步的钱一起算在 modal 档里(1.43104,正好是单步的两倍)。走完一轮局部重绘的成本,和做两次普通操作一样。

MODAL 不是失败。 它是 inpaint 之后等你补参数的正常中间态,轮询到它就该去调 modal,不是去重试 inpaint。30 分钟内不补参,任务会被自动取消并退款。

video 的 batch_size 是实打实的乘数。 传 4 就扣 4 份。720p 批量 4 段一次 20.8 积分,是 480p 单段 2.6 的 8 倍。出片只要一段就传 1,比稿才用 4。

speed 对 video 无效。 video 固定走 FAST 通道,传 relax 或 turbo 既不改价也不改排队。它只对生图类操作生效。

--raw 和 style: "raw" 是两个不同的 flag。 前者对应结构化字段 raw: true,后者对应 style: "raw"。想要哪个效果就传哪个,别互相替代。

pan 挑版本。 只在 v6/v6.1/v7/v8.1/v8.2/niji6 上有效,v5.2 及更早直接 FAILURE。而且它只吃 upscale 后的单图,连 HD upscale 的高清单图也一样被拒——这是 Midjourney 自身的限制。

计费

单位为积分(credits)。说明:

• inpaint 单独提交不计费,真正的局部重绘发生在随后的 modal 步骤,modal 档位已包含 inpaint+modal 两步的合计成本。
• video 的最终扣费 = 表中单价 × batch_size(可选 1/2/4)。batch_size: 4 就是实扣 4 份:720p 批量 4 段一次要 20.8 积分,比 480p 单段的 2.6 贵 8 倍。只要一段就传 1。
• video_type 含 720 时走 720p 档,其余走 480p 档。
• repeat(2-40)同样按次数倍增扣费,与 batch_size 是两个独立的乘数。
• 任务失败(FAILURE)自动全额退款,退款与终态判定同步完成,无需额外操作。
• 以上为当前生效价格,如有调整以实际扣费为准。

图片/视频有效期与 OSS 托管

生成结果会被平台转存到自有对象存储并签发可直接访问的 URL(grid_image_url/image_urls/video_urls),不依赖上游链接的时效:

• 图片:任务完成后 90 天内可访问。
• 视频:任务完成后 72 小时内可访问。

响应中不返回单独的过期时间字段,请在拿到 SUCCESS 结果后尽快下载并自行转存,不要长期依赖返回的链接。

错误

完整错误响应体格式与更多错误码见错误码。操作专属的父任务状态要求见操作详解。