> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Midjourney 任务接入

> 查询已有任务，理解动作路由和业务错误。

Midjourney 使用 `/mj/*` 的独立任务协议，不适用 `/v1/images/generations` 的请求和返回结构。需配置对应渠道；模型令牌使用网关 Bearer 认证。`/{mode}/mj/*` 还有模式前缀入口，可用 mode 由部署决定，不应自行猜测。

## 最小读取示例

按 [REST 运行环境](/zh/guides/http-runtime)准备环境，使用已有任务的公开 ID，脚本只查询一次，不提交生成，也不下载返回的 URL。

```bash theme={null}
export API_MJ_TASK_ID="YOUR_MJ_TASK_ID"
node examples/midjourney-status.mjs
```

成功返回任务对象，读取 `id`、`status`、`progress` 等；错误可能仍是 HTTP 200，带 `code` / `description`。示例拒绝该错误信封，严格核对任务 ID 和状态。进程成功退出只是查询完成；`completed: true` 才表示任务成功。`imageUrl` 可能是网关签名地址，避免公开日志；视频任务还有 `videoUrl` / `videoUrls`，不能假定都是图片。见 [任务 API](/zh/api-reference/midjourney-task)。

刚受理的任务可能暂时返回空 `status`，示例显示为应用侧 `PENDING`，不视为成功；`PENDING` 不是这里新增的服务端状态。

## 提交和后续动作

提交体来自 `MidjourneyRequest`，包含 `prompt`、`taskId`、`customId`、`action`、`index`、`base64Array` 等按动作选择的字段。响应通常为 `code`、`description`、`result`、`properties`；保存业务受理后返回的任务 ID，再查询，不能把 HTTP 200 当作图片生成成功。不同上游代理的动作与 `customId` 格式有差异，必须采用部署方提供的请求，不能从按钮文案推导参数。

下列路由均已登记，但此表不是各供应商 payload 的替代。`/mj/notify` 未注册，不能把 DTO 中存在 `notifyHook` 当作网关提供回调接收能力。

| POST 路径 | 用途 |
| - | - |
| `/mj/submit/imagine` | 文生图 |
| `/mj/submit/action`、`/mj/submit/modal` | 返回按钮动作及模态补充 |
| `/mj/submit/change`、`/mj/submit/simple-change` | 变体与修改 |
| `/mj/submit/describe`、`/mj/submit/blend` | 描述与混合图片 |
| `/mj/submit/shorten`、`/mj/submit/edits` | 提示词缩短与编辑 |
| `/mj/submit/video` | 视频动作 |
| `/mj/submit/upload-discord-images` | 上传图片动作 |
| `/mj/insight-face/swap` | 独立换脸请求结构 |
| `/mj/task/list-by-condition` | 请求 `ids` 数组，读取所属任务数组，不保证与输入顺序一致 |

另有 `GET /mj/task/{id}/image-seed` 和 `GET /mj/image/{id}`，分别查询种子与代理图片；不可把这两个响应当成任务 JSON。对生成类请求不自动重试；轮询、业务码与最终产物应在选定上游完成真实验收。

```javascript theme={null}
import { requestJSON } from './http-client.mjs';

try {
  const id = process.env.API_MJ_TASK_ID;
  if (!/^[A-Za-z0-9_-][A-Za-z0-9._~-]{0,127}$/.test(id || '')) throw new Error('Set API_MJ_TASK_ID.');
  const result = await requestJSON(`/mj/task/${encodeURIComponent(id)}/fetch`);
  if ('code' in result || result.id !== id
    || !['', 'NOT_START', 'SUBMITTED', 'IN_PROGRESS', 'SUCCESS', 'FAILURE'].includes(result.status)) {
    throw new Error('Invalid task or business error.');
  }
  // Query once; SUCCESS describes task state, not a downloaded or verified image.
  console.log(JSON.stringify({ id, status: result.status || 'PENDING', completed: result.status === 'SUCCESS' }));
} catch {
  console.error('Midjourney status request failed. No automatic submission or retry.');
  process.exitCode = 1;
}
```

[Read in English](/en/guides/midjourney)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.