Midjourney API 接入教程：任务提交、轮询与图片下载（2026）

Midjourney 没有官方公开 API，实际接入的对象通常是第三方封装服务。不同服务商的路径、字段和状态机并不统一，但底层流程接近：提交任务拿到 ID，轮询状态，成功后下载图片，再按需放大或生成变体。本文按这条链路讲，重点放在容易踩坑的差异和合规边界。

商标说明：Midjourney 是 Midjourney, Inc. 的商标；Discord 是 Discord Inc. 的商标。本文仅作技术说明，不代表任何合作、代理或认可关系。Midjourney 官方目前不提供 API，第三方接口的条款与稳定性需自行核验。

一、先选服务商，再写代码

Midjourney 第三方接口没有统一标准。同样是“提交任务”，有的返回 task_id，有的返回 job_id；有的用 /imagine，有的用 /v1/midjourney/imagine；有的把放大和变体做成独立任务，有的用动作接口。选型时先确认六件事：

鉴权方式与 Base URL 是否稳定，是否有版本化路径。
支持哪些任务类型：文生图、放大、变体、重绘、混合、描述。
状态字段与终态枚举，是否区分成功、失败、审核拒绝和超时。
结果保留时间与下载限制，是否支持回调。
并发、队列和限流规则，失败是否计费。
服务商存续与退出机制，是否支持短期合同和数据删除。

接口形态越接近你现有系统，迁移成本越低。不要只看演示效果，先看错误码文档和任务查询能力。

二、鉴权与请求约定

常见做法是 API Key 放在请求头，配合 JSON 请求体。具体头字段以服务商文档为准，常见形式包括 Authorization: Bearer、X-API-Key 或自定义头。把 Key、Base URL 和超时时间放进配置，不要散落在代码里。

调用前确认三件事：环境是测试还是生产、Key 是否绑定了 IP 或额度、请求是否经过公司出口代理。很多 401 和 403 不是 Key 错，而是环境配错或代理改写了请求头。

三、提交任务：prompt 与参数

一个典型提交请求如下，字段仅作示例：

export MJ_API_KEY="your-provider-key"
export MJ_BASE_URL="https://provider.example.com"

curl -sS -X POST "$MJ_BASE_URL/v1/midjourney/imagine" \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "minimalist product photo of a ceramic cup, soft window light --ar 4:3",
    "aspect_ratio": "4:3",
    "callback_url": "https://api.example.com/callbacks/mj"
  }'

提示词里的 --ar、--v、--style 等参数是否透传，各家支持程度不同。有的服务商把宽高比拆成独立字段，有的直接解析 prompt；不要假设参数一定生效，提交后用返回的任务详情核对。

提交成功后立即把任务 ID、业务单号、提示词、参数、提交时间和操作人写入任务表。后面的轮询、重试、对账和费用归集都依赖这条记录。

四、轮询：状态机与退避

状态	含义	处理建议
queued	排队中	继续等待，避免重复提交
running	生成中	按退避策略轮询
succeeded	成功	读取结果并立即转存
failed	失败	记录错误码，判断是否可重试
moderated	审核拒绝	修改提示词，不要原样重试
expired	超时或链接过期	查任务详情，必要时重提

轮询从 3 到 5 秒起步，逐步退避到 15 到 30 秒，并设置总超时。不要固定一秒一次，也不要多个实例同时查同一个任务。任务进入终态后停止轮询，把最终状态和结果地址落库。

如果服务商支持 Webhook，可以作为主通知，但必须验签、做幂等，并保留定时轮询兜底。回调丢失在封装服务里并不少见。

五、下载与转存

任务成功后返回的图片地址通常有时效，可能是几分钟到几天，也可能是临时签名 URL。不要把它直接写进前端页面或交付给客户。

正确顺序是：收到成功状态后立即下载，转存到自己的对象存储，记录任务 ID、对象路径、文件大小、校验值和下载时间，再把内部地址写入业务库。下载要设置超时、重试和并发上限；大图建议走服务端代理，避免浏览器跨域和链接泄露。

Midjourney 一次通常返回四宫格，外加放大后的单图。转存时把网格图和放大图分开命名，保留原始任务 ID，后续做变体或重绘时才能对应上。

六、放大、变体与重绘

放大和变体通常依赖原任务 ID 和图片序号。常见调用方式是提交一个新任务，带上 task_id 和 index，或者调用服务商的动作接口。不同服务商的序号从 1 开始还是从 0 开始并不统一，接入前用一条测试任务确认。

几个实践建议：

把“原图任务”和“派生任务”用父子关系记录，避免重复放大同一张图。
变体可能产生新的四宫格，费用按新任务计算，批量前先估算。
重绘、局部重绘和混合功能并非所有服务商都支持，以文档为准。
放大后的图片仍可能受上游链接有效期限制，成功后立即转存。

七、限流、并发与成本

封装服务的吞吐取决于账号池和上游队列，不等于你买了多少并发就能跑多少。常见限制包括每分钟任务数、同时运行任务数、单账号每日额度。遇到 429 要降低并发并指数退避，不要无脑重试。

成本按“成功交付的图片”核算，而不是按提交次数。把失败、审核拒绝、重复提交和放大变体都计入分母，才能得到真实的单张成本。先跑小批量，确认成功率和平均耗时，再逐步放量。

八、常见错误与排查

401：Key 缺失、格式错误、环境不匹配，或上游账号失效。
403：IP 不在白名单、额度不足、权限未开通。
404：路径或任务 ID 错误，也可能任务已被清理。
429：触发限流，降低并发并退避。
5xx：上游或封装层故障，按幂等键确认未创建再重试。
任务 failed：看错误码，区分参数、审核和上游失败。
链接 403/404：结果地址过期或需要鉴权，回到任务详情重新获取。

把请求 ID、任务 ID、错误码和脱敏后的参数记入日志。封装服务的错误信息经常被二次包装，保留原始响应能显著缩短排查时间。

九、迁移检查清单

从一个服务商迁到另一个，或从自建代理迁到托管服务，按下面清单逐项确认：

Base URL、鉴权头和请求路径是否整套替换。
任务 ID 字段名、状态枚举和终态判断是否一致。
prompt 参数是透传还是拆成字段，--ar、--v 是否生效。
放大、变体和重绘的调用方式与序号规则是否一致。
结果链接有效期、下载限制和转存逻辑是否验证。
回调是否支持，验签和幂等是否完成。
限流、并发、超时和重试是否重新压测。
计费口径、失败退费和账单对账是否能对上。

迁移后先跑一批真实业务样本，对比成功率、平均耗时和单张成本，再切全量。没有对账和回滚方案时，不要一次性切换。

常见问题

Midjourney API 是同步返回图片吗？

通常不是。提交任务只返回任务 ID，需要轮询或等待回调，成功后再下载图片。按同步接口设计容易超时和重复提交。

任务一般要轮询多久？

取决于队列和上游负载，从几十秒到几分钟都常见。建议 3 到 5 秒起步、逐步退避，并设置总超时，超时后查任务详情而不是直接重提。

图片链接能保存多久？

各服务商差异很大，可能是几分钟、几小时或几天。生产环境不要依赖上游链接，成功后立即转存到自己的对象存储。

放大和变体怎么调用？

一般需要原任务 ID 加图片序号，再提交一个派生任务或调用动作接口。序号起点和字段名各家不同，先用一条测试任务确认。

国内团队接入要注意什么？

先确认网络可达性、数据出境和内容合规，再评估服务商条款与停服风险。需要统一入口时，可在中商起航 AI 网关注册，并在模型价格页核对当前支持的模型；不要把非 OpenAI 协议的图片接口直接当成兼容接口。

下一步

先用一条低复杂度提示词跑通“提交、轮询、下载、转存”四步，再补放大、变体和回调。选服务商时把合规和退出机制放在效果之前。需要统一管理多个模型入口，可以在中商起航 AI 网关注册，并在模型价格页确认可用模型与计费方式。