# Midjourney — /images/generations

Midjourney 图片模型（Beta），默认 V8.2。提示词和参数照 midjourney.com 的写法；一次出一组 4 张 PNG 原图，按次计费，接着放大、变体、Remix、扩图、平移也是同一个接口。

**端点:** `POST https://kovapi.com/v1/images/generations`

## 快速开始

和其他图片接口一样是异步任务：提交得到任务 id，轮询拿结果。下面三步是文生图、查结果、放大第 2 张。

**第 1 步：提交文生图（参数写在提示词末尾）**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'
```

返回（HTTP 202）

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}
```

**第 2 步 · 每 2–3 秒查询一次，直到 `status` 变成 `succeeded` 或 `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

data 是 4 张 PNG 原图（按 1–4 的顺序），actions 是这单接下来能做的动作。

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1795248736,
  "model": "midjourney",
  "data": [
    {"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
    {"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
    {"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
    {"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
  ],
  "usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
  "actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}
```

**第 3 步：接着加工——放大第 2 张（同一个接口，传 task_id、action、index）**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'
```

**完整示例（Python：提交 → 等待 → 保存到本地）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def run(body):
    job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
    if "error" in job:
        raise SystemExit(job["error"]["message"])
    while job["status"] not in ("succeeded", "failed"):
        time.sleep(5)
        job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
    if job["status"] == "failed":
        raise SystemExit(job["error"]["message"])
    return job

# 文生图，再把第 2 张放大
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
    f.write(requests.get(big["data"][0]["url"]).content)
```

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 ID，此处为 midjourney。 |
| prompt | string | 否 | 提示词，Midjourney 参数照官方写法写在末尾（--ar、--v、--niji、--s、--c、--w、--seed、--no、--sref、--oref、--cref、--iw、--raw、--tile、--hd、--draft）。文生图、remix、edit 必填；最多 6000 字符。不支持 --repeat 和 {a, b}。 |
| speed | string | 否 | `relax`（默认，$0.045）、`fast`（$0.055）或 `turbo`（$0.10）。也可以在提示词里写 --relax / --fast / --turbo，这个字段优先。 |
| images | array | 否 | 垫图（image prompt），最多 5 张，图片链接、data: URI 或 base64；放在提示词前面一起交给 Midjourney，可配合 --iw。action 为 blend 时放 2–5 张要融合的图。 |
| size | string | 否 | 比例（如 `3:2`）或像素尺寸，提示词里没写 --ar 时换成 --ar；写了 --ar 以提示词为准。edit 两样都没写时按原图比例。 |
| task_id | string | 否 | 要接着加工的任务 id（img_ 开头，已完成、7 天内）。 |
| action | string | 否 | `upscale`（放大 2 倍，mode subtle / creative）、`vary`（变体，strength strong / subtle）、`remix`（换提示词重塑）、`reroll`（重跑）、`zoom`（向外扩，zoom 1–2）、`pan`（平移，direction）、`inpaint`（局部重绘，mask）；不带 task_id 的 `blend`（融合 2–5 张图）、`edit`（一张图 + 修改说明）。 |
| index | integer | 否 | 处理第几张（1–4）；放大后的单图可以不写。 |
| n | integer | 否 | 只能是 1：一次就是一组 4 张，按一次计费。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址，见下文的 Webhook。 |

## 加工动作（task_id + action）

对一单已完成的任务（7 天内）接着做，和官方 App 的按钮一一对应；结果仍是一单新任务，按所选速度计费。

| action | 要带的字段 | 作用 |
| --- | --- | --- |
| upscale | index, mode | 放大 2 倍：mode `subtle`（默认，细节不变）或 `creative`（会补细节）；交付 1 张。 |
| vary | index, strength | 以第 index 张为基础出 4 张变体：strength `strong`（默认）或 `subtle`。 |
| remix | index, prompt, strength | 保留构图，按新的 prompt 重塑，出 4 张。 |
| reroll | — | 用原提示词整组重跑，出 4 张。 |
| zoom | index, zoom | 向外扩展画面：zoom 1–2（默认 2），出 4 张。 |
| pan | index, direction | 朝 left / right / up / down 延展，出 4 张。 |
| inpaint | index, mask, prompt | 只重画 mask 里白色（或透明）的区域；mask 和原图同比例，会自动缩放到原图尺寸。只有任务结果的 actions 里有 inpaint 时才能用。 |
| blend | images（2–5 张） | 不带 task_id：把 2–5 张图融合成一组 4 张；比例写在 prompt（如 `--ar 3:2`）。 |
| edit | image, prompt | 不带 task_id：上传一张图，用一句话说明怎么改（V8.2 / 8.1），出 4 张；默认保持原图比例，想换比例在 prompt 里写 --ar 或传 size。 |

## 价格

按次计费，一次是一组 4 张（放大是 1 张），加工动作按所选速度同价。--hd（V8 系列）按 2 倍，V7 的 --draft 按半价（向下取整到积分），对 HD 图做变体或重跑也按 2 倍。提交时预扣，失败全额退回。

| 速度 | 积分 / 张 | 美元 / 张 |
| --- | --- | --- |
| 慢速 relax（默认） | 9 | $0.045 |
| 快速 fast | 11 | $0.055 |
| 极速 turbo | 20 | $0.10 |

## 尺寸、版本与限制

- 交付 Midjourney 生成的 PNG 原图（带 Midjourney 自己写入的内容元数据），不裁切、不缩放。尺寸跟比例走：1:1 为 1024×1024、3:2 为 1344×896、16:9 为 1456×816；--hd 和放大是 2 倍。

- 版本：不写为 V8.2，可写 --v 8.1 / 8 / 7 / 6.1 / 6 或 --niji 7 / 6。--hd 只用于 V8 系列，--draft 只用于 V7 和 V8 系列（V8 草图按标准价，可能一次给 24 张）。

- 不支持 --repeat / --r 和 {a, b} 这种一次变多个任务的写法；n 只能是 1。

- 垫图最多 5 张，放在提示词前面交给 Midjourney，可用 --iw 调权重；风格参考用 --sref <图片链接>，V7 的万物参考用 --oref <图片链接>。

- 结果和上传的图片保留 7 天；7 天后的任务不能再加工。

- Describe（图生文）和 Midjourney 视频暂未开放。

## 任务状态与返回字段

`GET /v1/images/jobs/{id}` 返回的状态如下，每个字段的说明见 [异步任务](https://docs.kovapi.com/zh/guide/async-jobs#fields)。建议每 2–3 秒查一次，或者用 Webhook。

| 状态 | 含义 |
| --- | --- |
| queued | 排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 `data[0].url`，计费明细在 `usage`。 |
| failed | 失败。原因在 `error`，预扣的积分已全额退回。 |

同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，图片链接保留 7 天。

## 出图时间

实测（11-21）：慢速和快速出 4 张约 1.5–2 分钟，极速约 1.5 分钟；放大约 2 分钟，扩图、平移约 1.3 分钟；带垫图或 Blend 约 4 分钟。高峰时可能更久。

## 错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://docs.kovapi.com/zh/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | invalid_request | 参考图读不到（链接打不开、不是图片、超过 16MB 等，`message` 写明是第几张、什么原因），`/v1/images/edits` 没带参考图，或请求体不是 JSON 对象、`n` 不是整数。 | 按 `message` 修改后重新提交。 |
| 400 | unsupported_action | 参考图读不到（链接打不开、不是图片、超过 16MB 等，`message` 写明是第几张、什么原因），`/v1/images/edits` 没带参考图，或请求体不是 JSON 对象、`n` 不是整数。 | 按 `message` 修改后重新提交。 |
| 404 | task_not_found | 参考图读不到（链接打不开、不是图片、超过 16MB 等，`message` 写明是第几张、什么原因），`/v1/images/edits` 没带参考图，或请求体不是 JSON 对象、`n` 不是整数。 | 按 `message` 修改后重新提交。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 503 | service_unavailable | 我们这边临时出错，例如保存参考素材失败；`/v1/responses` 暂时无法处理时也返回 503，并带 `Retry-After`。 | 稍后重试。 |

### 任务失败（`status` 为 `failed`）

| code | 什么时候出现 | 怎么办 |
| --- | --- | --- |
| moderation_blocked | 图片：模型方的安全审核拒绝了提示词或参考图（也可能是 `content_policy_violation`）。 | 改写提示词或更换参考图；原样重交通常还会被拒。 |
| upstream_error | 其他失败：自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等，`message` 写明具体情况。 | 通常重新提交就能成功。 |

## 用 Webhook 代替轮询

提交时加上 `callback_url`，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 [Webhook 文档 →](https://docs.kovapi.com/zh/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'
```
