# MJ 接入概览与任务约定

<a id="midjourney"></a>

<a id="midjourney-原生图片任务"></a>

## MidJourney 原生图片任务

本节介绍本站 MidJourney 原生图片任务接口的参数、调用流程及开放范围。MJ 任务使用 `/mj` 接口，不能通过 OpenAI 图片生成、编辑或 Responses 图片任务接口调用。

网页创作请打开应用中心的 [MJ 工作台](/apps/midjourney)，使用当前账号积分完成生图、图片描述、融合、提示词精简及结果后续操作。工作台任务与 API Key 任务分别管理。

Base URL 为本站根地址 `https://y.junlistudio.com`，不带 `/v1`。请求使用 `Authorization: Bearer YOUR_API_KEY`；POST 请求使用 `Content-Type: application/json`。示例中的 API Key、任务 ID、Base64 和图片 URL 都须替换。

调用顺序：提交 Imagine → 保存回执的 `result` → 查询任务 → 成功后下载图片 → 如需放大或变体，再使用任务返回的按钮提交子任务。Describe / Shorten 返回分析文本，上传和 Seed 则同步返回各自结果。

 方法 | 接口 | 用途 |
| --- | --- | --- |
 POST | [`/mj/submit/imagine`](https://y.junlistudio.com/docs.md?page=mj-create#mj-imagine) | Imagine 文生图与垫图 |
 GET | [`/mj/task/{id}/fetch`](https://y.junlistudio.com/docs.md?page=mj-results#mj-fetch) | 查询单个任务 |
 GET | [`/mj/image/{id}`](https://y.junlistudio.com/docs.md?page=mj-results#mj-image) | 下载生成图片 |
 POST | [`/mj/submit/action`](https://y.junlistudio.com/docs.md?page=mj-actions#mj-action) | Action 放大、变体与扩图 |
 POST | [`/mj/submit/change`](https://y.junlistudio.com/docs.md?page=mj-actions#mj-change) | Change 结构化变化 |
 POST | [`/mj/submit/simple-change`](https://y.junlistudio.com/docs.md?page=mj-actions#mj-simple-change) | Simple Change 文本变化 |
 POST | [`/mj/submit/modal`](https://y.junlistudio.com/docs.md?page=mj-actions#mj-modal) | Modal 局部重绘与自定义 Zoom |
 POST | [`/mj/submit/describe`](https://y.junlistudio.com/docs.md?page=mj-create#mj-describe) | Describe 图生文 |
 POST | [`/mj/submit/blend`](https://y.junlistudio.com/docs.md?page=mj-create#mj-blend) | Blend 图片混合 |
 POST | [`/mj/submit/shorten`](https://y.junlistudio.com/docs.md?page=mj-create#mj-shorten) | Shorten 提示词分析 |
 POST | [`/mj/submit/upload-discord-images`](https://y.junlistudio.com/docs.md?page=mj-results#mj-upload-discord-images) | 上传图片并获取 URL |
 POST | [`/mj/submit/edits`](https://y.junlistudio.com/docs.md?page=mj-actions#mj-edits) | Edits 图片编辑 |
 POST | [`/mj/task/list-by-condition`](https://y.junlistudio.com/docs.md?page=mj-results#mj-list) | 批量查询任务 |
 GET | [`/mj/task/{id}/image-seed`](https://y.junlistudio.com/docs.md?page=mj-results#mj-seed) | 获取图片 Seed |

[回执与状态](#mj-contract)[任务返回字段](#mj-fields)[模式与开放范围](#mj-modes)[完整客户端示例](https://y.junlistudio.com/docs.md?page=mj-examples#mj-clients)[计费与排障](https://y.junlistudio.com/docs.md?page=mj-errors#mj-errors)

<a id="mj-contract"></a>

<a id="通用提交回执与任务状态"></a>

### 通用提交回执与任务状态

大多数生成、变体和编辑接口采用异步任务。提交成功不等于生成成功；HTTP 200 还必须检查 JSON 中的 `code` 和 `result`。

 **异步提交回执**  `JSON`

```json
{
  "code": 1,
  "description": "Submit Success",
  "result": "TASK_ID",
  "properties": null
}
```

 字段 | 类型 | 说明 |
| --- | --- | --- |
 `code` | integer | 业务状态码，见下表；不是 HTTP 状态码。 |
 `description` | string | 操作说明或错误原因，文案可能变化。 |
 `result` | string | 异步提交接受时为非空任务 ID；保存后查询。上传和 Seed 的含义另见对应接口。 |
 `properties` | object / null | 附加信息，错误响应通常为 null；错误原因读取 description。 |

 code | 含义 | 处理 |
| --- | --- | --- |
 1 | 已接受 | 保存字符串 result，然后查询任务；这不代表图片已生成。 |
 21 | 需补充 Modal 参数，或关联任务已存在 | 保存 result 并检查任务状态及 description；需要 Modal 时使用该 ID 提交 modal。不能一律视为已完成，也不要重复提交原 Action。 |
 22 | 已接受，排队中 | 保存 result，按 3–5 秒间隔轮询。 |
 23 | 队列已满，明确拒绝 | 确认没有接受任务后，再有限次退避重试；不要与提交超时混为一谈。 |
 24 | 提示词被拒绝 | 查看 description，调整提示词后再提交。 |
 3 | 关联任务失效或账号不可用 | 检查父任务、动作权限及任务时效。 |
 其他 | 提交失败 | 保留原始回执，按 description 排查；本站自身错误采用 code: 4。 |

`1 / 21 / 22` 只有结合非空字符串任务 ID 才能继续后续流程；`21` 不应直接当作普通排队或完成。查询返回裸任务对象；终态为 `SUCCESS / FAILURE / CANCEL`。

 status | 含义 | 处理 |
| --- | --- | --- |
 NOT\_START | 未开始 | 继续轮询。 |
 SUBMITTED | 已提交 | 继续轮询。 |
 MODAL | 等待补充参数 | 当前 Action 已完成并结算，不再占用进行中并发；补充参数后提交独立计费的 Modal 任务。 |
 IN\_PROGRESS | 执行中 | 继续轮询，progress 为字符串。 |
 SUCCESS | 成功，终态 | 图片读取 imageUrl；Describe / Shorten 读取 properties。 |
 FAILURE | 失败，终态 | 读取 failReason，本次预扣积分退回。 |
 CANCEL | 取消，终态 | 结束轮询，本次预扣积分退回；这不是可调用的取消接口。 |

建议每 3–5 秒查询，客户端一次等待可设为 5–10 分钟。到达等待期限后保存任务 ID，稍后继续查询；等待超时不代表任务失败，也不会取消任务。

<a id="mj-fields"></a>

<a id="任务返回字段"></a>

### 任务返回字段

图片结果不包装成 OpenAI 的 `data[].url`。下表列出任务的常用字段；部分字段随动作和状态出现，客户端应容忍附加字段。

 字段 | 类型 | 说明 |
| --- | --- | --- |
 `id` | string | 本站任务 ID；后续操作继续使用此值。 |
 `action` | string | 动作类型，例如 IMAGINE、UPSCALE、VARIATION。 |
 `status` | string | 任务状态，见状态表。 |
 `progress` | string | 例如 "0%"、"100%"，不是数值。 |
 `prompt / promptEn` | string | 原提示词及处理后的英文提示词。 |
 `imageUrl` | string | 有图片时返回完整下载 URL；本站签名地址有效期 15 分钟。 |
 `imageUnavailable / imageUnavailableReason` | boolean / string | 确认图片已失效或被删除时返回 true 及具体提示，不再返回 imageUrl 和可用按钮；原生成状态和计费记录保留。 |
 `failReason` | string | 失败原因；正常任务通常为空字符串。 |
 `state` | string | 提交时携带的业务标识。 |
 `submitTime / startTime / finishTime` | integer | Unix 毫秒时间戳，未开始或未完成时可能为空或 0。 |
 `properties` | object / null | 动作相关结果；Describe、Shorten 常用 finalPrompt 和 finalZhPrompt。 |
 `buttons` | array | 当前任务可执行按钮；不同动作、模型版本返回的按钮可能不同。 |
 `buttons[].customId` | string | 不透明按钮标识，必须原样传给 action，不能根据 label 自行拼接。 |
 `buttons[].label / emoji` | string | 按钮文字和图标，可用于选择 U1、V1、Zoom 等操作。 |
 `buttons[].type / style` | integer | 按钮类型及样式，按原值保留。 |

后续操作使用本站返回的任务 ID、图片下载地址和 `buttons[].customId`。

<a id="mj-modes"></a>

<a id="模式与当前开放范围"></a>

### 模式与当前开放范围

本站当前仅开放默认 `/mj` 下已配置的动作。Fast、Turbo、Relax 独立模式尚未开放，请使用默认入口。

 接口前缀 | 用途 | 本站状态 |
| --- | --- | --- |
 `/mj` | 平台默认模式 | 本站当前入口；仅已启用、已定价且 Key 有权限的动作可调用。 |
 `/mj-fast/mj` | Fast | 本站当前未开放独立模式。 |
 `/mj-turbo/mj` | Turbo | 本站当前未开放独立模式。 |
 `/mj-relax/mj` | Relax | 本站当前未开放独立模式。 |

下载图片时使用查询返回的完整 `imageUrl`。

 功能 | 本站状态 |
| --- | --- |
 图片生成、变化、编辑、分析、上传、查询、Seed | 已适配本节所列接口；须有对应模型、价格和 Key 权限，不代表所有账号默认可用。 |
 `notifyHook` 回调 | 尚未开放，非空值被拒绝；使用轮询。不会悄悄丢弃回调地址或伪造通知。 |
 `POST /mj/submit/video` | 尚未适配 MJ 视频，新建和扩展均不可调用。 |
 `POST /mj/insight-face/swap` | 尚未适配换脸，不接受 accountFilter.instanceId 指定账号。 |

请求字段按本节参数表填写，生成 / 动作提交时未列出的字段会被拒绝。生成 / 编辑提交体上限为 50 MiB，包含 Base64 的体积；批量查询上限为 64 KiB。Data URL 使用 `data:image/png;base64,...` 等图片 MIME 格式，省略可选数组时不要发送空数组。