# Midjourney 与 Niji API 参数参考

Midjourney 使用本站统一异步接口，不需要提供 Midjourney 账号或执行服务的密钥。所有请求使用 `Authorization: Bearer sk-your-api-key`；JSON 请求同时设置 `Content-Type: application/json`。

本页集中维护字段与协议约束。首次接入可从[快速开始](https://api.hamubox.com/docs/midjourney/quickstart/)阅读；按场景查找[参考图与风格码](https://api.hamubox.com/docs/midjourney/references/)、[变体与放大](https://api.hamubox.com/docs/midjourney/actions/)、[视频生成](https://api.hamubox.com/docs/midjourney/video/)和[常见问题](https://api.hamubox.com/docs/midjourney/faq/)。

:::note[参数支持不等于已开放生成]
可用模型以当前 Key 的 `/v1/models` 为准，操作与档位以实时估价及返回的 `actions` 为准。本页保留完整参数契约，不承诺所有版本、编辑器操作或视频延长都已配置可用价格；不能估价的操作不要提交。本站是第三方接入服务，不是 Midjourney 官方 API。
:::

## 接口与模型

| 用途 | 方法与路径 |
| --- | --- |
| 图片提交 | `POST /v1/image/generations` |
| 图片估价 | `POST /v1/image/generations/estimate` |
| 图片查询 | `GET /v1/image/generations/{task_id}` |
| 视频提交 | `POST /v1/video/generations` |
| 视频估价 | `POST /v1/video/generations/estimate` |
| 视频查询 | `GET /v1/video/generations/{task_id}` |

图片提交包含生成、参考、编辑及后续操作；视频提交包含生成与延长。估价使用相同请求体，不创建生成任务。

图片模型 ID：`midjourney-v6`、`midjourney-v6.1`、`midjourney-v7`、`midjourney-v8.1`、`midjourney-v8.2`、`niji-v6`、`niji-v7`。视频模型 ID：`midjourney-video`。

使用当前 Key 调用 `GET /v1/models` 确认模型权限。某个模型可用不代表它的每个操作、速度和批量档位都已开放；请先估价确认。未配置的档位会拒绝提交，不会自动改成另一种收费模式。这里不使用旧版 `/mj/submit/*` 协议，也不使用同步 `/v1/images/generations`。

## 第一次生成

```json title="midjourney-image-generate.json"
{
  "model": "midjourney-v7",
  "prompt": "A quiet greenhouse at sunrise, soft watercolor illustration",
  "speed": "fast",
  "generation_mode": "standard",
  "aspect_ratio": "3:2",
  "stylize": 100,
  "seed": 0,
  "raw": false,
  "n": 1
}
```

下载[该请求 JSON](https://api.hamubox.com/docs/examples/midjourney-image-generate.json)，将下面命令中的 Key 替换为自己的：

```sh
curl https://api.hamubox.com/v1/image/generations \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @midjourney-image-generate.json
```

保存响应的 `id`，之后每隔约 5 秒查询一次，直至 `status` 为 `completed` 或 `failed`。`queued` / `in_progress` 不是失败，也不要反复 POST。HTTP 200 本身不代表图片已生成。

生成完成后，结果可能先返回 Midjourney 官方 CDN 地址，后台继续转存。
图片响应的 `result_transfer_status`（视频位于 `metadata` 中）表示保存进度；
需要本站长期地址时，可以继续查询至 `stored`。结果编号保持不变，URL 可能更新，
已保存的文件优先返回本站地址。`failed` 的保存状态不等于生成失败。
官方 CDN 可能对服务器下载触发访问验证；遇到这种情况请稍后查询本站地址，
不要重复提交生成请求，以免产生第二次费用。

:::caution[已有客户端的结果下载]
`completed` 不保证文件已经转存到本站。如果客户端只允许本站文件域名，或者服务器无法下载官方 CDN，请继续按保存状态查询，不要仅收到 `completed` 就固定保存第一次返回的 URL。保存状态为 `queued`（排队）、`pending`（保存中）、`stored`（已保存）或 `failed`（保存失败）。保存失败可能在后台补偿后恢复，但不保证最终成功；客户端应设置等待期限并保留已有结果，不要无限轮询。历史任务可能没有此字段，仍按原有结果处理。
:::

```sh
curl https://api.hamubox.com/v1/image/generations/task_example \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

### 基础参数

| 字段 | 说明 |
| --- | --- |
| `model` | 上表中的图片模型 ID |
| `operation` | 默认 `generate`；其它操作见下文 |
| `prompt` | 生成提示词，最多 4000 字符（包含原生尾随参数）。`generate`、`edit`、`retexture`、`region`、`custom_zoom` 必填 |
| `images` | 普通参考图 URL 数组，最多 4 张；在 `generate` 中是参考，不会自动切换为 `edit` |
| `aspect_ratio` | `1:1`（默认）、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9` |
| `speed` | `fast` 或 `relax`。建议明确指定；后续操作省略时优先继承原任务速度 |
| `generation_mode` | `standard`（默认）、`draft`、`hd`，不是速度设置 |
| `stylize` | 整数 0–1000，风格化强度 |
| `chaos` | 整数 0–100，结果差异程度 |
| `seed` | 整数 0–4294967295；`0` 有效 |
| `raw` | 布尔值；启用后减少模型默认审美修饰，并非无审核模式 |
| `negative_prompt` | 排除的内容，等价于 `--no`；最多 4000 字符，不包含其它参数、花括号或控制字符 |
| `image_weight` | 普通参考图权重，0–3；Niji V7 为 0–2，需要同时提供 `images` |
| `tile` | 布尔值，生成可平铺图案 |
| `weird` | 0–3000 的整数，增加非典型审美；不适用于 Niji |
| `n` | 图片任务只能是 `1`，表示一次任务／一组结果，不是仅生成一张图片 |
| `max_cost_usd` | 可选费用上限，0–10000 美元；估价超出上限时拒绝提交 |

`draft` 可用于 V7 / V8.1 / V8.2，`hd` 可用于 V8.1 / V8.2，均只用于 `generate`。Draft 是草稿生成模式，HD 是高清生成模式；它们与 Fast／Relax 分别控制生成方式与队列速度，价格也分别计算。这里不支持 `turbo`。

`negative_prompt`、`image_weight`、`tile` 和 `weird` 首版仅支持 `generate`。后续变体等继承父任务设置，不重新传这些字段。

:::caution[不要混用其它模型参数]
MJ 图片不接受 `size`、`resolution`、`quality`、`image_urls` 等其它图片协议字段。可使用本页的结构化参数或下方列出的原生尾随参数；不支持 `{...}` 排列生成、重复任务和未配置价格的质量／Turbo 档位。
:::

### 原生提示词格式

支持把常见的 MJ 参数放在提示词末尾，仍提交到 **`/v1/image/generations`**，不是另一个同步接口。描述放前面，参数放后面，参数名区分大小写。

```json title="midjourney-image-native.json"
{
  "model": "midjourney-v7",
  "prompt": "A quiet greenhouse at sunrise --v 7 --ar 16:9 --s 150 --chaos 0 --seed 42 --raw --no text, watermark --fast",
  "aspect_ratio": "1:1",
  "speed": "relax",
  "n": 1
}
```

此例实际使用 **16:9、Fast**，而不是 JSON 中的 1:1、Relax。估价和提交都会先解析相同的尾随参数，再按生效的规格计费。

| 原生写法 | 对应结构化字段 |
| --- | --- |
| `--ar` / `--aspect` | `aspect_ratio` |
| `--s` / `--stylize`，`--c` / `--chaos`，`--seed` | `stylize`、`chaos`、`seed` |
| `--raw` / `--style raw` | `raw: true` |
| `--no`，`--iw`，`--tile`，`--w` / `--weird` | `negative_prompt`、`image_weight`、`tile: true`、`weird` |
| `--sref`，`--sw`，`--sv` | 风格参考图／数字风格码、风格权重和版本 |
| `--cref`，`--cw` | 角色参考图和权重 |
| `--oref`，`--ow` | Omni Reference 和权重 |
| `--p` / `--profile` | `profile_codes`，需提供明确的共享代码 |
| `--draft`，`--hd`，`--sd` | `generation_mode`；`--sd` 对应 `standard` |
| `--fast`，`--relax` | `speed` |
| `--zoom` | `zoom`，仅用于 `custom_zoom` |
| `--v` / `--version`，`--niji` | 只核对版本，必须与 `model` 一致，不会替换已选择的模型 |

- 优先级：**尾随参数 > 对应 JSON 创作参数 > 默认值**。同一普通参数重复时以最后一次为准；同时出现 Fast／Relax，或多个不同的生成模式，会明确报错。
- 参考素材可放在文本开头，例如 `https://example.com/a.png https://example.com/b.png a garden --ar 16:9`。这些 URL 会替换 JSON 的 `images`，仍受参考图数量和下载校验限制。
- `--sref` 会整体替换 `style_references` 和 `style_codes`，支持同一参数下用空格分隔图片 URL 与数字风格码；`--cref`、`--oref`、`--p` 也替换各自对应的参考内容。平台工作台同时带有情绪版选择时，明确的 `--p` 优先。
- 参数覆盖不会改变模型权限、`n: 1`、父任务归属或 `max_cost_usd`。例如 `model: "midjourney-v7"` 搭配 `--v 8.2` 会拒绝；不会按 V7 的价格调用 V8.2。
- 不支持的参数会返回明确的 HTTP 400，而不是悄悄忽略。`--q` / `--quality`、`--turbo`、`--r` / `--repeat`、排列生成、视频命令仍不能使用。其它字段和模型限制仍按本页规定验证；复制官网参数不代表所有官网能力都已开放。
- 空提示词与超过 4000 字符会分别说明原因；只有参数、没有必填的正文描述，也会报错。普通单词或 URL 内的 `--` 不会被当成参数。

原始提示词保留在任务记录中，生成使用解析后的内容。视频接口仍只接受下方列出的结构化参数，不使用此图片解析规则。

### 参考图、风格与角色

参考素材必须是无需登录即可读取的公网 HTTPS 图片 URL，支持 PNG、JPEG、WebP，单张不超过 10 MB。不要求使用平台图床，但链接及其重定向不能指向内网地址，也不能携带登录凭据或使用非标准端口。不支持 `blob:`、本地路径或图片 Data URL。可先使用[素材上传接口](https://api.hamubox.com/docs/references/)取得 URL；`mask` 是下文单独说明的例外。

```json title="midjourney-image-reference.json"
{
  "model": "midjourney-v7",
  "prompt": "A traveler standing in a sunlit greenhouse",
  "speed": "fast",
  "style_references": [
    "https://example.com/style.png"
  ],
  "style_weight": 100,
  "omni_reference": "https://example.com/character.png",
  "omni_weight": 100
}
```

| 字段 | 范围与适用条件 |
| --- | --- |
| `style_references` | 最多 4 张风格参考图 URL |
| `style_codes` | 最多 4 个不重复的纯数字字符串，每个 1–20 位，不包含 `--sref` 前缀；与 `style_references` 合计不超过 4 项 |
| `style_weight` | 0–1000 的整数，必须同时提供风格图片或风格码 |
| `style_version` | 可选。V6 / V6.1：1–4；V7 图片风格参考：1–6，含风格码时仅 4 或 6；其它模型省略 |
| `character_references` | 最多 4 张；仅 V6 / V6.1 / Niji V6 |
| `character_weight` | 0–100 的整数，需搭配角色参考图 |
| `omni_reference` | 单张参考图 URL，仅 V7 的 `standard` 模式 |
| `omni_weight` | 1–1000 的整数，需搭配 Omni Reference |
| `profile_codes` | 最多 4 个不重复的公开个性化／情绪版代码，每个 2–32 位英文字母或数字；不包含 `--p` 前缀 |

风格、角色和 Omni 参数只用于 `generate` 或适用的 `edit`。V8 不接受 `character_references` / `omni_reference`，需要结合图片修改时使用 `edit`。

Omni 的 Fast 和 Relax 分别计价，不沿用普通生图的报价。若返回 `model_price_error`，表示平台尚未配置该操作和速度的有效价格，生成未提交、未扣款；请联系管理员，不要重复提交或改成普通生图来绕过报价。

`profile_codes` 仅用于 Midjourney 的 `generate`，不用于 Niji；支持与 V7 Standard 的 `omni_reference`、`omni_weight` 组合。组合请求沿用对应速度的 Omni 报价，不额外加收个性化费用，不能同时传 `style_weight` 或 `style_version`。不要传 `default`、`global`、`random`，也不要把数字风格码当作个性化代码。代码是否可用仍取决于分享权限与模型兼容性。平台情绪版创建和管理不属于本公共 API 的开放范围。

### 多结果与后续操作

成功任务的 `outputs` 是全部可见结果，不只是第一张。常规图片生成通常返回 4 张，某些模式可能更多或更少，客户端必须遍历数组，不能写死数量。下方是字段节选，不代表固定输出数量：

```json
{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "midjourney-v7",
  "operation": "generate",
  "status": "completed",
  "outputs": [
    { "id": "output_1", "object": "image.generation.output", "url": "https://example.com/result-1.png", "mime_type": "image/png" },
    { "id": "output_2", "object": "image.generation.output", "url": "https://example.com/result-2.png", "mime_type": "image/png" }
  ],
  "actions": [
    { "operation": "variation", "output_index": 0 },
    { "operation": "variation", "output_index": 1 }
  ]
}
```

后续操作仍 POST 图片端点，但传入本站的 `parent_task_id` 和 `actions` 提供的 `operation`、`output_index`。父任务必须属于当前用户且已完成；`model` 必须与父图片任务一致。不要传上游任务 ID 或按钮 `customId`。

```json title="midjourney-image-variation.json"
{
  "model": "midjourney-v7",
  "operation": "variation",
  "parent_task_id": "task_example",
  "output_index": 0
}
```

`output_index` 从 **0** 开始；请直接使用对应动作的值，不要使用图片界面筛选或排序后的下标。`output_1` 对应原始下标 0，`output_2` 对应 1。后续操作返回新的任务 ID，需要另行查询。

| `operation` | 用途 |
| --- | --- |
| `variation` / `vary_subtle` / `vary_strong` | 变体／轻微重绘／较强重绘 |
| `reroll` | 按原始设置重新生成 |
| `upscale_subtle` / `upscale_creative` | 保守放大／创意放大 |
| `zoom_1_5` / `zoom_2` | 向外扩展画面 |
| `pan_left` / `pan_right` / `pan_up` / `pan_down` | 向对应方向扩图 |
| `custom_zoom` | 自定义扩图，另传 `prompt` 和 `zoom`（1–2），可传 `aspect_ratio` |
| `region` | 局部重绘，另传 `prompt` 和 PNG Data URL `mask` |
| `select` | 提取已有单图，不等同于付费重新放大；已取得单图 URL 时无需再次调用 |

**只展示并提交 `actions` 实际返回的操作。** 不同模型、结果阶段和图片可用动作不同；例如某些放大或局部重绘需要先取得单图，不能假设所有四宫格都支持。

```json title="midjourney-image-upscale.json"
{
  "model": "midjourney-v7",
  "operation": "upscale_subtle",
  "parent_task_id": "task_selected_image",
  "output_index": 0,
  "speed": "fast"
}
```

除 `region` / `custom_zoom` 外，后续操作不重新传 `prompt` 或 `aspect_ratio`；也不要传 `images`、`seed`、`raw`、`chaos`、`stylize` 或参考控制参数，这些继承原任务。`mask` 必须是有效 PNG，Data URL 总长度不超过 8 MiB，宽高分别为 1–8192 像素；只允许用于 `region`。

### 编辑、融合与图转提示词

| `operation` | 模型与参数 |
| --- | --- |
| `edit` | V8.1 / V8.2，1–4 张 `images` 和非空 `prompt` |
| `retexture` | V6.1，1 张 `images` 和非空 `prompt` |
| `blend` | 2–4 张 `images`，正方形比例，不传提示词或风格化参数 |
| `describe` | 1 张 `images`，不传提示词或其它生成控制参数 |

```json title="midjourney-image-edit.json"
{
  "model": "midjourney-v8.2",
  "operation": "edit",
  "prompt": "Change the greenhouse into a winter garden, preserve the traveler",
  "images": [
    "https://example.com/source.png"
  ],
  "speed": "fast"
}
```

```json title="midjourney-image-describe.json"
{
  "model": "midjourney-v7",
  "operation": "describe",
  "images": [
    "https://example.com/source.png"
  ]
}
```

`describe` 完成后读取顶层 `descriptions` 字符串数组，通常有多个候选提示词；**不会因此生成四张图片**，也不保证永远有四条描述。客户端应支持没有 `outputs` 的成功任务。选择一条描述再次生成时，另行提交 `generate`，按新任务计费。

## 视频生成与延长

MJ 视频使用 `midjourney-video`，至少需要一张首帧图，不支持仅提示词的纯文生视频。

```json title="midjourney-video-generate.json"
{
  "model": "midjourney-video",
  "images": [
    "https://example.com/start.png"
  ],
  "prompt": "The camera slowly moves forward through the greenhouse",
  "resolution": "480p",
  "speed": "fast",
  "motion": "low",
  "n": 2
}
```

| 字段 | 说明 |
| --- | --- |
| `operation` | `generate`（默认）或 `extend` |
| `images` | 生成时 1–2 张 URL，顺序为首帧、可选尾帧 |
| `prompt` | 可选运动描述，最多 4000 字符，不允许原生参数或排列语法 |
| `resolution` | `480p`（默认，SD）或 `720p`（HD） |
| `speed` | `fast` / `relax`；720p 必须 Fast。480p Relax 也需要当前线路和价格支持 |
| `motion` | `low`（默认）或 `high` |
| `n` | 1（默认）、2 或 4，表示本次视频输出条数；与图片的 `n` 含义不同 |
| `raw` | 可选布尔值 |
| `loop` | 可选布尔值，循环视频；不能同时提供尾帧 |
| `max_cost_usd` | 可选本次任务费用上限 |

初次视频约 5 秒，每次延长约 4 秒，最多延长 4 次。实际编码时长可能略有差异。不接受 `duration`、`seconds`、`aspect_ratio`、`first_frame_url` 或 `reference_video_urls`，不能通过这些字段指定任意时长或上传外部视频进行延长。

查询成功后遍历 `outputs[].url` 获取全部视频；`metadata.url` 兼容提供第一条结果，不代表只有一条。

```json title="midjourney-video-extend.json"
{
  "model": "midjourney-video",
  "operation": "extend",
  "parent_task_id": "task_video_example",
  "output_index": 0,
  "prompt": "Continue the gentle camera movement",
  "resolution": "480p",
  "speed": "fast",
  "n": 1
}
```

延长使用本平台已完成的视频父任务和原始结果下标（0–3），不要传 `images`，也不要开启 `loop`。`resolution` 必须与父任务一致，建议显式填写。每次延长都会创建新任务；再次延长时使用最新任务 ID。达到延长次数上限或父任务缺少必要信息时会拒绝请求。

## 估价、扣费与失败处理

向对应 `/estimate` 端点发送与实际提交完全相同的 JSON（包括速度、模式、批量和父任务），返回顶层 `estimated_cost_usd`（美元）和 `quota`（内部额度单位）。估价不创建任务、不发起生成；不是锁价承诺。

```sh
curl https://api.hamubox.com/v1/image/generations/estimate \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @midjourney-image-generate.json
```

提交时可将接受的最高金额填入 `max_cost_usd`。超出会返回 HTTP 409；需要重新确认价格，不要自动提高限额。正式价格以[模型广场](/pricing)及当前 Key 的实时估价为准，不应把示例中的结果数量当成额外的计费乘数。

- 图片生成按组估价，后续变体、放大等是独立操作；视频批量按完整请求估价，不要再自行重复乘 `n`。
- 模型广场中的 MJ 单位为“次”，表示一次任务。图片的一组通常包含多张结果，并非每张都按页面基础价收费；视频也不是按秒计费，具体金额以规格、批量和操作的估价为准。
- 无法估价的操作或档位不要提交。费用、权限、原任务可用动作都会在提交时重新验证。
- 任务失败读取 `error.message`，费用读取 `usage`；结算与退款说明见[计费文档](https://api.hamubox.com/docs/billing/)。
- 没有结果 URL 时先检查 `status`，不要立即重发。已经生成但正在保存结果的任务应继续查询，不能通过重新生成来修复保存问题。
- 提交断网或超时不代表上游没收到。已获得任务 ID 时只查询该任务；尚未获得 ID 时先核对任务记录，避免重复收费。

可下载本页的[纯文本版本](https://api.hamubox.com/docs/markdown/models/midjourney.md)，或使用包含相同示例的 [OpenAPI](https://api.hamubox.com/docs/openapi.json)。