# MJ 图片/视频生成 API 对接文档（国内）

## 概述

MJ 系列接口提供图像生成、图像编辑、图生视频、视频处理等基础生成能力，采用任务化（异步）模型：调用生成类接口后返回 `jobId`，再通过查询接口轮询任务状态获取结果。

> 本版本将原单一的 `/aigc/mj` 接口拆分为多个语义化的独立接口（`/mj/v1/tob/*`），每个动作对应一个独立路径。原 `/aigc/mj` 接口已废弃。

**Base URL**: `https://api.apiverse.ai`

---

## 认证方式

所有接口均需在请求头中携带 API Key 进行认证：

```
Authorization: Bearer {YOUR_API_KEY}
```

---

## 响应结构（生成类接口）

所有生成类接口（图片 / 视频）返回统一的任务对象：

| 字段 | 类型 | 说明 |
|------|------|------|
| jobId | string | 任务 ID，用于后续查询或二次操作 |
| comment | string | 任务状态，见「任务状态」章节 |
| reason | string | 失败原因（仅任务失败时返回，已脱敏） |
| text | string | 提示词（图片任务返回） |
| urls | string[] | 图片结果 URL 列表（图片任务） |
| videoUrls | string[] | 视频结果 URL 列表（视频任务） |
| cost | number | 消耗金额，任务完成后更新 |
| createdAt | string | 创建时间（查询接口返回） |
| finishedAt | string | 完成时间（查询接口返回） |

> 创建任务时 `comment` 固定为 `JobStatusCreated`，`urls` / `videoUrls` 为空数组，`cost` 为 0。结果需通过「查询任务信息」接口获取。

**创建成功响应示例**

```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusCreated",
  "text": "一只可爱的橘猫在阳光下打盹，油画风格",
  "urls": [],
  "cost": 0
}
```

---

## 错误结构

```json
{
  "code": 400,
  "message": "Invalid_Argument",
  "reason": "请求参数无效: ..."
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 错误码 |
| message | string | 错误标识 |
| reason | string | 失败原因详情 |

常见错误码见文末「错误码」章节。

---

## 接口总览

| 分类 | 接口 | 方法 | 路径 |
|------|------|------|------|
| 图片生成 | 图像生成 | POST | `/api/v2/open/mj/v1/tob/diffusion` |
| 图片生成 | 变化 | POST | `/api/v2/open/mj/v1/tob/variation` |
| 图片生成 | 高清放大 | POST | `/api/v2/open/mj/v1/tob/upscale` |
| 图片生成 | 重新执行 | POST | `/api/v2/open/mj/v1/tob/reroll` |
| 图片生成 | 延展 | POST | `/api/v2/open/mj/v1/tob/pan` |
| 图片生成 | 扩图 | POST | `/api/v2/open/mj/v1/tob/outpaint` |
| 图片生成 | 区域重绘 | POST | `/api/v2/open/mj/v1/tob/inpaint` |
| 图片生成 | 重塑 | POST | `/api/v2/open/mj/v1/tob/remix` |
| 图片生成 | 编辑 | POST | `/api/v2/open/mj/v1/tob/edit` |
| 图片生成 | 高级编辑 | POST | `/api/v2/open/mj/v1/tob/upload-paint` |
| 图片生成 | 转绘 | POST | `/api/v2/open/mj/v1/tob/retexture` |
| 图片生成 | 移除背景 | POST | `/api/v2/open/mj/v1/tob/remove-background` |
| 图片生成 | 增强 | POST | `/api/v2/open/mj/v1/tob/enhance` |
| 视频生成 | 图生视频 | POST | `/api/v2/open/mj/v1/tob/video-diffusion` |
| 视频生成 | 视频延长 | POST | `/api/v2/open/mj/v1/tob/extend-video` |
| 视频生成 | 视频高清 | POST | `/api/v2/open/mj/v1/tob/video-upscale` |
| 任务查询 | 查询任务信息 | GET | `/api/v2/open/mj/v1/tob/job/{jobId}` |

---

## 一、图片生成接口

### 1.1 图像生成

**POST** `/api/v2/open/mj/v1/tob/diffusion`

核心的图像生成接口。提示词、生成参数、参考图片 URL 均通过 `text` 字段传入（与标准提示词写法一致，可在文本中嵌入图片链接与 `--ar`、`--v` 等参数）。当 `text` 中包含图片链接时按图生图计费，否则按文生图计费。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| text | string | 是 | 提示词，支持纯文本、嵌入图片 URL、生成参数 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "text": "一只可爱的橘猫在阳光下打盹，油画风格 --ar 16:9 --v 7",
  "callback": "https://your-domain.com/callback"
}
```

#### 使用场景

`text` 字段整体透传给生成引擎，通过不同的内容组合覆盖以下常见场景（`[]` 表示可选内容，实际请求中不需要写方括号）：

| 场景 | text 字段格式 | 说明 |
|------|--------------|------|
| 纯文本生图 | `描述文本 [--参数]` | 仅通过文字描述生成图像 |
| 单图 + 文本 | `图片URL 描述文本 [--参数]` | 参考一张图片，结合文字描述生成新图像 |
| 多图融合 | `图片URL1 图片URL2 [--参数]` | 混合多张图片的风格与元素（无文本） |
| 多图 + 文本 | `图片URL1 图片URL2 描述文本 [--参数]` | 多张参考图配合文字获得更精确的引导 |
| 角色参考 | `描述文本 --cref 人物图片URL` | 在新图中保持指定角色的面部、发型、服装一致性 |
| 风格参考 | `描述文本 --sref 风格图片URL` | 迁移参考图的视觉风格（颜色、纹理、光照）到新创作 |
| 万物引用 | `描述文本 --oref 物体图片URL` | 将参考图中的角色或物体放入新场景（仅 v7） |

> `text` 中可包含以 `http://` / `https://` 开头的图片链接实现图生图；图片链接需公网可访问。图像生成为**基础生成**，无论是否携带参考图，价格一致（按单次任务计费，一次生成一组图片），仅速度档影响计费倍率。

#### 常用生成参数

以下参数直接写在 `text` 中，与提示词、图片链接混用，例如 `一只猫 --ar 16:9 --v 7 --cref https://.../face.jpg --cw 80`。

| 参数 | 说明 | 取值范围 |
|------|------|----------|
| `--ar` | 画面宽高比 | 如 `16:9`、`1:1`、`2:3` |
| `--v` | 模型版本 | `6` / `6.1` / `7` / `8.1` / `8.2` |
| `--iw` | 图像提示权重，控制参考图对结果的影响程度 | 0-3，默认 1 |
| `--cref` | 角色参考图 URL | 支持 v6 / v6.1 / niji 6 |
| `--cw` | 角色参考权重 | 0-100，默认 100 |
| `--sref` | 风格参考图 URL（可多个） | 支持全部图像模型 |
| `--sw` | 风格参考权重 | 0-1000，默认 100 |
| `--sv` | 风格算法版本 | 1-4（v7 支持 1-6），默认 4 |
| `--oref` | 万物引用图 URL（仅 1 张） | 仅 v7 |
| `--ow` | 万物引用权重 | 1-1000，默认 100 |

> 上述参数由生成引擎解析，网关不做额外校验；参数格式错误时任务会以 `JobStatusBadPrompt` / `JobStatusInvalidParameter` 状态返回，且不消耗额度。

#### 版本选择（`--v` 参数）

模型版本通过在 `text` 中追加 `--v` 参数指定，写在提示词末尾即可，可与 `--ar`、`--sref` 等参数混用。未指定 `--v` 时使用平台默认版本。

| 写法 | 版本 | 说明 |
|------|------|------|
| `--v 6` / `--v 6.1` | v6 / v6.1 | 早期版本 |
| `--v 7` | v7 | 支持万物引用（`--oref`）、草图模式半价 |
| `--v 8.1` | v8.1 | 最新版本，提示词遵循更强、支持原生 2K 高清（`--hd`），`--q` 仅支持 `1` / `4` |
| `--v 8.2` | v8.2 | 与 v8.1 能力一致，`--q` 支持 `1` / `2` / `3` / `4` |

**使用示例：**

```json
{
  "text": "young elven hunter with moss-woven armor, soft forest light --ar 2:3 --raw --v 8.2 --hd",
  "callback": "https://your-domain.com/callback"
}
```

> - 版本号直接跟在 `--v` 后，如 `--v 8.2`；不写 `--v` 则由平台按默认版本处理。
> - v8.1 与 v8.2 的核心区别：v8.1 的 `--q`（图像细节质量）仅支持 `1` 和 `4`，v8.2 扩展为 `1` / `2` / `3` / `4`（`4` 为最高质量档）。

#### v8 系列（v8.1 / v8.2）专有参数

v8.1 与 v8.2 在 v7 参数基础上新增以下能力，均写在 `text` 中：

| 参数 | 说明 | 取值范围 | 计费影响 |
|------|------|----------|----------|
| `--hd` | 原生 2K 高清渲染，生成阶段即输出高分辨率，一次任务直接生成 4 张高清图 | 无需填值 | **叠加 1.5× 系数** |
| `--q` | 图像细节质量，`4` 为高质量模式 | v8.1：`1` / `4`；v8.2：`1` / `2` / `3` / `4`，默认 `1` | 不影响计费 |
| `--raw` | 原始模式，不采用默认美化 | 无需填值 | 不影响计费 |
| `--stylize` | 艺术风格强度 | 0-1000，默认 100 | 不影响计费 |
| `--exp` | 实验参数，增加画面动态感 | 0-100，默认 0 | 不影响计费 |
| `--draft` | 单次生成 24 张 0.5K 草图，用于快速预览 | 无需填值 | **系数为 1**（v8 系列草图不享受 v7 的 0.5× 减半） |

> - v8 系列的高清出图通过 `--hd` 实现（原生 2K），不再使用独立的「高清放大」接口，一次任务直接产出 4 张高清图。
> - `--q` 与风格参考（`--sref` / Moodboard）不影响计费。
> - v8 系列完全兼容 v7 的 `--sref` 风格参考与 Moodboard，已有风格资产可直接迁移。
> - v8 系列的非「标准生图」类任务（变化、编辑、转绘等）计费与 v7 一致。

#### 速度档（计费系数）

生成速度通过在 `text` 中追加速度参数控制，不同速度档对应不同计费倍率。未指定时默认 **快速档**。

| 参数 | 速度档 | 计费系数 | 说明 |
|------|--------|----------|------|
| `--fast` | 快速（默认） | 1× | 默认档位，不写速度参数时即为此档 |
| `--turbo` | 极速 | 2× | 更快出图，计费翻倍 |
| `--draft` | 草图 | 0.5×（仅 `--v 7`） | 半价快速预览；v8 系列亦可用 `--draft`，但计费系数为 1（不减半） |
| `--relax` | 放松 | 1× | 按快速档计费（无单独优惠档） |

> - 速度参数与 `--ar`、`--v` 等一样直接写在 `text` 中，可与其它参数混用，例如 `... --ar 16:9 --v 7 --turbo`。
> - 派生操作（变化、放大、延展等）不单独指定速度档，自动继承原始生成任务的速度档计费。
> - 实际单价以你的计费方案为准，上表系数为各档之间的相对倍率。

示例：`"text": "一只猫 --ar 16:9 --v 7 --turbo"`（极速档，2× 计费）

#### 响应示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusCreated",
  "text": "一只可爱的橘猫在阳光下打盹，油画风格 --ar 16:9 --v 7",
  "urls": [],
  "cost": 0
}
```

---

### 1.2 变化（Variation）

**POST** `/api/v2/open/mj/v1/tob/variation`

基于已生成图片中的某一张，生成相似的变体。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| type | int | 是 | 变化程度：`0` 轻微 / `1` 强烈 |
| remixPrompt | string | 否 | 重塑提示词 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "type": 1,
  "remixPrompt": "换成夜晚的场景"
}
```

---

### 1.3 高清放大（Upscale）

**POST** `/api/v2/open/mj/v1/tob/upscale`

对指定图片进行高清放大。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| type | int | 是 | 放大模式：`0` 标准 / `1` 创意 / `2` v5_2x / `3` v5_4x |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "type": 0
}
```

---

### 1.4 重新执行（Reroll）

**POST** `/api/v2/open/mj/v1/tob/reroll`

以源任务的参数重新生成一组图片。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345"
}
```

---

### 1.5 延展（Pan）

**POST** `/api/v2/open/mj/v1/tob/pan`

向指定方向平移并扩展画面内容。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| direction | int | 是 | 延展方向：`0` 下 / `1` 右 / `2` 上 / `3` 左 |
| scale | number | 是 | 延展比例（1.1-3.0） |
| remixPrompt | string | 否 | 延展区域提示词 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "direction": 1,
  "scale": 1.5,
  "remixPrompt": "向右延展出一片草地"
}
```

---

### 1.6 扩图（Outpaint）

**POST** `/api/v2/open/mj/v1/tob/outpaint`

在原图四周外扩生成更大的画面。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| scale | number | 是 | 扩展比例（1.1-2.0） |
| remixPrompt | string | 否 | 扩图区域提示词 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "scale": 2.0
}
```

---

### 1.7 区域重绘（Inpaint）

**POST** `/api/v2/open/mj/v1/tob/inpaint`

通过蒙版指定区域进行局部重绘。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| mask | object | 是 | 蒙版定义（`areas` 坐标区域，或 `url` 蒙版图，二选一） |
| remixPrompt | string | 否 | 重绘区域描述 |
| callback | string | 否 | 异步回调地址 |

**mask 对象结构**（`areas` 与 `url` 二选一）：

| 字段 | 类型 | 说明 |
|------|------|------|
| areas | array | 坐标区域列表，每个元素含 `width`、`height` 与 `points`（多边形顶点坐标数组，按 `x1,y1,x2,y2,...` 顺序排列） |
| url | string | 蒙版图片 URL（黑白蒙版，白色为重绘区域） |

#### 请求示例

坐标区域方式：

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "mask": {
    "areas": [
      {
        "width": 100,
        "height": 100,
        "points": [10, 10, 10, 100, 100, 100, 100, 10]
      }
    ]
  },
  "remixPrompt": "把这个区域换成一束鲜花"
}
```

蒙版图方式：

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "mask": { "url": "https://example.com/mask.png" },
  "remixPrompt": "把这个区域换成一束鲜花"
}
```

---

### 1.8 重塑（Remix）

**POST** `/api/v2/open/mj/v1/tob/remix`

以新的提示词对指定图片进行重新混合。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| remixPrompt | string | 是 | 新的提示词 |
| mode | int | 否 | 重塑模式：`0` 强烈（默认） / `1` 细微 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "remixPrompt": "改为赛博朋克风格",
  "mode": 0
}
```

---

### 1.9 编辑（Edit）

**POST** `/api/v2/open/mj/v1/tob/edit`

在指定画布与图像位置上对图片进行编辑。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| canvas | object | 是 | 画布尺寸 |
| imgPos | object | 是 | 图像位置 |
| remixPrompt | string | 是 | 编辑描述 |
| mask | object | 否 | 原图重绘区域 |
| callback | string | 否 | 异步回调地址 |

**canvas 对象结构**：

| 字段 | 类型 | 说明 |
|------|------|------|
| width | int | 画布宽度（像素） |
| height | int | 画布高度（像素） |

**imgPos 对象结构**（原图在画布中的位置与尺寸）：

| 字段 | 类型 | 说明 |
|------|------|------|
| width | int | 图像宽度（像素） |
| height | int | 图像高度（像素） |
| x | int | 水平偏移（相对画布左上角，像素） |
| y | int | 垂直偏移（相对画布左上角，像素） |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "canvas": { "width": 1024, "height": 1024 },
  "imgPos": { "width": 1024, "height": 768, "x": 0, "y": 0 },
  "remixPrompt": "在顶部补充天空"
}
```

---

### 1.10 高级编辑（Upload Paint）

**POST** `/api/v2/open/mj/v1/tob/upload-paint`

直接上传图片 URL 并指定蒙版、画布、图像位置进行编辑（无需源任务）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| imgUrl | string | 是 | 待编辑图像 URL |
| mask | object | 是 | 蒙版定义（结构见「区域重绘」的 mask） |
| canvas | object | 是 | 画布尺寸（结构见「编辑」的 canvas） |
| imgPos | object | 是 | 图像位置（结构见「编辑」的 imgPos） |
| remixPrompt | string | 是 | 编辑描述 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "imgUrl": "https://example.com/source.jpg",
  "mask": { "url": "https://example.com/mask.png" },
  "canvas": { "width": 1024, "height": 1024 },
  "imgPos": { "width": 1024, "height": 1024, "x": 0, "y": 0 },
  "remixPrompt": "把背景替换为海滩"
}
```

---

### 1.11 转绘（Retexture）

**POST** `/api/v2/open/mj/v1/tob/retexture`

保留原图结构，按目标风格重新生成材质/纹理。可在 `remixPrompt` 中配合 `--sref 风格图URL` 实现更精确的风格迁移。转绘需使用 v6.1 及以上版本模型。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| imgUrl | string | 是 | 待转绘图像 URL |
| remixPrompt | string | 是 | 目标风格描述 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "imgUrl": "https://example.com/source.jpg",
  "remixPrompt": "改为大理石材质"
}
```

---

### 1.12 移除背景（Remove Background）

**POST** `/api/v2/open/mj/v1/tob/remove-background`

移除图片背景，输出透明背景图。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| imgUrl | string | 是 | 待处理图像 URL |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "imgUrl": "https://example.com/source.jpg"
}
```

---

### 1.13 增强（Enhance）

**POST** `/api/v2/open/mj/v1/tob/enhance`

对指定图片进行细节增强。仅适用于 **草图模式（`--draft`）** 生成的图像。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源任务 ID |
| imageNo | int | 是 | 源图片编号（1-4） |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1
}
```

---

## 二、视频生成接口

### 2.1 图生视频（Video Diffusion）

**POST** `/api/v2/open/mj/v1/tob/video-diffusion`

由图片生成视频。支持两种首图来源，二者二选一：

- **派生模式**：引用已生成图片任务的 `jobId` + `imageNo`（`1`-`4`），系统自动以该图作为视频首帧；
- **链接模式**：在 `prompt` 中直接提供图片链接。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 条件 | 源图片任务 ID（派生模式，与 `prompt` 中的图片链接二选一） |
| imageNo | int | 否 | 源图片编号 `1`-`4`（搭配 `jobId` 使用，指定以哪张图作为首帧） |
| prompt | string | 条件 | 提示词；链接模式下需在其中包含图片链接 |
| videoType | int | 否 | 视频分辨率：`0` 为 480p（默认） / `1` 为 720p |
| callback | string | 否 | 异步回调地址 |

> 单次生成时长为 5 秒。视频比例跟随首帧图片比例，常见对应关系：

| 原图比例 | 视频比例 | 分辨率示例 |
|----------|----------|-----------|
| 1:1 | 1:1 | 624×624 |
| 4:3 | 77:58 | 720×544 |
| 2:3 | 2:3 | 512×768 |
| 16:9 | 91:51 | 832×464 |

> 720p（`videoType=1`）的费用约为 480p 的 3.2 倍，实际以计费方案为准。

#### 请求示例

派生模式（引用已生成图片）：

```json
{
  "jobId": "task_20260529150000_abc12345",
  "imageNo": 1,
  "prompt": "让画面中的人物缓缓转身",
  "videoType": 1
}
```

链接模式（prompt 中带图片链接）：

```json
{
  "prompt": "https://example.com/source.jpg 让画面中的人物缓缓转身",
  "videoType": 0
}
```

#### 响应示例

```json
{
  "jobId": "task_20260529160000_def67890",
  "comment": "JobStatusCreated",
  "videoUrls": [],
  "cost": 0
}
```

---

### 2.2 视频延长（Extend Video）

**POST** `/api/v2/open/mj/v1/tob/extend-video`

在已生成视频的基础上继续延长内容。每次延长增加 4 秒，最多可延长 4 次（即最长约 21 秒：5 + 4×4）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源视频任务 ID |
| videoNo | int | 是 | 视频编号 |
| prompt | string | 是 | 延长部分描述 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529160000_def67890",
  "videoNo": 0,
  "prompt": "人物继续向前走入森林"
}
```

---

### 2.3 视频高清（Video Upscale）

**POST** `/api/v2/open/mj/v1/tob/video-upscale`

对已生成视频进行高清放大处理，输出 1080P 视频（按视频时长计费）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 源视频任务 ID |
| videoNo | int | 是 | 视频编号 |
| callback | string | 否 | 异步回调地址 |

#### 请求示例

```json
{
  "jobId": "task_20260529160000_def67890",
  "videoNo": 0
}
```

---

## 三、任务查询接口

### 3.1 查询任务信息

**GET** `/api/v2/open/mj/v1/tob/job/{jobId}`

查询单个任务的状态与结果，用于轮询。

#### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| jobId | string | 是 | 任务 ID |

#### 响应示例

**处理中**
```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusRunning",
  "text": "一只可爱的橘猫在阳光下打盹，油画风格",
  "urls": [],
  "cost": 0,
  "createdAt": "2026-05-29T15:00:00+08:00"
}
```

**成功（图片）**
```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusSuccess",
  "text": "一只可爱的橘猫在阳光下打盹，油画风格",
  "urls": [
    "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/29/output_001.png"
  ],
  "cost": 0.6,
  "createdAt": "2026-05-29T15:00:00+08:00",
  "finishedAt": "2026-05-29T15:01:30+08:00"
}
```

**成功（视频）**
```json
{
  "jobId": "task_20260529160000_def67890",
  "comment": "JobStatusSuccess",
  "videoUrls": [
    "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/29/output.mp4"
  ],
  "cost": 1.2,
  "createdAt": "2026-05-29T16:00:00+08:00",
  "finishedAt": "2026-05-29T16:03:30+08:00"
}
```

**失败**
```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusFail",
  "reason": "生成失败",
  "cost": 0,
  "createdAt": "2026-05-29T15:00:00+08:00",
  "finishedAt": "2026-05-29T15:00:40+08:00"
}
```

> 任务失败时 `comment` 为失败类状态，`reason` 字段给出脱敏后的失败原因，已冻结金额会自动退还。

---

## 任务状态

生成类接口返回的 `comment` 字段及查询接口的 `status` 字段使用以下状态值：

| 状态值 | 说明 |
|--------|------|
| JobStatusCreated | 已创建 |
| JobStatusQueued | 排队中 |
| JobStatusRunning | 执行中 |
| JobStatusSuccess | 成功 |
| JobStatusFail | 失败（未知错误） |
| JobStatusError | 执行报错 |
| JobStatusReject | 图片审核未通过 |
| JobStatusTextReject | 文本审核未通过 |
| JobStatusBadPrompt | 提示词格式错误 |
| JobStatusInvalidParameter | 提示词格式错误，请重试 |
| JobStatusTimeout | 任务失败（超时） |
| JobStatusRequestTimeout | 任务处理失败（超时） |
| JobStatusInvalidImagePromptLink | 无效图片链接 |
| JobStatusMaxConcurrentLimited | 达到同时任务数上限 |
| JobStatusCreditNotEnough | 任务额度已用完 |
| JobStatusCanceled | 任务已取消 |
| JobStatusImagePromptDenied | 图片 prompt 敏感 |
| JobStatusDuplicateImage | 存在重复图片 |

---

## 回调通知

创建任务时若提供了 `callback`，任务完成（成功或失败）后系统会向该地址发送 POST 请求，请求体为任务对象（结构与「查询任务信息」一致）。

**Headers**
```
Content-Type: application/json
```

**Body 示例**
```json
{
  "jobId": "task_20260529150000_abc12345",
  "comment": "JobStatusSuccess",
  "urls": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
  "cost": 0.6,
  "createdAt": "2026-05-29T15:00:00+08:00",
  "finishedAt": "2026-05-29T15:01:30+08:00"
}
```

回调接收端应返回 HTTP 200 表示已成功接收。

---

## 错误码

| code | message | 说明 |
|------|---------|------|
| 400 | Invalid_Argument | 请求参数无效 / 源任务不存在 |
| 402 | Account_Fee_Not_Enough | 账户余额不足 |
| 500 | Internal_Server_Error | 服务器内部错误 |

---

## 最佳实践

### 1. 任务轮询策略

生成类接口为异步任务，需通过「查询任务信息」（`GET /job/{jobId}`）轮询结果。建议轮询间隔：

- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

当 `comment` 为 `JobStatusSuccess` 时从 `urls` / `videoUrls` 获取结果；为失败类状态时停止轮询。

### 2. 处理时间参考

- 图像生成 / 编辑类：通常 30 秒 ~ 2 分钟
- 图生视频：通常 1 ~ 5 分钟
- 视频延长 / 视频高清：通常 1 ~ 3 分钟

### 3. 余额管理

- 创建任务时会预扣（冻结）费用，余额不足将返回 `402 Account_Fee_Not_Enough`。
- 任务成功后从冻结金额中实际扣费，`cost` 字段反映实际消耗。
- 任务失败后冻结金额会自动退还。

### 4. 二次操作

- 变化 / 放大 / 延展 / 扩图 / 区域重绘 / 重塑 / 编辑 / 增强等接口均需引用一个有效的源任务 `jobId`，并通过 `imageNo` 指定具体图片。
- 视频延长 / 视频高清需引用已成功的视频任务 `jobId` 与 `videoNo`。

### 5. 回调优先

- 建议优先使用 `callback` 接收任务完成通知，减少轮询开销；轮询作为兜底手段。