MJ Image API

使用 API Key 异步提交图片任务，再查询结果。图片结果返回 URL，不返回 Base64。提交成功只表示已受理，不表示图片已经可以下载。

文档核对日期：2026-11-14。请求契约以当前服务为准；上游模型、套餐和资源可用性仍可能变化。以下参数和功能“实测”主要指 2026-11-13 的生产接口验收，不是性能承诺或所有参数组合的穷举。

上游公开图片可能通过浏览器直接访问，但这不替代本服务下载接口的验收，也不能把服务 API Key 发送给第三方图片域名。此页只描述对外接入；未列入清单的路径、额外字段或任意动作类型不构成稳定公开承诺。

快速开始

1. 准备 API Key 和运行环境

联系服务提供方取得以 mj_live_ 开头的 API Key。保存在调用程序的环境变量中，不写入网页前端、URL 或公开仓库。本页示例 Key 全是占位值，执行前必须替换。

复制# Bash：后续 curl 示例使用 Bash 的换行和引号语法
export MJ_API_KEY='mj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# 安装 Python 示例所需依赖
python -m pip install requests

复制# PowerShell：设置环境变量；不要直接复制 Bash 的反斜杠换行
$env:MJ_API_KEY = 'mj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# 使用 curl 时可显式调用 curl.exe，避免旧版 PowerShell 的同名命令别名

2. 检查连接和读取权限

复制curl --fail-with-body {BASE}/health \
  -H "Authorization: Bearer $MJ_API_KEY"

复制{"service":"mj-lite-service","version":"0.2","ok":true,"accounts":1,"docs":"/docs"}

ok=true 说明这次服务请求和认证成功，不保证生成容量、上游登录状态、套餐能力或图片下载都正常。仅有 submit 权限的 Key 不能通过需要 read 的健康检查。

3. 提交任务

复制curl --fail-with-body -X POST {BASE}/api/submit \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"relaxed","action":{"t":"imagine","prompt":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2"}}'

收到 job_id 和 job.media_url 后，任务进入异步处理；提交接口不会等待图片完成。此请求会创建真实任务并使用上游资源，不要把网络超时后的重发当作安全重试。没有固定完成时间，设置合理的等待窗。

4. 查询图片结果

复制# 用真实响应中的 job.media_url 替换下方路径；建议每 10–20 秒查询一次
curl --fail-with-body {BASE}/api/media/ee4c507f-521a-4ce0-888c-16aa71df6f63 \
  -H "Authorization: Bearer $MJ_API_KEY"

当 archive_status=ready，整组图片的 URL 均已可用；处理中也可先下载 images 中 status=ready 的图片。详见结果字段与状态。不必先等 /api/gallery 列表出现，再来查询结果。

5. 使用返回的 URL 下载

复制# 替换为本次响应中的 images[0].download_url；这次请求不要附加 API Key
curl --fail-with-body 'https://images.example.com/result-0.png?token=replace-with-current-response' -o result-0.png

download_url 返回图片文件；thumb_url 和 preview_url 用于预览。URL 有有效期，到期后重新查询，使用新的完整 URL。

公开能力清单

“已产出”表示记录和结果图片均观察到；“可传”仅表示接口能表达该请求；“未测”不等于不支持。

认证与权限

复制Authorization: Bearer mj_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

认证方案名不区分大小写，示例统一使用 Bearer；它与 Key 之间保留一个空格。Key 本身区分大小写。请求头名称遵循 HTTP 的不区分大小写规则。

已记录归属的任务应只允许对应 Key 读取；历史未归属任务目前存在放行例外。不要把本页当作历史数据已严格隔离的证明。提交响应当前也可能带额外账号身份字段：不应依赖或继续传播这些字段，响应脱敏尚未统一。

配额、并发和数据大小

轮询建议从 10～20 秒间隔开始，并按 Key 的请求预算调整。例如每 5 秒轮询 10 分钟就约需 120 次请求，尚未计算提交和下载；每日上限较低时会先触发 429。不要为了等待结果反复提交同一任务。

任务生命周期、超时与重试

1. 提交未确认：请求超时或连接断开，不确定上游是否已经创建任务。不要立即重新 POST。
2. 已受理：HTTP 200 且有 job.job_id，只证明本次受理响应成功，不证明生成完成。
3. 列表可见：在 /api/jobs 或 /api/gallery 找到对应 ID，证明已有结果记录；仍需检查结果数量和图片可读性。
4. 图片已就绪：GET job.media_url 的 archive_status=ready 表示整组结果 URL 可用；处理中 images 中 status=ready 的图片可先下载。
5. 下载已验证：请求 download_url 成功，Content-Type 为图片且内容可解码，文件长度与 sha256 校验通过，才说明这次文件获取成功。
6. 观察窗内未确认：列表和队列都找不到任务时，状态仍可能未知。队列为 0 不等于成功，也不能据此编造 failed 或 completed。

上面的名称是接入方观察阶段，不是服务已实现的一组状态枚举。当前没有可靠的按任务 ID 查询终态、进度百分比、开始时间、完成时间或失败原因的独立公开接口；也没有 webhook / 回调。

建议对 GET 使用有限的等待窗；明确的认证和权限错误立即处理，429 按实际原因等待，短暂网络失败可在总截止时间内重试。不要把所有 403/404 都当成“稍后重试”。任务的外部观察耗时包含排队、生成、记录传播、图片就绪和轮询，不能当作纯 GPU 时间。

POST /api/submit：公共提交契约

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2"}}

复制{"ok":true,"job":{"job_id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","media_url":"/api/media/ee4c507f-521a-4ce0-888c-16aa71df6f63","job_type":"v8-2_diffusion","event_type":"diffusion","is_queued":false,"softban":false,"flags":{"mode":"relaxed","visibility":"public"},"meta":{"width":1344,"height":896,"batch_size":4,"parent_id":null,"parent_grid":null}},"attempts":[]}

快速 / 慢速适用与验证矩阵

下列所有动作都可在公共请求层传 mode="fast" 或 mode="relaxed"；能表达不等于上游一定接受或完成。套餐、模型、源任务和当前资源仍会约束实际执行。

八种动作与完整请求

公共规则：id 是源任务 ID；index 是源任务结果的零基索引，必须满足 0 ≤ index < 源结果张数。普通四张结果是 0、1、2、3，放大后只有一张时只能取 0。输入选一张、输出一张是两件不同的事，最终读取 batch_size 和资源数组长度。

1. imagine：生成

复制{"mode":"fast","action":{"t":"imagine","prompt":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2"}}

普通生成本轮输出四张；不同模型或后续动作的张数必须以实际结果为准。显式写版本更利于复现，省略版本时由上游当前默认决定，不承诺永久默认 v8.2。

2. upscale：细腻 / 创意放大

复制{"mode":"relaxed","action":{"t":"upscale","type":"v8r2_2x_subtle","id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

创意放大将 type 改为 v8r2_2x_creative。模型不匹配可能被上游拒绝，历史错误如 v7 2x upscale is not supported by this model。本轮两档均已产出，不代表所有模型枚举已经覆盖。

3. vary：变体

复制{"mode":"relaxed","action":{"t":"vary","strong":false,"v8_1_hd":null,"v8_2_hd":null,"id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

强烈变体只把 strong 改为 true。本轮每次输出四张新结果，继承和归一化后的参数应再查最终 full_command 或 command。

4. reroll：整组重绘

复制{"mode":"relaxed","action":{"t":"reroll","newPrompt":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2","id":"ee4c507f-521a-4ce0-888c-16aa71df6f63"}}

5. remix：改词重生

复制{"mode":"relaxed","action":{"t":"remix","strong":true,"newPrompt":"a copper teapot on a pale marble table --ar 3:2 --v 8.2","id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

本轮选一张源图后输出了四张新图。不要把“单张源输入”解释为“固定单张输出”。上游某些编辑结果可能限制后续 remix；本轮没有覆盖全部父任务类型。

6. outpaint：扩图 / 改画幅

复制{"mode":"relaxed","action":{"t":"outpaint","newPrompt":"a ceramic teapot on a wooden table --ar 9:16","zoomFactor":100,"id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

改画幅已产出：本轮 100 + --ar 9:16 得到 816×1456 的尺寸记录。尺寸会按模型约束调整，不保证像素比完全精确。

复制{"mode":"relaxed","action":{"t":"outpaint","newPrompt":"a ceramic teapot on a wooden table","zoomFactor":2,"id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

7. inpaint：区域重绘

先上传与源图对应的 PNG 遮罩取得 mask_url，再提交这个动作。两个请求都需要 submit 权限。不能把 Base64 直接当成 maskUrl。

复制{"mode":"relaxed","action":{"t":"inpaint","newPrompt":"replace the teapot with a copper kettle","maskUrl":"https://storage.example.com/replace-with-uploaded-mask.png","id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","index":0}}

示例 maskUrl 是占位地址，必须替换为真实上传响应，不能原样使用。本轮 v8.2 源图、1344×896 遮罩、慢速模式约 84.58 秒后观察到四张结果。旧的“此动作完全不可用”判断与这次结果不符；本轮只确认产出，未完整确认透明/颜色语义和区域保真。其他模型、快速模式和更多遮罩条件未测。

8. video：图生视频与延长

本轮未测视频。下面保留历史接入记录，并明确未验证的边界。不要把它与本轮图片验收混成一次全量通过。

复制{"mode":"fast","action":{"t":"video","videoType":"vid_1.1_i2v_480","stitch":null,"newPrompt":"--motion low","parentJob":{"job_id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","image_num":0},"animateMode":"auto"}}

复制{"mode":"fast","action":{"t":"video","videoType":"vid_1.1_i2v_extend_480","stitch":null,"newPrompt":"--motion high","parentJob":{"job_id":"ef5afc90-d951-48ae-92f1-a2c487d62914","image_num":0},"animateMode":"auto"}}

第二个示例的 parentJob 必须是真实源视频，不可照抄示例 UUID。历史 standard 套餐的 relaxed 视频被拒，原错误为 Relax mode for video is limited to Pro and Mega plans。完整当前套餐支持情况、延长次数和最长时长未重新确认。

视频的父任务已带图，不要再在 newPrompt 放图片 URL；历史错误为 Can't use an Image Prompt with a parent job。视频 turbo 的历史错误为 Turbo mode isn't supported for video jobs。首尾双帧、循环与额外视频张数未列为当前已验证能力。

提示词参数：范围、默认与证据

参数写在 prompt 或该动作的 newPrompt 内。不能同时用 --v 和 --niji。未指定的参数可能取上游默认或父任务参数，本服务没有为下表每个参数设固定默认。保留最终 command / full_command 来核对归一化结果。

完整模型列表与验证范围

表中“未测”不表示不支持。“历史”不是本轮重新验证；对完整合法值域尚未确认的参数，保留未知，不编造最大值。

组合、继承与不支持项

参考图：直接 URL 与上传后引用

支持直接传图片 URL，不必先转 Base64。只有本地文件、调用方内存图片或需要自行读取的受限图片，才先上传换短链。服务不提供“给 /api/upload 一个 url 并代下载”的能力。

本轮参考素材为测试物体图片，不代表已量化验收真人面部一致性。单图、多图的全量数量上限未确认；本页已测的是一张和两张，不保证任意张数。

直接 URL 的八组完整请求

以下 JSON 均发送到 POST /api/submit，带 Authorization 和 Content-Type。images.example.com 是示例域名，必须换成 MJ 能读取的真实图片地址。没有单独的 image_url 或 reference_urls 生成字段。

1. 单张垫图

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"https://images.example.com/reference.jpg a teapot in a sunlit studio --iw 1.5 --ar 3:2 --v 7"}}

2. 多张垫图

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"https://images.example.com/subject.jpg https://images.example.com/scene.jpg a collection of teapots on a shelf --iw 1.5 --v 7"}}

3. 单张风格参考

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"a paper lantern in a rainy alley --sref https://images.example.com/style.jpg --sw 200 --sv 6 --v 8.2"}}

4. 多张风格参考

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"a paper lantern in a rainy alley --sref https://images.example.com/style-a.jpg https://images.example.com/style-b.jpg --sw 200 --v 7"}}

5. v7 Omni 参考

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"a teapot displayed in a cozy cafe --oref https://images.example.com/character.jpg --ow 400 --v 7"}}

6. v6.1 角色参考

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"a ceramic teapot on a kitchen counter --cref https://images.example.com/character.jpg --cw 100 --v 6.1"}}

niji 6 写法是把 --v 6.1 换成 --niji 6，不能同时保留两种版本参数。

7. 垫图 + 风格 + Omni

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"https://images.example.com/composition.jpg a teapot in a cozy cafe --iw 1.5 --sref https://images.example.com/style.jpg --sw 200 --oref https://images.example.com/character.jpg --ow 400 --ar 3:2 --v 7"}}

8. v8.2 图片 + 指令式提示词

复制{"mode":"relaxed","action":{"t":"imagine","prompt":"https://images.example.com/reference.jpg make this into a watercolor painting --sref https://images.example.com/style.jpg --sw 200 --raw --v 8.2"}}

最后一例是 imagine 的图片输入与指令，并没有 --edit 参数或独立编辑模型字段。本轮有产出，但不从这个样本推断所有编辑模型的数量、宽高比继承或 remix 限制。

URL 要求与失败排查

POST /api/upload：图片上传

复制{"filename":"reference.png","file_b64":"iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7GkOtAAANV0lEQVR4nO3dP26kSxXGYQ+6ITmbQEhkE7MNCJ2xAK9hUiSyCWEF5KQ4Q0Lkkw6alAWgkZHvxfhf91dV36nzPk+ECFDP11XnV9Vt7A/fvn65ASDPz85+AQCcQwAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChfjj7BcAbfvnb3499Rv/88x89dLi5ufnw7esXD4JmI/4IeSCHAJA7699PFWhJAJhr04n/Oj2gBwFgvJZD/yViwL4EgDGihv5LxIC9CACHmPvPUgK2IABcyeh/kwxQnABwMaP/IjJAWQLABYz+q8kABQkA72L0DyEDlOJ3AfE2038UT5JS3AB4jYE1iasAFbgB8CLTfx7PlgoEACCUAPA8R9TZPGFOJwA8w2xaw3PmXAIAEEoAAEL5k5BZPn76fPZL4OJ35P7u1lNjBjcAgFACwDN+/qtfey4LeM6cSwB4ntk0myfM6QQAIJQA8CJH1Hk8WyrwU0C8Paf+/Y+/e0yjGP3U4QbA28ysUTxJSnED4F1cBQ4y+ilIALiADFzB6KcsAeBiMnDRg4KyBIArycCbDweKEwDGTDo/KWTusx0BYPyZNyoGDvvsSwAYr30MDH16EACWzspNe2Di05IAcP4kLVUFs54cAkD1mTs8D0Y8PBAAqjOvYRK/CwgglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEGqPAHz89PnslwDQzR4BuL+7/fjpswwAxAXgkQYAxAXg/u724T+4CgBkBeAJGQAICsDjJeCRT4QAIgLwLFcBgIgA/P8l4IGrAEDzALzeABkA6ByA18kAQOcAvHQJeOQqANAzAO/hKgDQMwBvXgIeyABAtwBcxCdCAK0C8M5LwANXAYA+Abi0Aa4CAH0CcAVXAYAmAbj0EvBABgC2D8ARUV8Oax7QMADXXQKixmLCvxFIDMBxvTPQ+J8GHNEkAEcuAb0HZct/FDDEh29fv9x0MWrYDclJBaZ/G23WJKUIQM8tZ/S3tPWapKAmHwHN2B77ztB9Xzmv884yVqsADLfjl8PbvWAu4v1loG4BmHFH3mjLbfRSuZp3mVG6BSD5KlD/FTKK95ohWn0JvGZ71PwizkQIVHMpspGeAUhrgOkfa8FSfHZ1VdsCXEcArldkD5j+4Wavw/cssCJ7gUu1/Q5gzcnI8IXHvWA7bKdtAJY5d9HbcpRaA0qwl7YfAa3fG+tvwaV2Pueat/yOLDMfDRXnBjDM4iuw6U/99eBzoeKaB6DrqbzmbudcZVeFDJTV/COgEzdGzSs57Q1feGPXmw+FSml+AziRMQ32RXERN4Bzx7HfUYolN3tfcB03gJ0+AHWroM062eJFtpcSgNOPG8eXuw1Ds9WyxYvsLSUAFfhZCLApSgkKwOmXgCMZcFai8ZrZ6KU2ExSAOg24dMXbHixYZufa6KV2khWAUnwiBE92hAeyWFwA6lwC3rno7QqmLrBS9nq1DcQFoCBXAfjpdvA0lkkMQLVLwCsZsBkYsrT2eozbveB9JQZgl6VvGzBjXUF6AGpeAh74RAgUa43QABRvgCMbVpQGLJAbAKA4DZgtOgDFLwEwlnnKEz88/S8AXj4nLa7Ix0+fHdTmSfl7AK9wLCLKwHm6bO9owCTRHwEBR9zf3RrNW3MD+M4lgCgzpvbsTaQ0M7gBfGdtQfHbgFPaDAIAceYNU2epvQjAf1m4UHwruQQMJwDAYI5TuxCAH1m15Nj0O1uXgLEEAJjCiao+Afgfliw5FpymbajiBADYqQE+BRpIAJ5yZoGx7KmyBOAZ1ishNj1Nb/qyCxIAYDqHqpoE4HnWK9CeAEC0TX+ls0+BhhCAF7kEAL0JALCIQ1U1AvAa6xVoTADeoAG0t/Lz9B3/IGVjAgAQSgDe5hIAtCQAwFJOVHUIwLtYskA/AgD4QjWUALyXSwBU4weBDhKAC2gA0IkAAKs5SxUhAJexcIE2BAAglABczCUA6EEAgO/8RE0gAbiGSwDQgABcSQOA3QkAQCgBuJ5LALA1AQAIJQCHuAQA+xIAgFACcJRLAFzK/+egCAEYQAOAHQkAsCtnr4MEYAwLEdiOAACEEoBhXALgPXwDXIcAnEAqgAoEYCSTHdiIAAymAbDm8x977TgBAAglAOM5mMCzfP1bjQCckweRoBprMpAATGEvwdTjvy02hAAAhBKAWZxQ4JFP/2sSgKUNUAWYsbO4jgAAczn+lyUAczmqEG749LenBhKA01jHtF+Nzv7FCcC6rWXiE8X0r08AgG2mv1PUWAKwglVLFGf/XQjAIhpAiHnT3yYaTgDOZEHTbB06++/lh7NfANDB7NHvtDSDAADVT/2m/yQCAFzJBz67+/Dt65ezX0M6u4gTXXq4Xr9cHf/ncQMA6h5QTP+p/BQQQCgBOJ8zDtaerXEKAQAqcjBaQACAckz/NQSgBMsdq471BACoxXloGQGowqLHerMRFhMAoArHoMUEACjB9F9PAAqxAYhdaQVfUgIBAE5m+p9FAGqxE4haY/d3t6VeTxoBAM5h9J9OAMqxK0hYXXVeSTK/DhpYyuivww2gIjuEruuqwmvgkRsAsILRX5AbQFF2C21WlB/1KcsNAJjFOaY4N4C6bB72XUtO/VtwAyjt/u723D/JTQMrp79Ty14EADjK3N+UAFTnEsDB9TPjAZr4PQgA8BqzvjFfAm/ADsTKYQYB2IMGYM0wnAAAhBKAbbgEYLUwlgDsRAOwThhIADajAVghjCIAAKEEYD8uAVgbDPHhb3/5w5j/Jdb63V//5ZHzU3/6zS88EC7iBrArux3rgYMEYGMagJXAEQKwNw3AGuBqAgAQSgC25wCYzLvPEQLQgSmQyfvOQQLQhFmQxjvOcQLQh4mQw3vNEALQirmQwLvMKALQjenQm/eXgQSgITOiK+8sY/mj8J0nhd8X1IbRzwxuAJ2ZGj14H5lEAJozO3bnHWQeAejPBNmX946pBCCCObIj7xqz+RI4ha+FN2L0s4YbQBaTpT7vEcsIQBzzpTLvDiv5CCiRj4MKMvpZzw0gl4lTh/eCU7gBRHMVOJ3Rz4ncADCDTmP6cy43AL5zFVjM6KcCAeBHMrCA0U8dPgLiKRNqHs+WUtwAeIarwHBGPwUJAC+SgSGMfsoSAN4gA1cz+ilOAHgXGbiI0c8WBIBr5po/Nvn684EtCADXcCF49oHAXgSA67kQmPtsTQAYIPBCYPTTgAAwZSa2jIGhTzMCwBSdPh0y9+lKAJhr02uBoU8CAWCd4jEw9EkjAFSZtouTYNyDAFDFSxP5YBgMeniJAFCdCQ6T+HsAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgFACABBKAABCCQBAKAEACCUAAKEEACCUAACEEgCAUAIAEEoAAEIJAEAoAQAIJQAAoQQAIJQAAIQSAIBQAgAQSgAAQgkAQCgBAAglAAChBAAglAAAhBIAgJtM/wGpb0ihJ8i01wAAAABJRU5ErkJggg=="}

上例包含完整测试素材，不是省略片段。将 JSON 作为请求体发送到 /api/upload；真实业务可替换为自己的 Base64，并遵守前述 18 MiB 建议上限。不要手工修改编码中间字符。

复制{"short_url":"https://s.mj.run/21IY3X09bSU","usage":{"image_prompt":"把 short_url 放在 prompt 最前面","style_ref":"在 prompt 末尾加 --sref https://s.mj.run/21IY3X09bSU","character_ref":"使用兼容版本的 --cref 或 --oref"}}

响应短链用于之后的提交，上传本身不创建生成任务。字段 usage 是帮助文案，不是必须照抄的完整提示词；上传返回的真实 short_url 优先于示例地址。

复制import base64
import os
import requests

BASE = "{BASE}"
with open("reference.png", "rb") as source:
    image_b64 = base64.b64encode(source.read()).decode("ascii")
response = requests.post(
    BASE + "/api/upload",
    headers={"Authorization": "Bearer " + os.environ["MJ_API_KEY"]},
    json={"filename": "reference.png", "file_b64": image_b64},
    timeout=60,
    allow_redirects=False,
)
if response.status_code != 200:
    raise RuntimeError("Upload failed: HTTP " + str(response.status_code) + " " + response.text[:300])
print(response.json()["short_url"])

POST /api/mask：上传区域遮罩

遮罩应与所选源图实际像素尺寸一致。本服务原样转发，不保证帮你缩放、反转或修正遮罩。当前没有已独立确认的完整颜色／透明度语义；推荐使用上游编辑器的有效遮罩或由接入方先验收。下面是本轮产出的同类演示：白色不透明底，中央矩形透明；不据此承诺透明处必然代表重绘或保留。

复制# 依赖：python -m pip install requests pillow
# 必须替换为你真实源任务的 ID、索引和实际尺寸
import base64
from io import BytesIO
import os
import requests
from PIL import Image, ImageDraw

BASE = "{BASE}"
JOB_ID = "ee4c507f-521a-4ce0-888c-16aa71df6f63"
IMAGE_NUM = 0
WIDTH, HEIGHT = 1344, 896
HEAD = {"Authorization": "Bearer " + os.environ["MJ_API_KEY"]}
mask = Image.new("RGBA", (WIDTH, HEIGHT), (255, 255, 255, 255))
ImageDraw.Draw(mask).rectangle(
    (WIDTH // 3, HEIGHT // 3, WIDTH * 2 // 3, HEIGHT * 2 // 3),
    fill=(255, 255, 255, 0),
)
stream = BytesIO()
mask.save(stream, "PNG")
upload = requests.post(
    BASE + "/api/mask", headers=HEAD, timeout=60, allow_redirects=False,
    json={"job_id": JOB_ID, "image_num": IMAGE_NUM,
          "mask_b64": base64.b64encode(stream.getvalue()).decode("ascii")},
)
if upload.status_code != 200:
    raise RuntimeError("Mask upload failed: HTTP " + str(upload.status_code))
mask_url = upload.json()["mask_url"]
created = requests.post(
    BASE + "/api/submit", headers=HEAD, timeout=60, allow_redirects=False,
    json={"mode": "relaxed", "action": {
        "t": "inpaint", "newPrompt": "replace the teapot with a copper kettle",
        "maskUrl": mask_url, "id": JOB_ID, "index": IMAGE_NUM,
    }},
)
if created.status_code != 200:
    raise RuntimeError("Inpaint submission failed: HTTP " + str(created.status_code))
print(created.json()["job"]["job_id"])

复制{"mask_url":"https://storage.example.com/uploaded-mask.png"}

响应可能含额外字段，接入只需要 mask_url。上面的返回地址也是形状示例，不是真实可用遮罩。本轮上传成功约 0.60 秒；不同模型、图片尺寸和遮罩语义不能仅凭这一次请求外推。

查询图片结果与下载 URL

生成结果以 URL 返回，不返回 Base64。提交任务后，使用响应中的 job.media_url 查询结果。新图片任务会自动准备结果，调用方不需要额外发起准备请求。

复制{"job_id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","archive_status":"processing","attempts":1,"error":null,"url_expires_at":1794582000,"images":[{"index":0,"status":"ready","content_type":"image/png","width":1344,"height":896,"bytes":1376205,"sha256":"replace-with-response-checksum","download_url":"https://images.example.com/result-0.png?token=replace-with-current-response","thumb_url":"https://images.example.com/result-0-small.webp?token=replace-with-current-response","preview_url":"https://images.example.com/result-0-large.webp?token=replace-with-current-response"},{"index":1,"status":"pending"},{"index":2,"status":"pending"},{"index":3,"status":"pending"}]}

这是响应形状示例，地址、校验值和时间都需以真实响应为准。上例第一张已可下载，其余仍在准备中；如果需要整组图片，等待 archive_status=ready。图片结果不包含 file_b64、image_base64 或其他 Base64 文件内容。

复制curl --fail-with-body -X POST {BASE}/api/media/ee4c507f-521a-4ce0-888c-16aa71df6f63/archive \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

历史任务需能在最近结果窗口找到，否则返回 404。只允许处理自己的任务，不允许通过猜测 ID 读取其他人的图片。已就绪的图片会保留；请求超时后先查询状态，不盲目重新提交生成任务。

当前图片结果准备支持每张不超过 64MiB。视频不适用这组图片结果流程，视频接入范围见单独小节。

GET /api/jobs：原始任务记录列表

复制{"data":[{"id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","job_type":"v8-2_diffusion","event_type":"diffusion","full_command":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2","batch_size":4,"width":1344,"height":896,"enqueue_time":"2026-11-13T14:44:20.115853+00:00","parent_id":null,"parent_grid":null}],"scoped_to_key":true}

列表可附加 media_archive，其字段与 /api/media/{jobId} 的独立响应相同，包含图片可用状态及 URL。新任务优先使用 job.media_url 查询，不依赖列表窗口。

此接口每次只查询一个来源的最近记录，不聚合所有生成来源；跨来源查结果优先使用 /api/gallery，并仍注意窗口限制。依赖字段限于示例中的任务身份、命令、类型、结果数量、尺寸和父任务关系。响应当前可能有额外上游字段，不将其全部提升为稳定公开契约，也不要传播额外身份信息。没有可靠的 completed_at、started_at 或终态错误字段，enqueue_time 不能替代 GPU 执行起止时间。

GET /api/gallery：作品卡片列表

复制{"items":[{"id":"ee4c507f-521a-4ce0-888c-16aa71df6f63","prompt":"a ceramic teapot on a wooden table","command":"a ceramic teapot on a wooden table --ar 3:2 --v 8.2","job_type":"v8-2_diffusion","event_type":"diffusion","is_video":false,"batch_size":4,"width":1344,"height":896,"enqueued_at":"2026-11-13T14:44:20.115853+00:00","thumbs":["/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/0?size=384","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/1?size=384","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/2?size=384","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/3?size=384"],"fulls":["/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/0?size=640","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/1?size=640","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/2?size=640","/api/thumb/ee4c507f-521a-4ce0-888c-16aa71df6f63/3?size=640"]}],"account_count":1,"accounts":[],"errors":[],"scoped_to_key":true}

卡片可附加 media_archive，包含 archive_status 与 images 中的结果 URL。新任务直接用 job.media_url 查询即可；历史任务未登记结果时可请求 /api/media/{jobId}/archive。原有 thumbs / fulls 路径就绪后返回 302 下载地址，未就绪返回 202 JSON，不能无条件保存为图片。

thumbs / fulls 是相对路径，调用程序需要拼接 API 基地址并带自己的 API Key。索引与数组顺序一致；不要固定循环四次。is_video 为 true 时是视频结果，封面路径的尺寸可用性需单独判断。

图片 URL、尺寸与下载

推荐从 /api/media/{jobId} 的 images 取得 URL：download_url 用于原始 PNG，thumb_url 与 preview_url 用于预览。查询接口返回 JSON 和 URL，不返回图片 Base64；对下载 URL 的请求才返回图片文件。

不要传任意数值期待动态缩放。size 描述图片规格；视频封面并非每个尺寸都有，本轮观察 640px 封面可读，部分 384px 封面返回 404。

复制# 查看响应的状态和 Location，不将 JSON 或跳转响应保存为图片
curl --fail-with-body -D - -o /dev/null "{BASE}/api/image/ee4c507f-521a-4ce0-888c-16aa71df6f63/0?size=original" \
  -H "Authorization: Bearer $MJ_API_KEY"

如果返回 302，用不带 API Key 的独立请求访问 Location；如果返回 202，按 JSON 状态继续查询。不要把 API Key 自动附加到返回的下载 URL。下载成功应为 HTTP 200 和正确的 Content-Type，保存文件后可用 bytes 与 sha256 验证完整性。

视频结果范围

视频当前不适用 /api/media 的图片结果流程，会显示 unsupported。历史已知的视频 URL 形状如下，需替换真实任务 ID 和有效序号；本轮没有重新验收视频生成或完整下载，不宣称它与图片流程具有相同保障。

复制https://cdn.midjourney.com/video/ee4c507f-521a-4ce0-888c-16aa71df6f63/0.mp4
https://cdn.midjourney.com/video/ee4c507f-521a-4ce0-888c-16aa71df6f63/0_640_N.webp?frame=last

访问这些地址也不要发送本服务 API Key。若返回 403，检查 URL 有效性与当前可用性并联系服务方，不假设所有 403 都能靠等待解决。

GET /api/credits：共享 GPU 额度快照

复制{"account_count":1,"relax_ms_total":-8481557,"fast_available_ms_total":44940000,"accounts":[{"plan":"standard","relax_ms":-8481557,"fast_available_ms":44940000}]}

数据是快照，当前可能缓存约 45 秒；任务完成后立即查询不保证计费已经最终结算。提交、列表查询和下载产生的 Key 请求次数与这些 GPU 毫秒不是同一指标。没有公开的单 Key 剩余次数查询，需联系服务方确认配置。

GET /api/queue：共享队列计数

复制{"running":2,"waiting":1,"account_count":1,"accounts":[]}

running / waiting 是计数，不是任务 ID 列表；快照可能有缓存。0 / 0 不能证明你的任务完成，也不能证明任务失败。不要用它计算单个任务精确排队时间或 GPU 时间。

GET /health：连通性检查

复制{"service":"mj-lite-service","version":"0.2","ok":true,"accounts":1,"docs":"/docs"}

错误、恢复与响应结构

先看 HTTP 状态，再检查 Content-Type。应用错误通常有字符串 error；hint、detail、attempts、retry_after 都可能缺省，不能假设每次同形。请求入口或其他上游失败还可能返回 HTML 或纯文本。

复制{"error":"请求没有 submit 权限","hint":"联系服务提供方确认权限"}

复制{"error":"图片获取失败 (403)","detail":null}

复制{"error":"图片请求太频繁","retry_after":60}

retry_after 是 JSON 里的秒数示例，不承诺所有错误都返回 HTTP Retry-After 头。当前没有稳定统一的机器错误 code 枚举，本页不虚构一组与实现不符的代码。

可运行的 Python 与 Node.js 示例

示例需要自己的 API Key，运行入口会真实提交任务，默认使用 relaxed。提交后直接按任务 ID 等待结果 URL，不需要先轮询作品列表；取得 URL 后用不含 API Key 的独立请求下载。结果为 URL，不含 Base64。失败会明确报错，不自动重发 POST。

Python 3.10+：requests

先安装 requests，设置 MJ_API_KEY，保存为 client.py。主流程为 submit → wait_for_result → download_image；wait_for_record 是按列表查看记录的可选辅助函数，不是获取结果 URL 的前置条件。

复制import os
import time
from pathlib import Path
import requests

BASE = "{BASE}"
KEY = os.environ.get("MJ_API_KEY", "").strip()
if not KEY:
    raise RuntimeError("Set MJ_API_KEY before running")
HEAD = {"Authorization": "Bearer " + KEY}


def api_request(method, path, body=None, timeout_seconds=30):
    response = requests.request(
        method, BASE + path, headers=HEAD, json=body,
        timeout=timeout_seconds, allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        try:
            message = response.json().get("error", response.text[:200])
        except ValueError:
            message = response.text[:200]
        raise RuntimeError("HTTP " + str(response.status_code) + ": " + str(message))
    return response


def submit(prompt, mode="relaxed"):
    response = api_request("POST", "/api/submit", {
        "mode": mode, "action": {"t": "imagine", "prompt": prompt},
    })
    return response.json()["job"]["job_id"]


def wait_for_record(job_id, timeout_seconds=600):
    deadline = time.monotonic() + timeout_seconds
    while True:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("Observation deadline reached; task completion is unknown: " + job_id)
        response = api_request("GET", "/api/gallery?page_size=60", timeout_seconds=min(20, remaining))
        for record in response.json().get("items", []):
            if record.get("id") == job_id:
                return record
        time.sleep(min(10, max(0, deadline - time.monotonic())))


def wait_for_result(job_id, timeout_seconds=600):
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        remaining = deadline - time.monotonic()
        payload = api_request("GET", "/api/media/" + job_id, timeout_seconds=max(0.1, min(20, remaining))).json()
        if payload["archive_status"] == "ready":
            return payload
        if payload["archive_status"] in ("failed", "unsupported"):
            raise RuntimeError("Result preparation failed: " + str(payload.get("error")))
        time.sleep(min(10, max(0, deadline - time.monotonic())))
    raise TimeoutError("Result observation deadline reached: " + job_id)


def download_image(job_id, index, path):
    manifest = api_request("GET", "/api/media/" + job_id).json()
    image = next((item for item in manifest["images"] if item["index"] == index and item["status"] == "ready"), None)
    if image is None:
        raise RuntimeError("Image result is not ready")
    # Do not send the service API Key to the returned download URL.
    response = requests.request("GET", image["download_url"], timeout=60, allow_redirects=False)
    if response.status_code != 200 or not response.headers.get("Content-Type", "").lower().startswith("image/"):
        raise RuntimeError("Image download failed: HTTP " + str(response.status_code))
    digest = __import__("hashlib").sha256(response.content).hexdigest()
    if len(response.content) != image["bytes"] or digest != image["sha256"]:
        raise RuntimeError("Image file integrity check failed")
    Path(path).write_bytes(response.content)
    return path


if __name__ == "__main__":
    job_id = submit("a ceramic teapot on a wooden table --ar 3:2 --v 8.2", mode="relaxed")
    print("Accepted:", job_id)
    result = wait_for_result(job_id)
    print("Result URLs ready:", len(result["images"]))
    download_image(job_id, 0, "out.png")
    print("Downloaded out.png")

Node.js 18+：内置 fetch，保存为 client.cjs

使用 CommonJS 的 .cjs 后缀运行 node client.cjs；不需要第三方请求库。每次请求使用 AbortSignal.timeout，总轮询也有截止时间。BASE 只在一处配置，不把模板变量混成错误 URL。

复制const { writeFileSync } = require("node:fs");
const BASE = "{BASE}";
const KEY = (process.env.MJ_API_KEY || "").trim();
if (!KEY) throw new Error("Set MJ_API_KEY before running");

async function apiRequest(method, path, body, timeoutMs = 20000) {
  const response = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: "Bearer " + KEY,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    redirect: "error",
    signal: AbortSignal.timeout(timeoutMs),
  });
  if (!response.ok) {
    const text = await response.text();
    let message = text.slice(0, 200);
    try { message = JSON.parse(text).error || message; } catch { }
    throw new Error("HTTP " + response.status + ": " + message);
  }
  return response;
}

async function submit(prompt, mode = "relaxed") {
  const response = await apiRequest("POST", "/api/submit", {
    mode, action: { t: "imagine", prompt },
  });
  return (await response.json()).job.job_id;
}

async function waitForRecord(jobId, timeoutMs = 600000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    const response = await apiRequest("GET", "/api/gallery?page_size=60", undefined, Math.max(1, Math.min(20000, remaining)));
    const data = await response.json();
    const found = (data.items || []).find(record => record.id === jobId);
    if (found) return found;
    await new Promise(resolve => setTimeout(resolve, Math.min(10000, Math.max(0, deadline - Date.now()))));
  }
  throw new Error("Observation deadline reached; task completion is unknown: " + jobId);
}

async function waitForResult(jobId, timeoutMs = 600000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const remaining = Math.max(1, Math.min(20000, deadline - Date.now()));
    const response = await apiRequest("GET", "/api/media/" + jobId, undefined, remaining);
    const manifest = await response.json();
    if (manifest.archive_status === "ready") return manifest;
    if (["failed", "unsupported"].includes(manifest.archive_status)) throw new Error("Result preparation failed: " + manifest.error);
    await new Promise(resolve => setTimeout(resolve, Math.min(10000, Math.max(0, deadline - Date.now()))));
  }
  throw new Error("Result observation deadline reached: " + jobId);
}

async function downloadImage(jobId, index, filename) {
  const manifest = await (await apiRequest("GET", "/api/media/" + jobId)).json();
  const image = manifest.images.find(item => item.index === index && item.status === "ready");
  if (!image) throw new Error("Image result is not ready");
  // Do not send the service API Key to the returned download URL.
  const response = await fetch(image.download_url, { signal: AbortSignal.timeout(60000), redirect: "error" });
  if (!response.ok || !(response.headers.get("content-type") || "").toLowerCase().startsWith("image/")) {
    throw new Error("Image download failed: HTTP " + response.status);
  }
  const bytes = new Uint8Array(await response.arrayBuffer());
  const digest = require("node:crypto").createHash("sha256").update(bytes).digest("hex");
  if (bytes.byteLength !== image.bytes || digest !== image.sha256) throw new Error("Image file integrity check failed");
  writeFileSync(filename, bytes);
  return filename;
}

async function run() {
  const jobId = await submit("a ceramic teapot on a wooden table --ar 3:2 --v 8.2", "relaxed");
  console.log("Accepted:", jobId);
  const result = await waitForResult(jobId);
  console.log("Result URLs ready:", result.images.length);
  await downloadImage(jobId, 0, "out.png");
  console.log("Downloaded out.png");
}

if (require.main === module) {
  run().catch(error => { console.error(error.message); process.exitCode = 1; });
}

常见问题与接入验收

快速模式是不是只有文生图？

不是，mode 是公共提交字段。但本轮快速模式只验证了普通文生图；其他动作的 fast 分支明确标为未单独实测，不把“可传”写成“已完成”。

为什么提交 200 后一直没有结果？

可能仍在处理、落到列表窗口外、上游未产出或状态无法查询。保存任务 ID、提交时间和响应，使用有限等待窗。队列 0 不构成成功证明；不要自动重新提交导致重复任务。

为什么图片 URL 返回 403，但 API Key 能查询结果？

查询权限和下载 URL 的有效性需分别检查。先重新查询结果，使用最新 download_url 再下载，且不要附加 API Key。如果最新 URL 仍被拒绝，保留任务 ID、时间和响应状态联系服务方，不反复提交生成任务。

结果是否返回 Base64？

不返回。生成结果通过 images 中的 download_url、thumb_url、preview_url 提供。参考图上传支持 file_b64，这是输入方式，不代表生成输出也是 Base64。

如何获取原始分辨率的图片？

使用 images 中已就绪结果的 download_url，按 content_type、width、height、bytes、sha256 核对文件。预览 URL 用于展示，不能代替原图。URL 失效后重新查询即可。

为什么新 Key 还能看到部分旧作品？

历史未归属任务当前放行，不符合严格隔离承诺。接入方应知悉此限制；有明确归属的新任务仍按 Key 判断。不能仅因 scoped_to_key=true 就推断所有历史数据已隔离。

如何知道还有多少调用次数？

/api/credits 给 GPU 毫秒，不给单 Key 剩余次数。每日次数、权限、到期时间联系服务方确认。轮询和取图也计数，UTC 00:00 重置。

批量生成怎么做？

当前没有公开的一次多任务事务或批量幂等接口。由调用方逐条提交并保存每个 job_id；先使用较低并发，按资源与请求预算调节，失败时不要盲重发全部。每个请求都是独立任务和独立结果。

这份文档是否宣称全部参数已实测？

没有。它覆盖当前列出的公开能力，并把已产出、历史记录、条件限制、未确认和当前异常分开。个人化成功路径、stealth 成功路径、视频新一轮生成、所有模型交叉参数、所有数值边界、人物一致性、区域保真都没有被本轮完整验收。

接入验收至少分别核对：认证、权限、受理 ID、实际参数、结果张数、资源可读、尺寸格式、超时恢复和数据范围。功能变更、上游版本或套餐变化后，相关状态需要重新确认，不能只靠文档存在某个参数就宣布可用。