# MJ 查询、下载与辅助接口

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

<a id="查询单个任务"></a>

## 查询单个任务

 **GET**  `/mj/task/{id}/fetch`

返回裸任务对象，包含任务状态、进度、图片或分析结果及可执行按钮。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `id（路径）` | `string` | 是 | 当前 API Key 创建的任务 ID；提交、查询和后续操作使用同一站点和 Key。 |

 **查询任务**  `GET /mj/task/{id}/fetch`

```bash
curl --fail-with-body 'https://y.junlistudio.com/mj/task/TASK_ID/fetch' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

 **返回：** 直接返回任务对象，不包在 result、data 或 data\[\].url 中。下方示例展示主要字段；字段是否存在取决于任务动作和状态。

 **成功任务示例**  `响应示例`

```json
{
  "id": "TASK_ID",
  "action": "IMAGINE",
  "status": "SUCCESS",
  "progress": "100%",
  "prompt": "a cat in sunlight --ar 16:9",
  "promptEn": "a cat in sunlight --ar 16:9",
  "imageUrl": "IMAGE_URL_FROM_RESPONSE",
  "failReason": "",
  "state": "order-123",
  "submitTime": 1787317252488,
  "startTime": 1787317253000,
  "finishTime": 1787317270584,
  "properties": {},
  "buttons": [
    {
      "customId": "COPY_EXACT_CUSTOM_ID_FROM_BUTTONS",
      "emoji": "",
      "label": "U1",
      "type": 2,
      "style": 2
    }
  ]
}
```

每 3–5 秒查询一次；FAILURE / CANCEL 读取 failReason，SUCCESS 读取对应结果。

查询不重复收费。即使同一用户创建多把 Key，也不能使用另一把 Key 查询该任务。

计费：查询不新增动作费用。动作是否开放及价格，以本站模型目录和当前 Key 权限为准。

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

<a id="批量查询任务"></a>

## 批量查询任务

 **POST**  `/mj/task/list-by-condition`

按任务 ID 列表查询，返回裸任务数组。只查询明确列出的任务，不支持按 state 搜索或列出所有任务。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `ids` | `string[]` | 是 | 任务 ID 数组，最多 100 个；必须全部属于当前 Key。空数组返回空数组。 |

 **批量查询**  `POST /mj/task/list-by-condition`

```bash
curl --fail-with-body -X POST 'https://y.junlistudio.com/mj/task/list-by-condition' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "ids": [
    "TASK_ID",
    "TASK_ID_2"
  ]
}'
```

 **返回：** 数组内每项与单任务查询格式一致；下方省略了重复的任务字段。

 **任务数组（节选）**  `响应示例`

```json
[
  {
    "id": "TASK_ID",
    "status": "SUCCESS",
    "progress": "100%",
    "imageUrl": "IMAGE_URL_FROM_RESPONSE"
  },
  {
    "id": "TASK_ID_2",
    "status": "IN_PROGRESS",
    "progress": "50%"
  }
]
```

本站先校验整批任务归属，再逐个读取任务；任一任务无权访问或查询失败会使整批请求报错，不返回部分成功数组。

可回退为逐个 GET 查询以定位失败任务。本站批量请求体上限 64 KiB。

计费：查询不新增动作费用。动作是否开放及价格，以本站模型目录和当前 Key 权限为准。

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

<a id="下载生成图片"></a>

## 下载生成图片

 **GET**  `/mj/image/{id}`

图片生成完成后，优先使用任务返回的完整 imageUrl 下载；不要自行拼接图片地址。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `id（路径）` | `string` | 是 | 当前 API Key 创建的任务 ID；提交、查询和后续操作使用同一站点和 Key。 |
 `token（查询）` | `string` | 条件 | imageUrl 自带的临时签名，无需额外 Bearer。直接调用不带 token 的下载路径时，须携带创建任务的 API Key。 |

 **用当前 Key 下载图片**  `GET /mj/image/{id}`

```bash
curl --fail-with-body 'https://y.junlistudio.com/mj/image/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output result.png
```

 **使用返回的签名地址**  `GET /mj/image/{id}`

```bash
curl --fail-with-body 'PASTE_COMPLETE_IMAGE_URL_HERE' --output result.png
```

 **返回：** 返回 image/\* 二进制，不是 JSON 或 Base64。

签名 URL 有效期 15 分钟；失效后重新查询任务，取得新的 imageUrl。建议及时保存图片到自己的存储。

签名链接本身授予临时下载权限，不要公开分享。向返回的签名 URL 下载时无需附带 API Key。

检查 HTTP 状态及 Content-Type，再按实际图片格式保存；本站下载代理上限为 32 MiB。

计费：下载不新增动作费用。动作是否开放及价格，以本站模型目录和当前 Key 权限为准。

<a id="mj-upload-discord-images"></a>

<a id="上传图片并获取-url"></a>

## 上传图片并获取 URL

 **POST**  `/mj/submit/upload-discord-images`

将图片 Data URL 上传为后续可引用的 URL。该接口同步返回，不需要轮询任务。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `base64Array` | `string[]` | 是 | 本站要求 1–10 个图片 Data URL；不接受 state 或 notifyHook。 |

 **上传一张图片**  `POST /mj/submit/upload-discord-images`

```bash
curl --fail-with-body -X POST 'https://y.junlistudio.com/mj/submit/upload-discord-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "base64Array": [
    "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
  ]
}'
```

 **返回：** 同步返回以下两种格式之一。对象回执必须检查 code；不能只凭 result 存在判断上传成功。

 **对象回执**  `响应示例`

```json
{
  "code": 1,
  "description": "提交成功",
  "result": [
    "https://images.example.com/uploaded.png"
  ],
  "properties": {}
}
```

 **裸 URL 数组**  `响应示例`

```json
[
  "https://images.example.com/uploaded.png"
]
```

返回格式可能为裸 URL 数组或 result 为 URL 数组的回执，客户端需要兼容这两种格式。

result 数组不是任务 ID。URL 有效期有限，长期使用应自行保存。

计费：mj\_uploads。动作是否开放及价格，以本站模型目录和当前 Key 权限为准。

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

<a id="获取图片-seed"></a>

## 获取图片 Seed

 **GET**  `/mj/task/{id}/image-seed`

读取原任务对应的 Seed。使用 GET；同时兼容原有 POST 空 JSON 调用。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `id（路径）` | `string` | 是 | 当前 API Key 创建的任务 ID；提交、查询和后续操作使用同一站点和 Key。 |

 **查询 Seed**  `GET /mj/task/{id}/image-seed`

```bash
curl --fail-with-body 'https://y.junlistudio.com/mj/task/TASK_ID/image-seed' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

 **返回：** 返回 Seed 回执；result 是 Seed 字符串，不是新任务 ID。

 **Seed 回执示例**  `响应示例`

```json
{
  "code": 1,
  "description": "成功",
  "result": "636646138"
}
```

Seed 回执可能使用 code: 0 或 code: 1。以 code 为 0 或 1 且 result 为非空字符串判断成功，不要套用异步任务提交的判定。

建议在原图片任务成功后查询；未提供 Seed 时返回 503，稍后只重试本查询，不重复提交生成任务。

计费：本站不新增 Seed 动作扣费。动作是否开放及价格，以本站模型目录和当前 Key 权限为准。