# MJ 绘画 API 文档

# MJ 绘画 API 文档

本文档详细说明了 MJ (Midjourney) 绘画相关的 API 接口。

## 鉴权

所有接口均需要在 Header 中携带 `Authorization` 字段进行鉴权。

| 参数名 | 位置 | 类型 | 描述 | 示例 |
| :--- | :--- | :--- | :--- | :--- |
| Authorization | Header | string | API Key | `{{YOUR_API_KEY}}` |

---

## 任务提交接口

### 1. 提交 Imagine 任务

提交文生图任务。提交后获取任务ID，需使用查询接口查询任务状态。

- **接口地址**: `/mj/submit/imagine`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| botType | string | 否 | bot类型: `MID_JOURNEY` (默认), `NIJI_JOURNEY` |
| prompt | string | 是 | 提示词 |
| base64Array | array | 否 | 垫图base64数组 |
| notifyHook | string | 否 | 回调地址 |
| noStorage | boolean | 否 | 是否返回官方链接 (默认 false) |
| accountFilter | object | 否 | 账号筛选配置 |

**accountFilter 结构:**

| 参数名 | 类型 | 描述 |
| :--- | :--- | :--- |
| modes | array | 速度筛选，如 `["RELAX"]` |

#### 请求示例

```json
{
  "botType": "MID_JOURNEY",
  "prompt": "Cat",
  "base64Array": [],
  "notifyHook": "",
  "noStorage": false
}
```

#### 响应结果

返回 `提交结果` 对象。

```json
{
  "code": 1,
  "description": "提交成功",
  "result": "1320098173412546"
}
```

### 2. 提交 Blend 任务

提交混图任务。

- **接口地址**: `/mj/submit/blend`
- **请求方式**: `POST`

#### 请求参数 (Blend提交参数)

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| base64Array | array | 是 | 图片base64数组 (2-5张) |
| botType | string | 否 | bot类型: `MID_JOURNEY` (默认), `NIJI_JOURNEY` |
| dimensions | string | 否 | 比例: `PORTRAIT`(2:3), `SQUARE`(1:1), `LANDSCAPE`(3:2) |
| notifyHook | string | 否 | 回调地址 |
| state | string | 否 | 自定义参数 |

#### 请求示例

```json
{
  "botType": "MID_JOURNEY",
  "base64Array": [
    "data:image/png;base64,xxx1",
    "data:image/png;base64,xxx2"
  ],
  "dimensions": "SQUARE"
}
```

### 3. 提交 Describe 任务

提交识图（图生文）任务。

- **接口地址**: `/mj/submit/describe`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| botType | string | 否 | bot类型: `MID_JOURNEY` (默认), `NIJI_JOURNEY` |
| base64 | string | 否 | 图片base64 (与link二选一) |
| link | string | 否 | 图片链接 (与base64二选一) |
| notifyHook | string | 否 | 回调地址 |
| state | string | 否 | 自定义参数 |
| language | string | 否 | 语言: `en` (默认), `zh_cn` |

#### 请求示例

```json
{
  "botType": "MID_JOURNEY",
  "link": "https://example.com/image.jpg",
  "language": "en"
}
```

### 4. 提交 Action 任务

执行任务的后续操作（如 U, V, Reroll, Zoom 等）。

- **接口地址**: `/mj/submit/action`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| customId | string | 是 | 动作标识 (从任务查询结果的 buttons 中获取) |
| taskId | string | 是 | 任务ID |
| notifyHook | string | 否 | 回调地址 |
| state | string | 否 | 自定义参数 |
| noStorage | boolean | 否 | True: 返回原始图片链接 |
| enableRemix | boolean | 否 | 是否使用 remix 模式 (默认 false) |

#### 请求示例

```json
{
  "customId": "MJ::JOB::variation::1::UUID",
  "taskId": "1746531634074810",
  "enableRemix": true
}
```

### 5. 提交 Modal 任务

提交 Modal（弹窗）操作，通常用于 remix 或 custom zoom 等需要输入参数的操作。

- **接口地址**: `/mj/submit/modal`
- **请求方式**: `POST`

#### 请求参数 (Modal提交参数)

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| taskId | string | 是 | 任务ID |
| prompt | string | 否 | 提示词 |
| maskBase64 | string | 否 | 局部重绘的蒙版base64 |
| noStorage | boolean | 否 | True: 返回原始图片链接 |

#### 请求示例

```json
{
  "taskId": "14001934816969359",
  "prompt": "new prompt"
}
```

### 6. 提交 Video 任务

提交视频生成任务。

- **接口地址**: `/mj/submit/video`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| videoType | string | 是 | 视频类型: `vid_1.1_i2v_480`, `vid_1.1_i2v_720` |
| image | string | 是 | 首帧图片 (url 或 base64) |
| motion | string | 是 | 运动幅度: `low`, `high` |
| prompt | string | 否 | 提示词 |
| endImage | string | 否 | 尾帧图片 (url 或 base64) |
| loop | boolean | 否 | 是否循环 |
| batchSize | integer | 否 | 生成数量 (1, 2, 4, 默认 4) |
| action | string | 否 | 操作类型: `extend` (扩展视频时填写) |
| index | integer | 否 | 视频索引 (0-3, action不为空时必填) |
| taskId | string | 否 | 父任务ID (action不为空时必填) |
| notifyHook | string | 否 | 回调地址 |

#### 请求示例

```json
{
  "prompt": "run cat",
  "videoType": "vid_1.1_i2v_480",
  "image": "https://example.com/cat.jpg",
  "motion": "low",
  "batchSize": 1
}
```

### 7. 提交 Edit 任务

提交图片编辑/重绘任务。

- **接口地址**: `/mj/submit/edits`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| prompt | string | 是 | 提示词 |
| image | string | 是 | 图片 (url 或 base64) |
| maskBase64 | string | 否 | 蒙版base64 (透明表示编辑区域) |
| notifyHook | string | 否 | 回调地址 |
| noStorage | boolean | 否 | 是否不存储 |

### 8. 提交 Retexture 任务

提交材质重绘任务。

- **接口地址**: `/mj/submit/retexture`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| prompt | string | 是 | 提示词 |
| image | string | 是 | 图片 (url 或 base64) |
| notifyHook | string | 否 | 回调地址 |

### 9. 上传文件到 Discord

上传图片到 Discord 以获取链接，用于垫图等。

- **接口地址**: `/mj/submit/upload-discord-images`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| base64Array | array | 否 | base64字符串数组 |

---

## 任务查询接口

### 1. 指定 ID 获取任务

查询单个任务详情。

- **接口地址**: `/mj/task/{id}/fetch`
- **请求方式**: `GET`
- **路径参数**: `id` (任务ID)

#### 响应结果 (任务对象)

| 字段名 | 类型 | 描述 |
| :--- | :--- | :--- |
| id | string | 任务ID |
| status | string | 状态: `NOT_START`, `SUBMITTED`, `IN_PROGRESS`, `FAILURE`, `SUCCESS`, `CANCEL` |
| progress | string | 进度 (如 "100%") |
| imageUrl | string | 主图链接 |
| imageUrls | array | 单图链接列表 |
| action | string | 任务类型 (IMAGINE, UPSCALE, VARIATION 等) |
| prompt | string | 提示词 |
| promptEn | string | 英文提示词 |
| description | string | 状态描述 |
| failReason | string | 失败原因 |
| submitTime | integer | 提交时间 |
| startTime | integer | 开始时间 |
| finishTime | integer | 结束时间 |
| buttons | array | 可执行的操作按钮列表 |

**Button 结构:**

| 字段名 | 类型 | 描述 |
| :--- | :--- | :--- |
| customId | string | 动作标识 |
| label | string | 按钮文本 (U1, V1 等) |
| emoji | string | 图标 |

### 2. 根据 ID 列表查询任务

批量查询任务状态。

- **接口地址**: `/mj/task/list-by-condition`
- **请求方式**: `POST`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| ids | array | 否 | 任务ID字符串数组 |

#### 响应结果

返回任务对象数组。

### 3. 获取任务图片的 Seed

获取已完成任务的 Seed 值。

- **接口地址**: `/mj/task/{id}/image-seed`
- **请求方式**: `GET`
- **路径参数**: `id` (任务ID)

#### 响应结果

```json
{
  "code": 1,
  "description": "Success",
  "result": "123456789"
}
```

---

## 数据模型

### 提交结果

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| code | integer | 状态码: 1(成功), 22(排队中), 其他(错误) |
| description | string | 描述 |
| result | string | 任务ID |

### 任务状态 (Status)

- `NOT_START`: 未开始
- `SUBMITTED`: 已提交
- `MODAL`: 等待弹窗确认
- `IN_PROGRESS`: 执行中
- `FAILURE`: 失败
- `SUCCESS`: 成功
- `CANCEL`: 已取消