# Midjourney 图片

> Midjourney 兼容入口：新版 Imagine 与 U/V 工作流，以及无版本头的旧兼容契约。

Base URL：`https://platform.sgt.site/midjourney`

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

所有提交和查询都使用平台虚拟密钥：`Authorization: Bearer YOUR_VIRTUAL_KEY`。JSON 提交另加 `Content-Type: application/json`；查询不需要请求体。先按[地址与鉴权](access.md)设置 `GATEWAY_ORIGIN` 和 `KEY`；以下完整 curl 命令从网关根地址拼接 `/midjourney/v1`，不用再追加本页 Base URL。

虚拟密钥必须属于有消费资格的使用人或应用，并有对应动作模型授权、可用渠道及预算。文生图需要 `mj_imagine`；编辑、混合和基于结果的操作分别检查相应动作权限。查询只读取当前主体拥有的任务，不因提供一个任务 ID 就授予访问权限。

| 方法 | 路径 |
| --- | --- |
| POST | `/v1/generations` |
| POST | `/v1/generations/{action}` |
| GET | `/v1/{id}` |

本页 Base URL 加 `/v1/...` 是平台提供的 Midjourney 兼容入口。旧 `https://platform.sgt.site/mj/...` 路由仍保留。

<a id="native-mj-h-fb49ba64"></a>

## 选择契约

同一组路径按请求头 `X-Heighliner-MJ-Response-Version` 区分两套契约。新接入的企业调用方使用新版工作流；旧兼容契约只为已有客户端保留，不能与新版混用。

| 项目 | 新版工作流 | 旧兼容契约 |
| --- | --- | --- |
| 版本头 | 每次提交和查询都带 `X-Heighliner-MJ-Response-Version: 2026-10-16` | 不带该头 |
| 支持动作 | 文生图、普通 `upscale`（U）、`variation`（V） | 文生图、编辑、混合及全部基于结果的操作 |
| 受理状态码 | HTTP 202 | HTTP 200 |
| 任务 ID | `data.platform_task_id`（平台 ID）；`data.task_id` 只是 Proxy ID，可能为 null | `data.task_id` |
| 后续动作引用源任务 | `source_task_id` 填源任务的平台 ID | `task_id` 填源任务的 `data.task_id` |
| 专用查询 | `GET /v1/{平台 ID}?id_type=platform`，带版本头 | `GET /v1/{task_id}`，不带版本头 |
| 响应包装 | `data` 对象，含 `billing`、`available_actions`、`error` | `data` 对象，含 `status`、`progress`、`image_urls`，失败时 `fail_reason` |
| 请求错误 | `error.code`、`error.message` | `error.message` |
| 幂等重放 | 支持 `Idempotency-Key`，见[幂等键与重试](#native-mj-idempotency) | 不处理 `Idempotency-Key`，没有重放保证 |

两套契约不能互相接续：

- 新版登记的任务不能交给旧动作入口。不带版本头、用 `task_id` 操作新版任务时返回 409 `response_version_required`，应改用新版请求和 `source_task_id`。
- 历史任务不会自动加入新版工作流。带版本头查询未登记的任务返回 404 `task_not_registered`；新版 U/V 也不能以历史任务为源。
- 新版的 `platform_task_id` 不是 Proxy ID，旧查询和旧动作中的 `task_id` 也不能填平台 ID。

<a id="native-mj-h-26f7992f"></a>

## 版本化 Imagine 与 U/V 工作流

新版仅面向企业预算主体，只支持文生图、普通 U 和 V；带版本头调用其他动作返回 400 `operation_not_supported`，版本值不是 `2026-10-16` 时返回 400 `unsupported_response_version`。渠道支持、模型授权和有效价格仍是消费前提。

完整流程：Imagine 提交 → 用平台 ID 查询到 `succeeded` → 从 `available_actions` 选择 U 或 V → 提交子任务 → 用子任务的平台 ID 查询。每一步的请求都完整列在下文，可直接复制并替换示例值。

<a id="native-mj-h-f26907d5"></a>

### 创建可恢复的新任务

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Heighliner-MJ-Response-Version: 2026-10-16' \
  -H 'Idempotency-Key: mj-imagine-order-1001' \
  --data '{"prompt":"A lighthouse by the sea","size":"16:9","speed":"fast"}'
```

`Idempotency-Key` 由调用方为**这一次生成操作**生成并保存，示例值需替换；同一操作的重试沿用它，新的生成使用新值，规则见下文[幂等键与重试](#native-mj-idempotency)。请求字段与旧契约文生图相同（`prompt`、`size`、`version`、`speed`、`metadata`），取值见[旧契约：文生图](#native-mj-section-1)的参数表。示例显式使用 `fast`，原因见[速度与版本](#native-mj-speed-version)。

受理后返回 HTTP 202，响应头带 `X-Heighliner-MJ-Response-Version: 2026-10-16`。下面的任务标识仅为示例：

```json
{
  "data": {
    "task_id": "proxy-task-example",
    "platform_task_id": "task_0123456789abcdef0123456789abcdef",
    "operation": "imagine",
    "speed": "fast",
    "poll_url": "/media/v1/tasks/task_0123456789abcdef0123456789abcdef",
    "status": "queued",
    "progress": "0%",
    "image_urls": [],
    "request_id": "request-example",
    "billing": {"status":"reserved","currency":"CNY","amount":null},
    "metadata": {},
    "available_actions": [],
    "error": null
  }
}
```

| 字段/规则 | 含义 |
| --- | --- |
| `task_id` | Proxy 任务 ID；提交结果不明确时可以为 null，不会被平台 ID 替换。新版的查询和动作都不使用它 |
| `platform_task_id` | 平台在发送上游前持久化的任务身份，用于新版查询和 U/V 的 `source_task_id` |
| `poll_url` | 相对于网关根地址的统一任务查询地址，仍需平台虚拟密钥；响应形状见下文 |
| `status` | `queued/running/succeeded/failed/reconciling`；未成功时不返回完成图片 URL |
| `billing` | 原账务事实。金额未知或只有预留时 `amount=null`，表示尚无可确认金额，不等于 0 元；`"0.000000"` 才是确认的零金额。生成状态不代表账务状态 |
| `source_task_id` | 子任务的父平台任务 ID；文生图根任务不含此字段 |
| `operation`、`speed` | 本次请求的动作及速度 |
| `available_actions` | 本次读取时可识别的真实普通 U/V 按钮，包含 operation、1 起 index、enabled、禁用 reason 和 billing_model；执行时重新校验 |
| `error` | 任务级受控错误，区分提交待核对、生成失败和结果链接不可用，不包含上游私有配置 |

<a id="native-mj-idempotency"></a>

### 幂等键与重试

`Idempotency-Key` 可选，长度 1–255，使用不含空白的可见 ASCII 字符。重放作用域是同一企业、消费主体、虚拟密钥和提交路径；动作之间、虚拟密钥之间不共享。省略该头时，每个请求独立受理。

| 情形 | 请求 | 结果 |
| --- | --- | --- |
| 同一操作重试（超时、断连、进程重启） | 同一键、完全相同的请求体 | 返回原任务（HTTP 202），不再次生成或冻结 |
| 上一次受理仍在进行 | 同一键、同一请求 | 409 `idempotency_in_progress` 和 `Retry-After`，稍后用同一键、同一请求重试 |
| 新的生成，或修改了提示词、比例、速度等任何字段 | 新键 | 独立受理，另行产生任务和费用 |
| 沿用已绑定的键但请求体不同 | 旧键、不同请求 | 409 `idempotency_conflict`，不会受理；改用新键 |

明确生成及账务终态后，重放记录至少保留 24 小时；超出保留期不能再依靠旧键防重，平台任务身份继续保留。

发送后断连、5xx、空响应、无法解析响应、成功响应缺少 ID，或上游任务身份与其他请求冲突时，返回或保留 `reconciling`。内部 Modal 提交同样遵守此保护；准备阶段 ID 不代表最终生成任务。此时查询原平台任务；没有取得平台 ID 时，用**同一键、同一请求**重放以取回原任务。不要换一个新键重新提交来“恢复”结果未知的请求，那会被当作一次新的生成。没有可靠上游 ID 时可能需要人工核对原请求证据；等待超过一小时不会自动退款。生成请求尚未发往上游时（例如本地构造请求失败，或 Modal 前置校验失败），按明确失败返回 `failed` 并释放预留。生成成功但 `error.stage=delivery` 时，费用和生成状态保持原事实。

平台界面在关闭、重新打开或刷新后保留未确认提交的原请求、幂等键和密钥 ID，不保存密钥明文。多个标签页共享恢复保护，选择密钥或打开其他任务不会覆盖未确认请求。首次明确的参数或权限拒绝允许修改后重提；已有未知结果的请求必须继续核对，重试时出现权限拒绝不能证明先前提交失败。超过最短 24 小时重放保障窗口后须先核对记录，不继续重放。取得任务身份后持续查询；即使生成已成功或失败，`billing.status` 仍为 `reserved` 或 `reconciling` 时也不能视为账务完成。延迟结算完成后仍保留至少 24 小时重放记录；明确失败会释放预留，不要求上游进度字段达到 100%。

<a id="native-mj-speed-version"></a>

### 速度与版本

| 字段 | 省略时 | 说明 |
| --- | --- | --- |
| `speed` | `relax` | 可选 `relax/fast/turbo`。新版 U/V 省略时同样为 `relax`；平台界面执行 U/V 时默认沿用源任务所选速度 |
| `version` | `6.1` | 数字版本字符串；提示词中未写 `--v` 时网关追加 `--v <version>`。仅文生图使用，U/V 不接受此字段 |

速度能否使用取决于渠道所用的上游 Midjourney 账号套餐。本页示例显式使用 `fast`，只是为了避开常见的套餐限制，服务端默认仍是 `relax`，也不保证 Fast 或 Turbo 在每个部署都可用。若上游账号不包含 Relax，省略 `speed` 或填写 `relax` 的请求会被上游明确拒绝（例如提示套餐不含 Relax 模式），这不是鉴权失败或网关未接入，改用账号支持的速度即可。

新版最小请求可以省略 `version`。需要指定版本时，在同一请求体中写明：

```json
{"prompt":"A lighthouse by the sea","size":"16:9","version":"7","speed":"fast"}
```

显式版本仍受渠道设置影响。管理员为渠道启用“使用上游默认版本”后，网关在发送上游前移除基础文生图提示词中的数字 `--v` / `--version` 参数（包括由 `version` 字段或默认值追加的部分），实际版本由上游账号决定，不能保证指定版本生效。该设置只作用于基础文生图（新版和旧契约的 `POST /v1/generations`），不影响编辑、混合及 U/V 等基于结果的操作。

<a id="native-mj-h-92fd6830"></a>

### 查询任务与普通按钮

新版专用查询必须同时满足三点：路径填 `data.platform_task_id`，加 `id_type=platform`，带版本头。下例的平台 ID 需替换：

```bash
curl -sS "$GATEWAY_ORIGIN/midjourney/v1/task_0123456789abcdef0123456789abcdef?id_type=platform" \
  -H "Authorization: Bearer $KEY" \
  -H 'X-Heighliner-MJ-Response-Version: 2026-10-16'
```

查询返回 HTTP 200，包装和字段与提交响应相同。成功时节选如下，金额仅为示例：

```json
{
  "data": {
    "task_id": "proxy-task-example",
    "platform_task_id": "task_0123456789abcdef0123456789abcdef",
    "operation": "imagine",
    "speed": "fast",
    "status": "succeeded",
    "progress": "100%",
    "image_urls": ["https://media.example.com/mj-grid.png"],
    "billing": {"status":"settled","currency":"CNY","amount":"0.350000"},
    "available_actions": [
      {"operation":"upscale","index":1,"enabled":true,"billing_model":"mj_upscale"},
      {"operation":"variation","index":1,"enabled":false,"reason":"model_not_authorized","billing_model":"mj_variation"}
    ],
    "error": null
  }
}
```

`queued/running` 时继续查询；`succeeded` 时读取 `data.image_urls[]`；`failed` 时读取 `data.error`；`reconciling` 时继续查询同一平台任务。`available_actions` 只在成功源任务上返回，`enabled=false` 时 `reason` 说明原因（如 `model_not_authorized`、`source_channel_unavailable`）。

`id_type=platform` 不带版本头，或取值不是 `platform` 时返回 400 `invalid_request`。未指定 `id_type=platform` 时，该路径只解释为 Proxy ID，不依次猜测不同类型。当前模型权限或虚拟密钥限制收窄后，新登记任务的其他查询入口也不能绕过检查；额度耗尽但仍有效的密钥可查询和重放已经受理的任务。

`poll_url` 是另一种查询，只提供统一状态、产物、父任务和权威账务：

```bash
curl -sS "$GATEWAY_ORIGIN/media/v1/tasks/task_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $KEY"
```

它的响应是顶层的[平台任务形状](media-tasks.md)（`id`、`status`、`artifacts[]`、`billing` 等），没有 `data` 包装，也不含 `available_actions`。同一段客户端代码不要混用两种响应的解析方式；需要 U/V 按钮时使用专用查询。

只有成功源任务提供对应按钮时才可执行 U/V。一张网格图仍是一个产物，U1/V1 的位置不是 `artifacts[].index`，也不代表已经生成四张独立图片。

<a id="native-mj-h-c2d96d1a"></a>

### 从新源任务执行 U 或 V

U（普通放大）：

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/upscale" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Heighliner-MJ-Response-Version: 2026-10-16' \
  -H 'Idempotency-Key: mj-upscale-order-1001-u1' \
  --data '{"source_task_id":"task_0123456789abcdef0123456789abcdef","index":1,"speed":"fast"}'
```

V（变化）：

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/variation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Heighliner-MJ-Response-Version: 2026-10-16' \
  -H 'Idempotency-Key: mj-variation-order-1001-v1' \
  --data '{"source_task_id":"task_0123456789abcdef0123456789abcdef","index":1,"speed":"fast"}'
```

| 字段 | 说明 |
| --- | --- |
| `source_task_id` | 必填，成功源任务的 `data.platform_task_id`；不能填 Proxy `task_id` 或图片 URL |
| `index` | 必填整数 1–4，对应 `available_actions[].index`，不是从 0 开始 |
| `speed` | 可选 `relax/fast/turbo`，省略时 `relax` |
| `metadata` | 可选对象，不作为业务任务参数或授权依据 |

新版动作只接受上表四个字段，传入旧 `task_id`、原始 `custom_id`、`model` 或 HD 参数返回 400。源任务必须是同一企业、同一消费主体的新版成功任务，且具备对应普通 U/V 按钮。每个 U/V 是独立操作，各自使用自己的幂等键。

受理后返回 HTTP 202，`data` 包装与 Imagine 相同：`platform_task_id` 是子任务的新平台 ID，`source_task_id` 是父任务平台 ID，`operation` 为 `upscale` 或 `variation`。子任务独立处理费用，失败不改变父任务结果；用子任务的平台 ID 按上文专用查询轮询，不要继续查询源任务来等待子任务结果。源渠道、地址或原上游身份失效时拒绝动作（403 `source_channel_unavailable`），不随机换账号。

本期不提供 MJ 的取消、分步补参、归档扩展、签名下载、回调或历史任务导入。U 的实际输出效果及费用应以目标渠道的验收为准，不能把普通 U 宣称为高清放大。

<a id="native-mj-h-8cc08de5"></a>

### 新版错误

新版请求错误的响应体为 `{"error":{"code":"...","message":"...","type":"midjourney_error"}}`，按 `error.code` 判断；源任务按钮不匹配等少数校验的 `error.code` 为空，读取 `error.message`。鉴权和限流错误使用平台通用格式。任务受理后的生成或交付问题不在 HTTP 状态中，而在任务的 `data.error` 中（如 `submission_unknown`、`provider_rejected`、`artifact_unavailable`）。

| HTTP | `error.code` | 含义与处理 |
| --- | --- | --- |
| 400 | `invalid_request` | 字段或取值不合法，或 `id_type` 用法错误；修正请求 |
| 400 | `unsupported_response_version` | 版本头取值不受支持 |
| 400 | `operation_not_supported` | 新版不支持该动作；其他动作只能走旧契约，且不能用于新版任务 |
| 403 | `enterprise_required` | 提交方不是企业预算主体 |
| 403 | `model_not_authorized`、`channel_not_authorized` | 当前授权或虚拟密钥限制不允许访问该任务或渠道 |
| 403 | `source_channel_unavailable` | 源任务的原渠道或上游身份已失效 |
| 404 | `task_not_found` | 任务不存在或不属于当前主体 |
| 404 | `task_not_registered` | 历史任务未登记到新版工作流 |
| 409 | `idempotency_conflict` | 同一幂等键已绑定不同请求；新请求改用新键 |
| 409 | `idempotency_in_progress` | 同键请求受理中；按 `Retry-After` 用同一键、同一请求重试 |
| 409 | `response_version_required` | 用无版本头的旧动作操作新版任务；改用新版请求和 `source_task_id` |
| 415 | `invalid_request` | 提交缺少 `Content-Type: application/json` |

<a id="native-mj-h-11368921"></a>

## 旧兼容契约（无响应版本头）

本节及以下两节是旧兼容契约，只适用于**不带** `X-Heighliner-MJ-Response-Version` 的请求。旧契约以 `data.task_id`（Proxy ID）提交、查询和引用源任务，提交受理返回 HTTP 200，请求错误读取 `error.message`，任务失败读取 `data.fail_reason`。它不处理 `Idempotency-Key`，没有新版的重放保证。

旧动作只能操作旧契约创建的任务，新版任务需按上文的新版请求继续操作。下列示例都不带版本头，不能与新版示例的字段、ID 或查询方式混用。

<a id="native-mj-section-1"></a>

## 旧契约：文生图

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "prompt": "A lighthouse by the sea",
    "size": "16:9",
    "version": "7",
    "speed": "fast"
  }'
```

| 字段 | 说明 |
| --- | --- |
| `prompt` | 必填非空文本 |
| `size` | 默认 `1:1`；正整数比例或 `2048x1152` 等像素尺寸，转换为比例 |
| `version` | 数字版本字符串，默认 `6.1`；以 Midjourney 实际支持为准，渠道启用上游默认版本时不生效，见[速度与版本](#native-mj-speed-version) |
| `speed` | `relax/fast/turbo`，默认 relax；可用速度取决于上游账号套餐 |
| `metadata` | 可选对象，不作为业务任务参数或授权依据 |

新版文生图沿用本表字段。需要授权 `mj_imagine`。基础生成不接受非空 `image_urls`，也不接受 `model/n` 或视频、repeat 标记。提示词的比例、版本、速度标记不能与字段值冲突。

提交成功返回 HTTP 200：

```json
{
  "data": {
    "task_id": "mj_task_example",
    "status": "queued",
    "progress": "0%",
    "image_urls": []
  }
}
```

查询 `GET /v1/mj_task_example`：

```bash
TASK_ID="替换为提交响应 data.task_id"
curl -sS "$GATEWAY_ORIGIN/midjourney/v1/$TASK_ID" \
  -H "Authorization: Bearer $KEY"
```

```json
{
  "data": {
    "task_id": "mj_task_example",
    "status": "succeeded",
    "progress": "100%",
    "image_urls": ["https://media.example.com/mj-result.png"]
  }
}
```

状态 `queued/running/succeeded/failed`。progress 为带百分号字符串；未完成时不返回预览图。失败可能有 `data.fail_reason`；提交阶段的参数或上游拒绝以 HTTP 错误返回，读取 `error.message`。查询读取已有任务，不新增生成或扣费。

<a id="native-mj-section-2"></a>

## 旧契约：图片编辑和基于结果的操作

下表均为不带版本头的 `POST /v1/generations/{操作}`，需要相应动作模型授权、源任务归属和可用渠道。每次操作可能生成新任务和费用。表中的 `task_id` 都是旧契约源任务的 `data.task_id`；新版任务的 U/V 见[从新源任务执行 U 或 V](#native-mj-h-c2d96d1a)。

| 操作 | 必要输入/限制 |
| --- | --- |
| `edits` | `prompt`、恰好一张 `image_urls`；可选 size，不能改变输入图比例 |
| `blend` | 2–4 张 `image_urls`；比例 `1:1/2:3/3:2` |
| `upscale` | 成功源 `task_id`，`index=1..4` 或匹配按钮的 custom_id |
| `variation` | 成功源 task_id，index 或 custom_id |
| `low-variation/high-variation` | 对应成功源任务及可用变化按钮，网格按钮需要 index |
| `reroll` | task_id 及可用重新生成按钮 |
| `pan` | task_id，`direction=left/right/up/down` |
| `zoom` | task_id，`1 < zoom_ratio <= 4` |
| `remix-subtle/remix-strong` | task_id、prompt，网格按钮需要 index |
| `modal` | 成功源 task_id、prompt、mask_url，遮罩尺寸须匹配 |

各操作支持可选 speed、metadata；基于源任务的操作支持匹配已存按钮的 custom_id。缺失必要按钮或前置放大步骤时返回错误，不会自动额外生成。编辑和混合可用 HTTP(S) 图片或 PNG/JPEG/GIF/WebP Data URI。

<a id="native-mj-h-995ec672"></a>

### 编辑已有图片

将 URL 替换为你有权使用且平台可读取的图片，恰好传一张。`size` 可省略；需要填写时必须与原图比例一致。这个入口不需要已有 Midjourney 任务 ID。

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/edits" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "prompt": "Keep the cup and change the background to pale blue",
    "image_urls": ["https://media.example.com/cup.png"],
    "speed": "fast"
  }'
```

<a id="native-mj-h-f053a680"></a>

### 混合两张图片

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/blend" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "image_urls": ["https://media.example.com/cup.png", "https://media.example.com/table.png"],
    "size": "1:1",
    "speed": "fast"
  }'
```

`blend` 不接受 `prompt`，也不能把生成接口的 `version` 或 `model` 带进来。

<a id="native-mj-h-b60de85a"></a>

### 放大成功网格中的第一张图

先查询同一消费主体的源任务，确认 `status: "succeeded"` 且源结果具备可用的放大按钮。用该源任务的 `data.task_id`，不能用图片 URL 或其他协议的任务 ID：

```bash
TASK_ID="替换为已成功且可放大的源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/upscale" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"speed\":\"fast\"}"
```

<a id="native-mj-h-84eff0dc"></a>

### 基于网格生成变化图

`variation` 选择成功网格中的一张图继续生成变化。下例选第一张，源任务必须有与 `index: 1` 对应的变化按钮；`index` 范围是 1–4，不是从 0 开始。

```bash
TASK_ID="替换为已成功的网格源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/variation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"speed\":\"fast\"}"
```

<a id="native-mj-h-f04d822a"></a>

### 轻微变化

`low-variation` 使用较轻的变化强度。下例同样从成功网格的第一张开始，需要对应的变化按钮；不要给普通 `variation` 额外传一个未定义的强度字段。

```bash
TASK_ID="替换为已成功的网格源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/low-variation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"speed\":\"fast\"}"
```

<a id="native-mj-h-2bd1d641"></a>

### 强烈变化

`high-variation` 使用较强的变化强度，源任务条件与轻微变化相同。两种强度分别提交，分别产生新任务及费用。

```bash
TASK_ID="替换为已成功的网格源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/high-variation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"speed\":\"fast\"}"
```

若使用的是已放大的成功单图，且它提供独立的轻微/强烈变化按钮，可以省略 `index`。不能假定任意成功任务都同时提供这两种按钮。

<a id="native-mj-h-3221a042"></a>

### 重新生成

`reroll` 使用源任务的提示词重新生成，需要源任务已经成功且存在可用的重新生成按钮。它是一次新生成，不是查询、恢复或免费重试，不接受 `index` 或新 `prompt`。

```bash
TASK_ID="替换为已成功且可重新生成的源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/reroll" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"speed\":\"fast\"}"
```

<a id="native-mj-h-f2cecbac"></a>

### 向指定方向扩图

先通过 `upscale` 取得成功的单图源任务，再对具备相应方向扩图按钮的结果调用 `pan`。下例向左扩图；其他方向使用 `right`、`up`、`down`。这里填写的是放大后返回的新任务 ID，不是原网格任务 ID。

```bash
TASK_ID="替换为已放大成功且可向左扩图的源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/pan" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"direction\":\"left\",\"speed\":\"fast\"}"
```

<a id="native-mj-h-86200c4f"></a>

### 缩小主体并扩展画布

`zoom` 的 `zoom_ratio` 必须大于 1 且不超过 4。下例使用成功的放大单图扩展为两倍视野，源任务需提供匹配的缩放按钮或自定义缩放按钮。自定义缩放会沿用源提示词；若源提示词已经含有 `--zoom`，先处理冲突，不能重复叠加。

```bash
TASK_ID="替换为已放大成功且可缩放的源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/zoom" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"zoom_ratio\":2,\"speed\":\"fast\"}"
```

<a id="native-mj-h-a7932f96"></a>

### 修改提示词并轻微重混

`remix-subtle` 在变化时使用新的提示词。下例从成功网格的第一张开始，需要对应的变化按钮；`prompt` 必填，`index` 仍为 1–4。若使用提供独立轻微变化按钮的成功单图，可省略 `index`。

```bash
TASK_ID="替换为已成功的网格源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/remix-subtle" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"prompt\":\"Keep the lighthouse composition and change the sky to warm sunset colors\",\"speed\":\"fast\"}"
```

<a id="native-mj-h-2a04e544"></a>

### 修改提示词并强烈重混

`remix-strong` 使用较强的变化强度。下例仍使用成功网格的第一张；成功单图则需要相应的强烈变化按钮。不要把 `remix-subtle` 与 `remix-strong` 当作对同一任务的免费更新。

```bash
TASK_ID="替换为已成功的网格源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/remix-strong" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"index\":1,\"prompt\":\"Reimagine the lighthouse as a futuristic tower beside a calm sea\",\"speed\":\"fast\"}"
```

<a id="native-mj-h-c11ab610"></a>

### 使用遮罩局部重绘

`modal` 需要成功的放大单图、可用的局部重绘按钮、非空 `prompt` 和 `mask_url`。遮罩的宽高必须与源图完全相同；将示例 URL 替换成你有权使用且平台可以读取的真实遮罩。遮罩也可使用受支持的图片 Data URI。它不能通过另传 `size` 改变源图或遮罩尺寸。

```bash
TASK_ID="替换为已放大成功且可局部重绘的源任务 data.task_id"
curl -sS -X POST "$GATEWAY_ORIGIN/midjourney/v1/generations/modal" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"task_id\":\"$TASK_ID\",\"prompt\":\"Replace the selected area with a small blue boat\",\"mask_url\":\"https://media.example.com/mask.png\",\"speed\":\"fast\"}"
```

<a id="native-mj-h-41a4452b"></a>

### 按钮选择与新任务查询

平台从源任务保存的实际按钮中，按动作、`index`、`direction` 或 `zoom_ratio` 选出唯一匹配项。没有匹配项或存在多个匹配项时拒绝，不自动补做放大或其他生成。成功状态本身不保证所需按钮存在。

基于源任务的操作均接受可选 `custom_id`，用于已有客户端明确指定自己保存的真实源按钮。它必须与平台保存的按钮完全相同，且与请求动作及方向/缩放等语义匹配；不能根据任务 ID 自行拼接。本页 GET 响应不返回 `buttons` 或 `custom_id`，没有原按钮值时使用上述选择字段，不能填写示意字符串来绕过前置条件。

上述每次操作都返回一个新的 `data.task_id`，不会覆盖源任务。保存新 ID 并执行同一查询流程：

```bash
TASK_ID="替换为本次操作返回的新 data.task_id"
curl -sS "$GATEWAY_ORIGIN/midjourney/v1/$TASK_ID" \
  -H "Authorization: Bearer $KEY"
```

响应包装、状态与取图方式和文生图相同：`queued/running` 时继续查询，`succeeded` 时读取 `data.image_urls[]`，`failed` 时读取 `data.fail_reason`。不要继续查询源任务来等待新操作结果，也不要把某个动作的参数发送给另一个动作。

<a id="native-mj-h-7248187a"></a>

## 失败与结果未知

参数或源任务条件不满足时先修正请求；没有授权、预算或可用渠道时不会因为换一个任务 ID 而恢复权限。无论哪种契约，提交结果未知都不是重新生成的依据：保存 `X-Oneapi-Request-Id` 和已经取得的任务 ID，有 ID 时查询同一个任务，不要给 curl 加 `--retry` 来重复提交。取得 `image_urls` 后下载时不附带平台虚拟密钥。

| 契约 | 提交超时、断连或 5xx 后 |
| --- | --- |
| 新版工作流 | 有平台 ID 时用专用查询或 `poll_url` 查询该任务；没有时用**同一 `Idempotency-Key`、同一请求**重放取回原任务，不换新键重提。规则与保留期见[幂等键与重试](#native-mj-idempotency) |
| 旧兼容契约 | 不提供客户端幂等重放保证。有 `data.task_id` 时查询该任务；没有时先核对调用记录，不自动重新提交生成请求 |