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

# Midjourney 能力与参数

> 全部接口、提示词参数、后续操作与计费说明

新建任务每个能力一个接口：`POST /midjourney/{接口名}`；加工已有的图统一调 `POST /midjourney/action`，用 `action` 指定做什么。提交后都返回任务 ID，用 `GET /midjourney/task/{task_id}` 查询结果。还没调过的话，先看 [快速上手](https://docs.rixapi.com/docs/cn/guides/midjourney-quickstart.md)。

## 全部接口

所有接口都接受 `notify_hook`（任务结束后推送结果的地址）。除识图外都接受 `speed`（`relax` / `fast` / `turbo`，默认 `fast`）。

### 生成

| 接口 | 能做什么 | 必填 | 可选 |
| - | - | - | - |
| `imagine` | 用提示词生成四张图，可以垫图 | `prompt`（只垫图时可以不写） | `images`（垫图，最多 5 张） |
| `blend` | 把 2 到 5 张图融合成新图 | `images` | `prompt`（只写参数，如 `--ar 16:9`） |
| `describe` | 识图：给出描述这张图的提示词，**同步返回** | `image` | — |
| `edit` | 按文字指令修改一张图，比如换背景、改颜色。只支持 V8.1 及以后，不写版本用 V8.2 | `image`、`prompt` | — |
| `retexture` | 保留原图的构图和结构，按提示词换风格与材质。支持 V7 与 V6 系列，不写版本用 V7 | `image`、`prompt` | — |

### 加工已有的图

统一调 `POST /midjourney/action`：`action` 填下表里的一个，再传 `task_id`（要加工的任务）。作用在某一张图上的，还要传 `index`：第几张，从 1 开始；任务只有一张图时可以不传。

```json theme={null}
{ "action": "variation", "task_id": "mj-0cd1cef934d741b4ab3643ed25515a90", "index": 2, "strength": "subtle" }
```

| `action` | 能做什么 | 必填 | 可选 |
| - | - | - | - |
| `upscale` | 把一张图放大到 2 倍尺寸 | `task_id`、`index` | `type`：`subtle`（默认，忠于原图）/ `creative`（补充更多细节） |
| `variation` | 以一张图为基础生成四张变体 | `task_id`、`index` | `strength`：`strong`（默认，变化大）/ `subtle`（变化小） |
| `remix` | 以一张图为基础，换一段提示词重新生成 | `task_id`、`index`、`prompt` | `strength` |
| `reroll` | 整组重新生成一次 | `task_id` | `prompt`（换一段提示词重跑，不写版本沿用原任务的版本） |
| `zoom` | 向外扩图，画面内容保持在中间 | `task_id`、`index` | `zoom`：1.0 到 2.0，默认 2.0；`prompt` |
| `pan` | 朝一个方向延展画面 | `task_id`、`index`、`direction`（`up` / `down` / `left` / `right`） | `prompt` |
| `inpaint` | 局部重绘：只重画遮罩标出的区域 | `task_id`、`index`、`mask` | `prompt`（重绘区域要画什么） |
| `enhance` | 从草图里挑一张，按完整质量重新生成一组 | `task_id`、`index` | — |

`zoom`、`pan`、`inpaint` 不传 `prompt` 时沿用原任务的提示词；传了但没写版本时，补上原任务的版本。

### 视频

用自己的图做首帧调 `POST /midjourney/video`；用某个任务里的图做首帧、延长视频都算加工，调 `POST /midjourney/action`。

| 写法 | 能做什么 | 必填 | 可选 |
| - | - | - | - |
| `POST /midjourney/video` | 用你的图做首帧，做成约 5 秒的视频 | `image` | `prompt`、`resolution`、`motion`、`batch_size`、`end_image`、`loop` |
| `action` 填 `video` | 用任务里的某张图做首帧 | `task_id`、`index` | 同上 |
| `action` 填 `video-extend` | 把视频再延长约 4 秒 | `task_id`、`index`（第几个视频） | `prompt`、`motion` |

视频的参数见下文 [视频](#视频)。

## 后续操作

查询结果里的 `actions` 列出这个任务接着能做的加工（即 `/midjourney/action` 的 `action` 取值），规则与 Midjourney 网页端一致：

| 任务产出 | 能接着做 |
| - | - |
| 一组图（`imagine`、`blend`、`variation`、`remix`、`reroll`、`zoom`、`pan`、`inpaint`、`enhance`、`edit`、`retexture` 的结果） | `upscale`、`variation`、`remix`、`zoom`、`pan`、`inpaint`、`video`、`reroll`，草图还有 `enhance` |
| 放大后的单张图（`upscale` 的结果） | `variation`、`remix`、`zoom`、`video` |
| 视频（`video`、`video-extend` 的结果） | `video-extend`，最多延长 4 次 |
| 文字（`describe` 的结果） | 无 |

几种图有额外限制：

* **V8 高清图**（`--hd`）：不能放大。扩图、平移、局部重绘按普通分辨率生成。
* **V8.1 / V8.2 的草图**有时一次出 24 张，这种草图批次只能变化、重塑、增强和重跑。
* **V8**（`--v 8`）：只能变化、重塑、做视频和重跑。

另外：

* 只能加工自己账号下、已经成功的任务。任务还没完成时提交会返回 `task_not_finished`。
* `index` 从 1 开始，最大是 `images` 的张数（视频任务是视频的个数）。
* 个别图片没通过内容审核时，`images` 里对应位置是空字符串，其余图片的序号不变，这张图不能再加工。
* 视频不能重跑，想重来就用同样的参数再调一次 `video`。

## 提示词参数

提示词原样交给 Midjourney，在 Midjourney 里能用的参数在这里都能用：`--ar`、`--v`、`--niji`、`--s`、`--c`、`--w`、`--q`、`--seed`、`--no`、`--sref`、`--oref`、`--cref`、`--iw`、`--p`、`--raw`、`--tile`、`--draft`、`--hd` 等。

几条需要知道的规则：

* **速度**：`--relax`、`--fast`、`--turbo` 会被读成 `speed` 参数，不会原样发出。两处都写时以 `speed` 参数为准。
* **版本**：不写版本时补上 `--v 8.2`（Midjourney 现在的默认版本）。
* **不支持** `--repeat`（`--r`）和排列写法 `{a, b}`：它们会把一次请求变成多个任务，请分开提交。
* **视频参数**（`--video`、`--motion`、`--bs`、`--loop`、`--end`）只能在视频接口里用。
* **参考图**：提示词里的图片地址（开头的垫图、`--sref`、`--cref`、`--oref` 后面的地址）要能公网直接下载。地址后面的权重（如 `::2`）不支持，会被去掉。
* 提示词最长 6000 个字符（汉字、字母、空格、标点都算 1 个）。V8 系列的提示词正文（参数前面的文字）在 1024 个字符以内一定能用；更长的会先自动精简再生成，正常写的长描述多半没问题，重复堆砌的内容可能被拒，返回 400 `The prompt is too long, shorten it to under 1024 characters and try again`，不扣费，缩短到 1024 个字符以内即可。

## 图片输入

`images`、`image`、`mask`、`end_image` 都可以传公网能直接下载的图片地址，或 base64（带不带 `data:image/png;base64,` 前缀都可以）。

* 支持 PNG、JPEG、GIF、WebP，单张不超过 20 MB。
* 地址必须是公网地址，内网和需要登录的地址会被拒绝。

**局部重绘的遮罩**：一张黑白图，白色是要重画的区域，黑色保持不变；也可以用透明区域表示要重画的地方。尺寸可以和原图不同，会拉伸到原图尺寸，所以宽高比最好与原图一致。全白或全黑的遮罩会被拒绝，想整张重画请用 `variation` 或 `remix`。

## 视频

首帧有两种给法：

* 用已生成的图：调 `POST /midjourney/action`，`action` 填 `video`，传 `task_id` + `index`。
* 用你自己的图：调 `POST /midjourney/video`，传 `image`。

| 参数 | 取值 | 默认 |
| - | - | - |
| `prompt` | 想要的动作与镜头。不写时，用已生成的图会沿用原任务的提示词，用自己的图则自动决定动作 | — |
| `resolution` | `480p` / `720p` | `480p` |
| `motion` | `low`（动作舒缓）/ `high`（动作幅度大） | `low` |
| `batch_size` | 一次生成几个视频：`1` / `2` / `4` | `1` |
| `end_image` | 尾帧图片，视频会过渡到这张图 | — |
| `loop` | `true` 时首尾帧相同，生成可循环播放的视频。不能和 `end_image` 同时用 | `false` |

延长时调 `POST /midjourney/action`，`action` 填 `video-extend`，传视频任务的 `task_id` 和第几个视频 `index`。延长出来的视频沿用原视频的分辨率和个数，每次加约 4 秒，最多延长 4 次。

视频不支持 `relax` 速度。

## 计费

每次调用按次计费，失败自动退费。各能力按速度分档的单价见模型详情页的价格表，下面这些情况在对应速度的单价上再乘倍率。

**速度**：已经体现在价格表里，慢速是快速的 0.4 倍、极速是 2 倍；视频没有慢速，识图不分速度。

**版本与画质**（`imagine`、`blend`、`edit`、`retexture`，以及 `reroll`）：

| 情况 | 倍率 |
| - | - |
| V7 草图（`--draft`） | 0.5 |
| V8.1 / V8.2 草图（`--draft`） | 先按 1 倍预扣；只出 4 张时按 0.5 倍结算，退回差额；出了 24 张按 1 倍 |
| V8 系列高清（`--hd`） | 2 |
| 其他 | 1 |

**加工已有的图**：

* 对草图做变化、放大、扩图、平移、增强，都按完整质量生成，按 1 倍计费，不再打折。
* 对 V8 高清图做变化 2 倍；`remix` 的新提示词带 `--hd` 也是 2 倍。
* 扩图、平移、局部重绘总是 1 倍（高清图上按普通分辨率生成）。
* 原样 `reroll` 沿用原任务的倍率；换了提示词就按新提示词算。

**视频**：模型详情页列的是 480p、一个视频的价格。`resolution` 为 720p 乘 3.2，`batch_size` 为 2 或 4 分别乘 2 或 4。`video-extend` 按原视频的分辨率和个数计价。

## 错误

错误响应统一是这个形状，HTTP 状态码与错误类型对应：

```json theme={null}
{ "error": { "code": "invalid_request", "message": "index must be between 1 and 4" } }
```

| HTTP | `code` | 含义 |
| - | - | - |
| 400 | `invalid_request` | 参数不对，`message` 会说明是哪一个 |
| 400 | `unsupported_action` | 这个任务不能做这个操作，以查询结果里的 `actions` 为准 |
| 400 | `content_rejected` | 提示词或图片没通过内容审核，未扣费 |
| 401 | `unauthorized` | API Key 缺失或无效 |
| 402 / 403 | `insufficient_quota` | 余额不足 |
| 404 | `task_not_found` | 任务不存在，或不属于当前账号 |
| 404 | `not_found` | 接口名写错了 |
| 409 | `task_not_finished` | 要加工的任务还没成功 |
| 429 | `rate_limited` / `queue_full` | 请求太频繁，或生成队列已满，稍后重试 |
| 5xx | `upstream_error` / `internal_error` | 服务端故障，可以重试 |

## 常见问题

> [accordion] 以前用的 /mj/submit/\* 接口还能用吗？
>
> 能用，已经接好的不需要改。新接入建议用本文的接口：不用再从 `buttons` 里拼 `custom_id`，加工哪张图直接调 `/midjourney/action`，传 `action`、`task_id` 和 `index`；速度也改成了请求参数，不再依赖令牌设置。

> [accordion] 为什么加工时提示 index 超出范围？
>
> `index` 从 1 开始，最大是这个任务 `images` 的张数（视频任务是视频的个数）。放大后的任务只有一张图，`index` 填 1 或者不填。

> [accordion] 草图（--draft）能直接放大吗？
>
> 一组四张的草图可以直接放大，按完整质量计费。也可以先用 `enhance` 按完整质量重新生成一组，再挑一张放大。V8.1 / V8.2 一次出 24 张的草图批次不能放大，要先 `enhance`。

> [accordion] 为什么高清图的 actions 里没有 upscale？
>
> V8 的高清图（`--hd`）本身就是高分辨率，Midjourney 不提供再放大。可以直接变化、扩图或做视频。

> [accordion] 识图返回的描述能直接当提示词吗？
>
> 可以。`describe` 同步返回，结果在 `descriptions` 里，是一段中文描述，拿去调 `imagine` 即可。


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