Midjourney 绘图
用 Midjourney Proxy 协议格式生成与操作绘图任务——提交、放大变换、图生文、任务查询与轮询状态机。
Midjourney 绘图接入的是社区通行的 Midjourney Proxy 协议格式 (novicezk/midjourney-proxy 项目定义的接口契约)。 与积木的视频生成同属异步任务模型:提交请求只拿回任务 ID, 需要轮询任务状态,完成后再取图片。不要期望提交接口同步返回图片。
端点总览
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /mj/submit/imagine | 文生图 |
POST | /mj/submit/describe | 图生文(按图片反推提示词) |
POST | /mj/submit/blend | 多图混合 |
POST | /mj/submit/edits | 图像编辑 |
POST | /mj/submit/video | 图生视频 |
POST | /mj/submit/change | 放大 / 变换(U/V 系列操作) |
POST | /mj/submit/simple-change | 放大 / 变换的简化调用(用 content 编码指令) |
POST | /mj/submit/shorten | 缩短提示词(Plus 专属) |
POST | /mj/submit/modal | 提交局部重绘等弹窗式操作的后续参数 |
POST | /mj/submit/action | Plus 客户端的按钮回调统一入口 |
POST | /mj/submit/upload-discord-images | 上传参考图到任务存储(Plus 专属) |
POST | /mj/insight-face/swap | 换脸 |
GET | /mj/task/{id}/fetch | 查询单个任务 |
POST | /mj/task/list-by-condition | 按任务 ID 数组批量查询 |
GET | /mj/task/{id}/image-seed | 查询任务的绘图种子(seed) |
GET | /mj/image/{id} | 转发下载任务生成的图片 |
{mode} 段访问,如 /fast/mj/submit/imagine、
/turbo/mj/submit/imagine——{mode} 段不改变行为,仅用于部分客户端按速度档路由,可忽略。鉴权见 鉴权与令牌(Authorization: Bearer <令牌>)。
本组接口的错误响应不是标准的任务错误信封,也不是模型接口的 error 对象,而是 Midjourney Proxy
自有的结构(见下文「错误响应」)。
第一步:提交任务
以最常用的文生图为例:
/mj/submit/imaginepromptstring必填绘图提示词,留空返回错误码 4(prompt_is_required)
base64Arraystring[]参考图的 Base64 数组(图生图 / 垂直参考等场景)
notifyHookstring任务状态变更时的回调地址(需管理员在运营设置中开启回调功能才会实际触发)
statestring自定义状态标识,原样回传,不参与业务逻辑
botTypestring机器人类型标识,多数部署可忽略,留空使用默认值
其余端点的核心参数:
/mj/submit/describe:base64Array传入一张图(Base64),返回反推出的提示词/mj/submit/blend:base64Array传入 2–5 张图(Base64),混合出新图/mj/submit/change:taskId(必填,指向原任务)、action(必填,如UPSCALE/VARIATION/REROLL)、index(必填,操作第几张,从 1 开始)/mj/submit/simple-change:content(必填,编码格式如<任务ID> <操作代号>,服务端自动解析出taskId/action)/mj/insight-face/swap:请求体为{"sourceBase64": "...", "targetBase64": "..."},两者均为 Base64 编码图片,均必填
提交响应
{
"code": 1,
"description": "提交成功",
"result": "0741798445574458",
"properties": null
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码,见下表 |
description | string | 人类可读描述 |
result | string | 任务 ID(code=1 时),拿去轮询用 |
properties | object | null | 附加信息,因 code 不同而异 |
code 常见取值:
code | 含义 |
|---|---|
1 | 提交成功 |
21 | 任务已存在(重复提交,result 与 properties 直接给出已有任务的结果) |
22 | 排队中,前面还有任务(properties.numberOfQueues 给出排队数) |
23 | 队列已满,请稍后再试 |
24 | 提示词命中敏感词(properties.bannedWord 给出触发词) |
4 | 请求参数错误(如缺 prompt/taskId),见 description |
30 | 当前负载已饱和(HTTP 429),建议退避重试或升级套餐 |
/mj/submit/change 等)依赖原任务所在的具体渠道:
若原任务所属渠道已被禁用,本次提交会直接失败(该任务所属渠道已被禁用),且无法切换到其他渠道重试。第二步:轮询任务状态
查询单个任务
/mj/task/{id}/fetch任务不存在时返回 {"code": 4, "description": "task_no_found"}。
批量查询
/mj/task/list-by-conditionidsstring[]要查询的任务 ID 数组;为空或未匹配到任何任务时返回空数组 []
任务对象字段
idstring任务 ID
actionstring任务动作,如 IMAGINE、UPSCALE、VARIATION、DESCRIBE、BLEND 等
statusstring内部状态枚举,见下表
prompt / promptEnstring原始提示词 / 翻译为英文后的提示词(部分部署可能为空)
progressstring带百分号的字符串(如 "30%"),完成为 "100%"
imageUrlstring图片地址。开启转发(见下文「取回图片」)时为积木域名下的代理地址,否则为上游原始地址
videoUrl / videoUrlsstring / array图生视频任务的视频地址(单个 / 多个)
failReasonstring失败原因,仅失败时非空
buttonsarray可执行的后续操作按钮列表(放大/变换等),元素含 customId/label/type
submitTime / startTime / finishTimeint64提交 / 开始 / 完成时间戳(Unix 毫秒),未发生时为 0
status 值 | 含义 |
|---|---|
| (空字符串) | 已创建,尚未提交上游 |
SUBMITTED | 已提交上游 |
IN_PROGRESS | 生成中 |
SUCCESS | 生成成功(终态) |
FAILURE | 生成失败(终态),原因见 failReason |
任务状态由渠道端的回调(若开启)或平台的后台补偿更新,轮询建议间隔 5–10 秒。
查询绘图种子
/mj/task/{id}/image-seed返回该任务绘图使用的随机种子(seed),可用于复现或微调同一张图的变体。任务所属渠道已禁用时返回错误。
取回图片
/mj/image/{id}{id} 为 Midjourney 任务 ID(不是普通任务查询接口的 task_id)。此接口转发下载上游图片,
返回图片二进制流(Content-Type 取自上游响应,默认 image/jpeg)。
是否启用此转发由平台配置决定:启用时,任务对象里的 imageUrl 会指向本接口
(https://api.jimu.chat/mj/image/{id}),未完成的任务额外带随机查询参数防止缓存;
未启用时 imageUrl 直接是上游原始地址,无需经过本接口。
错误响应
提交类接口失败时返回:
{
"description": "prompt_is_required",
"type": "upstream_error",
"code": 4
}
触发上游限流时返回 HTTP 429,code 为 30,description 固定提示负载已饱和。
这套错误结构只用于本组端点,与错误处理与请求追踪中
描述的三种通用形态均不同,接入时需单独处理。
请求示例
# 提交文生图任务
TASK_ID=$(curl -s https://api.jimu.chat/mj/submit/imagine \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JIMU_API_KEY" \
-d '{"prompt":"a cat running on the grass, cinematic lighting"}' \
| python -c "import sys,json;print(json.load(sys.stdin)['result'])")
# 轮询(每 5 秒一次)
while true; do
STATUS=$(curl -s "https://api.jimu.chat/mj/task/$TASK_ID/fetch" \
-H "Authorization: Bearer $JIMU_API_KEY" \
| python -c "import sys,json;print(json.load(sys.stdin)['status'])")
echo "status=$STATUS"
[ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILURE" ] && break
sleep 5
done
# 下载图片(imageUrl 由任务对象给出,此处假设已启用转发)
curl -L "https://api.jimu.chat/mj/image/$TASK_ID" \
-H "Authorization: Bearer $JIMU_API_KEY" -o result.jpg