Appearance
Midjourney 接入与图片接口
接入说明
Midjourney 使用异步任务流程:提交请求,读取 result 中的任务 ID,再查询到 SUCCESS 或 FAILURE。图片上传是例外,成功响应的 result 为图片 URL 数组,不是任务 ID。
完整型号见 Midjourney 模型目录,视频生成见 视频接口。本文采用 MJ 专用 JSON 接口,请求体不传 model。
| 模式 | 服务地址 | 示例 |
|---|---|---|
| Fast | https://iliu.ai/fast | POST https://iliu.ai/fast/mj/submit/imagine |
| Relax | https://iliu.ai/relax | POST https://iliu.ai/relax/mj/submit/imagine |
下文使用完整 URL,不需要追加 /v1。切换模式时仅在支持该模式的接口中替换 /fast/ 或 /relax/;后续任务操作保持原任务的访问上下文。模式与最终费用以账户记录为准,不靠 state 或模型名字符串选择。
http
Authorization: Bearer <API_KEY>
Content-Type: application/jsonGET 查询也携带 Authorization,无须请求体。Apifox 中 POST 的 Body 选择 JSON。所有带尖括号的值均为占位符,必须替换;不要直接运行旧任务 ID 或自行拼接按钮标识。
可选通用字段:state 为业务追踪字符串,不是幂等键;notifyHook 为服务端可访问的 HTTPS 回调地址。最小示例省略这两个字段,也不填写账号筛选条件。
文生图与参考图生成
1. 功能介绍
根据提示词生成图片;需要图片参考时增加 base64Array。对应 mj_fast_imagine、mj_relax_imagine。
http
POST https://iliu.ai/fast/mj/submit/imagine2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 提示词;可包含 --ar 16:9 等参数 |
base64Array | string[] | 否 | 参考图片的完整 Data URL 数组 |
state | string | 否 | 业务追踪标识 |
notifyHook | string | 否 | HTTPS 回调地址 |
版本参数与按钮能力以服务实际支持及任务返回为准。不预设所有版本都支持相同放大动作,不在最小请求中填写 mode 或 accountFilter。
3. 请求示例
json
{
"prompt": "一个红苹果,白色背景,产品摄影 --ar 16:9"
}参考图示例:
json
{
"prompt": "保留参考图主体,将背景改为白色 --ar 16:9",
"base64Array": ["data:image/png;base64,<IMAGE_BASE64>"]
}4. 返回响应
json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": "<IMAGINE_TASK_ID>"
}code=1 表示提交成功,code=22 表示排队中;有有效任务 ID 时继续查询,不重复提交。result 按字符串保存。
5. 后续步骤
查询新任务;成功后获取 imageUrl 和 buttons。四宫格中的 U1、U2、U3、U4 分别选择左上、右上、左下、右下图片;V1–V4 为对应图片的变体按钮。
图片上传
1. 功能介绍
上传图片并获得图片 URL,对应 mj_fast_upload、mj_relax_upload。
http
POST https://iliu.ai/fast/mj/submit/upload-discord-images2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
base64Array | string[] | 是 | 至少一张图片的完整 Data URL;格式、大小与数量限制以接口实际返回为准 |
PNG 使用 data:image/png;base64,,JPEG 使用 data:image/jpeg;base64,。Base64 内容来自图片文件,不是本地路径或图片网址;此请求使用 JSON,不使用 multipart/form-data。
3. 请求示例
json
{
"base64Array": ["data:image/png;base64,<IMAGE_BASE64>"]
}Windows PowerShell 生成 Data URL 的方式:
powershell
$imageBytes = [IO.File]::ReadAllBytes('C:\images\apple.png')
$imageData = 'data:image/png;base64,' + [Convert]::ToBase64String($imageBytes)
$requestBody = @{ base64Array = @($imageData) } | ConvertTo-Json -Compress4. 返回响应
json
{
"code": 1,
"description": "提交成功",
"result": ["https://example.com/uploaded-image.png"]
}URL 为结构示例。成功后使用实际 result 数组中的地址;不要将它当作任务 ID 轮询。
5. 后续步骤
上传获得图片地址不等于生成 MJ 任务,也不会产生 customId。需要变体时先通过 Imagine 创建任务,再从该任务查询按钮。仅做参考图生成时可以直接向 Imagine 传 base64Array,无需预先上传。
图片融合
1. 功能介绍
将多张图片融合为新图,对应当前目录中的 mj_relax_blend。
http
POST https://iliu.ai/relax/mj/submit/blend2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
base64Array | string[] | 是 | 2–5 张图片的完整 Data URL |
dimensions | string | 否 | PORTRAIT、SQUARE、LANDSCAPE;分别为 2:3、1:1、3:2 |
state | string | 否 | 业务追踪标识 |
notifyHook | string | 否 | HTTPS 回调地址 |
3. 请求示例
json
{
"base64Array": [
"data:image/png;base64,<IMAGE_1_BASE64>",
"data:image/png;base64,<IMAGE_2_BASE64>"
],
"dimensions": "SQUARE"
}4. 返回响应
返回通用提交响应,result 为任务 ID。使用 Relax 查询地址等待完成,成功后读取 imageUrl。
图片描述
1. 功能介绍
根据图片生成文字描述,对应 mj_fast_describe。
http
POST https://iliu.ai/fast/mj/submit/describe2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
base64 | string | 是 | 单张图片的完整 Data URL,字段名不是 base64Array |
state | string | 否 | 业务追踪标识 |
notifyHook | string | 否 | HTTPS 回调地址 |
3. 请求示例
json
{
"base64": "data:image/png;base64,<IMAGE_BASE64>"
}4. 返回响应
提交后从 result 取得任务 ID 并查询。描述任务的文字结果及可执行按钮以实际响应为准,不要求必须出现非空 imageUrl。
提示词分析
1. 功能介绍
分析和精简提示词,对应 mj_relax_shorten。
http
POST https://iliu.ai/relax/mj/submit/shorten2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 需要分析的提示词 |
state | string | 否 | 业务追踪标识 |
notifyHook | string | 否 | HTTPS 回调地址 |
3. 请求示例
json
{
"prompt": "a highly detailed photograph of a red apple on a white table, studio lighting"
}4. 返回响应
返回通用提交响应,随后查询 result 对应任务。文字分析结果按实际响应读取,不将它按图片下载任务处理。
按钮动作
1. 功能介绍
选图、放大、变体、重新生成、平移和扩图共用 Action 接口。具体操作由任务返回的按钮决定。
http
POST https://iliu.ai/fast/mj/submit/actionRelax 使用 https://iliu.ai/relax/mj/submit/action。对应型号和模式见 模型目录。
2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 产生该按钮的任务 ID |
customId | string | 是 | 该任务 buttons 中的完整 customId,原样复制 |
state | string | 否 | 业务追踪标识,不影响模式与动作 |
notifyHook | string | 否 | HTTPS 回调地址 |
3. 请求示例
json
{
"taskId": "<TASK_ID>",
"customId": "<BUTTON_CUSTOM_ID>"
}<BUTTON_CUSTOM_ID> 必须替换为下表目标按钮的实际标识。表中的片段仅用于识别按钮,不是可提交的完整值。
| 操作 | 选择的按钮 | customId 中的常见片段 | 前置条件 |
|---|---|---|---|
| 选图 | U1–U4 | ::upsample:: | 成功的四宫格任务 |
| 普通变体 | V1–V4 / Make Variations | ::variation:: | 任务实际返回该按钮 |
| 强变体 | Vary (Strong) | ::high_variation:: | 单图任务返回强变体按钮 |
| 弱变体 | Vary (Subtle) | ::low_variation:: | 单图任务返回弱变体按钮 |
| 2x 放大 | Upscale (2x) | ::upsample_v5_2x:: 等 | 必须使用实际返回的 2x 按钮 |
| 4x 放大 | Upscale (4x) | ::upsample_v5_4x:: 等 | 必须使用实际返回的 4x 按钮 |
| V7 细节放大 | Upscale (Subtle) / Upscale (Creative) | ::upsample_v7_2x_subtle:: / ::upsample_v7_2x_creative:: | 这两种按钮已在 V7 单图结果中出现 |
| 重新生成 | Reroll / 重抽图标 | ::reroll:: | 从 buttons 选择,不依赖 label 非空 |
| 方向扩图 | 方向箭头 | ::pan_left::、::pan_right::、::pan_up::、::pan_down:: | 单图任务返回方向按钮 |
| 扩大视野 | Zoom Out 2x / 1.5x | ::Outpaint:: | 扩展画面范围,不是分辨率放大 |
| 自定义扩图 | Custom Zoom | ::CustomZoom:: | 按响应提示继续提交 Modal |
| 局部重绘 | Vary (Region) | ::Inpaint:: | 按响应提示继续提交蒙版 |
不要把 variation 改成 high_variation,不要将按钮中的版本片段替换成提示词版本。不同版本提供的按钮可能不同;没有 4x 按钮时不能自行构造 4x 请求。
4. 返回响应
通常返回通用提交响应和新的 result 任务 ID;后续查询该新 ID。需要补充参数的操作应依据响应中的任务信息继续 Modal,不能仅凭一个业务码判断。
5. 调用记录
强变体请求可能在日志中显示 mj_high_variation,选图及放大可能显示 mj_upscale。日志名称不等于请求需要填写的 model 字段,也不能据此断定放大倍率。发生模型不可用错误时,应开通错误消息中提示的模型与分组权限。
局部重绘与补充参数
1. 功能介绍
Modal 用于提交局部重绘或自定义扩图需要的补充参数,对应 mj_fast_modal、mj_relax_modal。先选择 Vary (Region) 或 Custom Zoom 按钮,再使用响应中要求继续处理的任务 ID。
http
POST https://iliu.ai/fast/mj/submit/modal2. 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 需要补充参数的任务 ID,不固定等于最初的 Imagine ID |
prompt | string | 按任务要求 | 补充提示词;自定义缩放参数以任务要求为准 |
maskBase64 | string | 按任务要求 | 局部重绘蒙版 Data URL;不要将普通参考图当作蒙版 |
蒙版尺寸与遮罩规则需满足该任务要求;不要假定与其他图像编辑接口的黑白或透明规则一致。
3. 请求示例
局部重绘参数结构:
json
{
"taskId": "<MODAL_TASK_ID>",
"prompt": "将选中区域改为绿色叶片",
"maskBase64": "data:image/png;base64,<MASK_BASE64>"
}自定义扩图参数结构:
json
{
"taskId": "<MODAL_TASK_ID>",
"prompt": "<PROMPT_WITH_SUPPORTED_ZOOM_PARAMETERS>"
}4. 返回响应
提交后读取 result,查询返回的任务 ID。单独添加 maskBase64 到 Imagine 请求不能替代此流程。不要将所有 code=21 响应解释为需要提交 Modal,应结合 description、任务状态和具体操作判断。
查询任务
1. 功能介绍
查询任务状态、结果和可执行按钮。所有异步提交和按钮动作均使用此接口。
http
GET https://iliu.ai/fast/mj/task/{id}/fetchRelax 使用 https://iliu.ai/relax/mj/task/{id}/fetch。鉴权与创建任务保持一致,不发送请求体。
2. 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | 最近一次提交响应中的任务 ID |
3. 请求示例
bash
curl 'https://iliu.ai/fast/mj/task/<TASK_ID>/fetch' \
-H "Authorization: Bearer $API_KEY"4. 返回响应
以下仅为结构示例,任务 ID、URL 和按钮均需从实际响应读取。
json
{
"id": "<TASK_ID>",
"action": "UPSCALE",
"status": "SUCCESS",
"progress": "100%",
"imageUrl": "https://example.com/result.png",
"videoUrl": "",
"videoUrls": null,
"failReason": "",
"buttons": [
{
"customId": "<ACTUAL_HIGH_VARIATION_CUSTOM_ID>",
"label": "Vary (Strong)",
"emoji": "",
"type": 2,
"style": 2
}
]
}| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 当前任务 ID |
action | string | 如 IMAGINE、UPSCALE、HIGH_VARIATION |
status | string | 任务状态,以此判断成功与失败 |
progress | string | 如 45%、100%;失败任务也可能显示 100% |
imageUrl | string | 图片地址,任务失败或非图片任务时可为空 |
videoUrl | string | 视频地址,可为空 |
videoUrls | array / null | 多视频结果;元素结构以实际响应为准 |
failReason | string | 失败原因 |
buttons | array | 可继续操作的按钮,可为空 |
buttons[].customId | string | Action 请求中必须原样使用的按钮标识 |
state | string | 提交时的业务追踪字段 |
properties | object | 任务附加信息 |
5. 状态处理
| status | 处理方式 |
|---|---|
NOT_START / SUBMITTED / IN_PROGRESS | 等待并继续查询 |
SUCCESS | 停止轮询,根据任务类型读取结果 |
FAILURE | 停止轮询,读取 failReason |
MODAL | 根据任务要求提交补充参数 |
CANCEL / CANCELED / CANCELLED(如返回) | 停止轮询,按取消处理 |
建议每 3–5 秒查询一次,并设置总等待时间。未知状态应保留原始响应并在超时后停止,不无限轮询。查询失败可以有限重试;提交请求超时后先核查任务记录,避免重复生成。
完整调用示例
1. 生成、选图与强变体
- 提交 Imagine,保存返回的
result为四宫格任务 ID。 - 查询到 SUCCESS,在
buttons中选择 U1;将该任务的id和 U1 的customId一起提交 Action。 - 查询 Action 返回的新任务 ID,等待单图 SUCCESS。
- 从单图的
buttons中找到 Vary (Strong),使用单图的id和该按钮的完整customId再次提交 Action。 - 查询最后返回的新任务 ID,成功后读取结果图片。
弱变体将第 4 步目标改为 Vary (Subtle);放大则选择单图实际提供的 Upscale 按钮。U1 选图不代表完成了 2x 或 4x 分辨率放大。
2. Python 自动读取按钮
以下脚本会实际提交三个任务,产生对应费用。运行前安装 requests,设置 ILIU_API_KEY。请求体不使用固定的历史任务 ID。
python
import os
import time
import requests
BASE_URL = "https://iliu.ai/fast"
session = requests.Session()
session.headers.update({"Authorization": "Bearer " + os.environ["ILIU_API_KEY"]})
def read_response(response):
response.raise_for_status()
data = response.json()
if not isinstance(data, dict) or data.get("error"):
raise RuntimeError(data)
return data
def submit(path, body):
data = read_response(session.post(BASE_URL + path, json=body, timeout=60))
task_id = data.get("result")
if data.get("code") not in (1, 22) or not isinstance(task_id, str) or not task_id:
raise RuntimeError(data)
return task_id
def wait_task(task_id, max_wait=600):
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
data = read_response(session.get(
BASE_URL + "/mj/task/" + task_id + "/fetch", timeout=30))
status = data.get("status")
if status == "SUCCESS":
if data.get("id") != task_id:
raise RuntimeError("查询结果的任务 ID 不匹配")
return data
if status in ("FAILURE", "CANCEL", "CANCELED", "CANCELLED"):
raise RuntimeError(data.get("failReason") or data)
if status == "MODAL":
raise RuntimeError("任务需要补充参数,请按 Modal 流程继续")
if status not in ("NOT_START", "SUBMITTED", "IN_PROGRESS"):
raise RuntimeError(data)
time.sleep(3)
raise TimeoutError("等待超时,保留任务 ID 继续查询:" + task_id)
def click(task, label, marker):
button = next((item for item in task.get("buttons", [])
if item.get("label") == label
and marker in item.get("customId", "")), None)
if button is None:
raise RuntimeError("当前任务未提供按钮:" + label)
return submit("/mj/submit/action", {
"taskId": task["id"], "customId": button["customId"]})
grid_id = submit("/mj/submit/imagine", {"prompt": "一个红苹果 --ar 16:9"})
print("四宫格任务:", grid_id, flush=True)
grid = wait_task(grid_id)
single_id = click(grid, "U1", "::upsample::")
print("单图任务:", single_id, flush=True)
single = wait_task(single_id)
variation_id = click(single, "Vary (Strong)", "::high_variation::")
print("强变体任务:", variation_id, flush=True)
result = wait_task(variation_id)
if not result.get("imageUrl"):
raise RuntimeError("任务成功但没有返回图片地址")
print(result["imageUrl"])3. 局部重绘与扩图
先生成并选图,从单图查询结果中选择 Vary (Region)、Zoom Out、Custom Zoom 或方向按钮。Action 若直接返回生成任务则继续查询;若明确要求补充参数,则使用它给出的任务 ID 提交 Modal。不可跳过按钮步骤对任意图片地址直接执行这些动作。
错误处理
同时检查 HTTP 状态、提交响应和任务状态;HTTP 200 或进度 100% 均不等于生成成功。
| 错误 / 现象 | 原因与处理 |
|---|---|
custom_id_is_required | Action 缺少 customId;从对应任务的 buttons 中原样复制 |
task_not_exist / task_not_found / task_no_found | 任务不存在、已无法访问或访问上下文不一致;核对账户、服务地址及任务 ID |
model_not_found / No available channel | 当前分组暂无该操作的可用服务;联系管理员核对错误消息中的模型名称与权限,不修改 customId |
mj_high_variation 不可用 | 确认账户可使用该名称对应的强变体操作;仅有 mj_fast_high_variation 展示条目不保证权限完整 |
status=FAILURE、无效生图请求 | 保存 taskId、customId、完整请求地址和 failReason 排查;不能单凭此提示判断版本不兼容 |
progress=100% 但 imageUrl 为空 | 先看 status 与任务类型;失败任务及文字任务不一定有图片 |
| 没有目标按钮 | 当前任务不提供该动作;不能自行拼接按钮或替换版本片段 |
| HTTP 401 / 403 | 核对令牌有效性、账户分组和操作权限 |
| HTTP 429 / 503 | 查看具体错误;对限流或临时故障有限重试,权限或模型配置错误需先处理配置 |
请求中的 state 只用于追踪;它不选择模型、不指定倍率,也不能代替 taskId。
其他模型
edits、ric_reader、ricreader_retry 的 Fast / Relax 型号已收录于 模型目录。其独立请求字段或触发条件尚未确认,暂不发布可直接执行的请求示例;也不将它们等同于 Describe、Reroll 或 Inpaint。
