Skip to main content

Midjourney 图片生成与编辑示例

通过 /v1/tob/diffusion 提交图片生成任务,使用 GET /v1/tob/job/{jobId} 查询进度和结果。生成完成后,可对图片进行变化、高清、延展、扩图和重塑等操作。 所有请求均使用 Bearer 鉴权,在请求头中传入 Authorization: Bearer <API-KEY>。

接口概览

所有提交接口都接收 application/json,返回同一种任务响应;二次编辑也会创建新的任务 id。

快速开始:提交与轮询

以下示例使用模型名 midjourney。运行前,将 <API-KEY> 替换为具有模型访问权限的 API Key。

模型名与版本选择

model 指定模型名称;text 中的 --v 或 --niji 参数指定生成版本。例如,使用 V8.2 时传入 "model": "midjourney",并在提示词末尾添加 --v 8.2。 在提示词末尾添加对应的版本参数。例如:
V8.2
Niji 7
每次请求选择一个版本。--v 用于 V6、V6.1、V7、V8.1、V8.2;--niji 用于 Niji 6、Niji 7。生成参数的范围及版本兼容性见本页参数支持矩阵。

请求参数约定

二次编辑使用来源任务的模型,请求体无需传入 model。提交和查询须使用同一个 API Key。任务结果通过轮询获取;请求体不接受 callback 或接口定义之外的字段。

任务响应与状态

提交和查询都返回任务对象。下面是示意结构,任务提交时 urls 通常为空;查询成功后从 urls 取图片地址。
id 是任务 ID,提交编辑操作时放入 jobId,查询时放入 URL 路径。status 是数字,不是通用异步图片接口的 queued / completed 字符串;图片在 urls,不在 data[].url。cost、audits、seed 等上游字段可能返回,任务完成前的费用不是最终费用。 建议间隔 5 秒查询。客户端等待超时不等于任务失败;已经拿到 id 时,继续查询原任务即可。任务记录保留 30 天,图片地址按返回 URL 的有效期使用,建议及时保存图片。

版本与 MJ 参数

在 text 中写参数,而不是增加 size、ratio、quality、seed、n 等独立 JSON 字段。 图片 URL 请替换为上游可访问的真实地址。平台原样转发 text;--ar、--raw、--tile、--seed、--chaos、--stylize、--weird、--quality、速度模式及参考图参数均在这个字段中传入。各参数的可用版本、取值和组合限制由上游决定,不能将示例理解为所有版本均支持同一组参数。 参数和编辑能力受来源任务的版本限制。例如 V8.1 / V8.2 不支持 pan、outpaint、inpaint 和 enhance;需要这些操作时,使用支持它们的版本生成来源任务。V7 Draft 不能与 --tile 或 --oref 同时使用。各版本的参数范围与编辑能力分别列在下方两张矩阵中。

参数支持矩阵

以下矩阵依据阿里云版本指南整理,更新于 2026-10-10。✅ 表示支持,❌ 表示不支持,?表示文档未明确或存在冲突。参数统一写入 text;组合使用时还需满足下方的参数限制。 ¹ --cref 的通用接口说明仅列 V6 / V6.1 / Niji 6;--oref / --ow 仅列 V7,不能因版本更高推断 V8 支持。 ² V8 指南的参数表将 --draft 描述为每任务 24 张、费用与标准任务一致;这与 V7 草图模式的语义不同。

版本功能矩阵

下表列出各版本的图片操作支持情况。二次编辑须使用兼容的来源任务;上传编辑、转绘和去背景的请求字段以各接口定义为准。 ³ V8 高清采用 diffusion + --hd --seed;不要按旧版标准 / 创意高清的语义理解。使用相同描述与种子生成高清仍属于新任务。 ⁴ reroll 接收来源 jobId,使用该任务的参数重新生成;版本指南未逐版本列出兼容性,因此标为通用接口。 ⁵ V7 的 --oref 来源任务不兼容延展、扩图及区域重绘。 本页涵盖图片生成、编辑与任务查询接口。

参数组合限制与上游文档差异

  • V7 --draft 不可与 --tile、--oref、速度模式或 --q 4 组合;enhance 需要支持增强的 Draft 来源任务。
  • V7 --oref 只接收一张图,并且不兼容 pan、outpaint、inpaint。V7 / V8 不支持多提示词 :: 或 --stop。
  • V8 仅接受 --sv 6,不支持 --turbo、--bs;V8.1 的质量值为 1 / 4,V8.2 为 1 / 2 / 3 / 4。V8 的 Draft 不能照搬 V7 的增强流程。
  • V6 / V6.1 / Niji 6 使用 --sref random 时要求 --sv 4;Niji 7 不支持 --tile、--quality、--stop 或 --cref。
阿里云文档存在以下不一致,暂不作为稳定能力承诺:
  • Niji 的参数表称支持 --no,限制表称不支持。
  • Niji 6 的版本表给出 --iw 0–3,通用接口表给出 0–2;在确认前使用共同范围 0–2。
  • V6 的 --personalize 支持标记与“仅 V8.1 支持”的备注冲突;Niji 个性化参数缺少完整使用约束。
  • V8 参数表列出 Draft,但增强接口备注又称 V8.1 没有 Draft。当前应将 Draft 生成与 enhance 分开处理,不能据此调用增强接口。
存在差异的参数组合尚未确认兼容性,不建议用于依赖稳定行为的请求。

二次编辑示例

以下请求中的 <source_job_id> 替换为成功的来源任务 id。每次操作都会返回新的任务,再使用同一个查询接口等待结果。

各操作的请求体

下面给出完整字段组合。所有请求均为 POST /v1/tob/{operation},共用 Bearer 鉴权。
type=0 为强变化,type=1 为细微变化;可选 remixPrompt。
type=0 为标准高清,type=1 为创意高清。type=2 / 3 是 V5 任务的 2 倍 / 4 倍高清,不能任意用于其他版本的来源图。
direction:0 下、1 右、2 上、3 左;scale:1.1~3。可选 remixPrompt。
scale:1.1~2。可选 remixPrompt。扩图表示扩大画面视野,不保证输出像素尺寸按相同比例增加。
mask 使用坐标区域 areas 或蒙版图片 url。坐标示例见下一节,可选 remixPrompt。
mode 可省略,0 为强烈模式,1 为细微模式。
mask 可选。
来源任务需要为支持增强的 Draft 任务,例如 V7 Draft。

蒙版与画布参数

mask.areas 中每个区域包含参考尺寸 width、height,以及按 [x1, y1, x2, y2, ...] 排列的多边形坐标 points。以下示例选取 1024 × 1024 来源图的中间区域;请按实际图片尺寸调整坐标。
示例中的 example.com 地址只是占位符,使用前需替换为上游可访问的真实图片地址。imgUrl、参考图及蒙版 URL 不使用平台 Bearer Key 下载。

计费与错误处理

  • 提交时不扣费;成功且有图片结果后按任务计费,失败不扣费。
  • 一次任务即使返回多张图片,也按一次任务结算;不同操作、版本与模式的费用可能不同。
  • cost 是上游任务消耗信息,不是平台钱包流水或最终实付账单;最终实付以平台消费记录为准。
  • 客户端查询超时不会取消任务。拿到 id 后保留并继续查询;不要自动重复提交来代替查询。

正常返回与失败返回

以下均为结构示例,任务 ID、图片地址、时间与消耗值为占位值。所有提交操作共享任务响应结构;提交成功通常表示已受理,最终结果仍需查询。cost、seed、audits 可能缺省或因任务而不同。

提交成功:HTTP 200

排队等待:查询 HTTP 200

保存原任务 ID,继续轮询;不要因 urls 为空重新提交。

生成完成:查询 HTTP 200

urls 数量随操作和模式变化,不固定为四张。二次编辑的 imageNo 当前只接受 0–3,即使 Draft 返回更多图片,也不能直接提交下标 4 及以上。消费示例不构成价格承诺。

任务生成失败:查询仍为 HTTP 200

此例表示参考图片地址无效或下载超时。停止轮询,修正图片地址后再发起新任务。失败原因可能是英文标识或其他说明,客户端应以数字 status 判定终态,不要依赖 comment 固定文案。 HTTP 错误按 error 对象处理;查询 HTTP 200 本身不代表生成成功。

请求参数错误:HTTP 400

例如提交 callback(包括 null)会被拒绝:
例如查询不存在、已过期或属于其他 API Key 的任务:

请求并发受限:HTTP 429

降低同时执行的任务数量,等待已有任务结束后再提交。 错误对象还可能包含 details 与 trace_id,可用于定位问题。根据 HTTP 状态和 error.code 处理请求错误;根据任务 status 判断生成是否完成。已经获得任务 ID 时,查询暂时失败可继续查询原任务。 详细字段及可交互的响应示例可在侧栏「悠船 MJ 图片接口」中查看。

参考资料

本页已列出请求格式、版本参数、参数范围、功能兼容性和返回示例。以下为参数与版本能力的来源资料: