# Midjourney — /images/generations

Midjourney の画像モデル（Beta）。既定は V8.2。プロンプトとパラメータは midjourney.com と同じ書き方で、1 回 4 枚 1 組の PNG オリジナルを 1 回分の料金で生成します。アップスケール、バリエーション、リミックス、ズーム、パンも同じ API です。

**エンドポイント:** `POST https://kovapi.com/v1/images/generations`

## クイックスタート

ほかの画像 API と同じ非同期ジョブです。送信してジョブ id を受け取り、ポーリングで結果を取得します。下の 3 手順は、テキストから画像、結果の取得、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 · `status` が `succeeded` か `failed` になるまで、2〜3 秒ごとに照会**

```
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 枚目をアップスケール（同じ API に 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 | いいえ | 画像プロンプト。最大 5 枚、画像 URL・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`（1〜2 倍ズームアウト）、`pan`（direction）、`inpaint`（mask）。task_id なしの `blend`（2〜5 枚）と `edit`（画像 1 枚＋指示）。 |
| index | integer | いいえ | 何枚目を処理するか（1〜4）。アップスケール後の 1 枚なら省略可。 |
| n | integer | いいえ | 1 のみ。1 回で 4 枚 1 組、1 回分の課金です。 |
| callback_url | string | いいえ | タスク終了時に結果を送る先。下の Webhook の項目をご覧ください。 |

## 加工（task_id + action）

完了したジョブ（7 日以内）を続けて加工します。公式アプリのボタンと 1 対 1 で対応し、結果は新しいジョブとして選んだ速度で課金されます。

| action | 渡すフィールド | 内容 |
| --- | --- | --- |
| upscale | index, mode | 2 倍にアップスケール：mode は `subtle`（既定、細部を保つ）か `creative`（細部を足す）。1 枚を返します。 |
| vary | index, strength | index 番目を元に 4 枚のバリエーション：strength は `strong`（既定）か `subtle`。 |
| remix | index, prompt, strength | 構図を保ったまま新しい prompt に合わせて作り直し、4 枚。 |
| reroll | — | 同じプロンプトで 1 組すべて再生成、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 枚 1 組に。比率は prompt に書きます（例：`--ar 3:2`）。 |
| edit | image, prompt | task_id なし：画像 1 枚と変更内容を 1 文で（V8.2 / 8.1）、4 枚。元画像の比率のまま出力し、変えたいときは prompt に --ar を書くか size を指定します。 |

## 料金

1 回ごとの課金で、1 回は 4 枚 1 組（アップスケールは 1 枚）。加工は選んだ速度の 1 回分と同じ料金です。--hd（V8 系）は 2 倍、V7 の --draft は半額（クレジット単位で切り捨て）、HD 画像のバリエーションや再生成も 2 倍です。送信時に仮押さえし、失敗時は全額戻ります。

| 速度 | 1 枚あたりのクレジット | 1 枚あたりの料金（USD） |
| --- | --- | --- |
| 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}（1 回で複数ジョブになる書き方）は使えません。n は 1 のみです。

- 画像プロンプトは最大 5 枚で、Midjourney と同じくプロンプトの前に置かれます（--iw で重み付け）。スタイル参照は --sref <画像 URL>、V7 のオムニ参照は --oref <画像 URL>。

- 結果とアップロードした画像は 7 日間保存され、それより古いジョブは加工できません。

- Describe（画像からプロンプト）と Midjourney の動画はまだ提供していません。

## タスクの状態と返却フィールド

`GET /v1/images/jobs/{id}` は次のステータスを返します。各フィールドの説明は [非同期タスク](https://docs.kovapi.com/ja/guide/async-jobs#fields) をご覧ください。2〜3 秒ごとに照会するか、Webhook を使ってください。

| ステータス | 意味 |
| --- | --- |
| queued | 順番待ち。`queue_position`（前にあるタスク数）と `eta_seconds`（予想待ち時間）が付きます。 |
| processing | 生成中。 |
| succeeded | 完了。結果は `data[0].url`、課金の内訳は `usage` にあります。 |
| failed | 失敗。理由は `error` にあり、予約したクレジットは全額返金されます。 |

1 つのアカウントで同時に生成できるタスクは 50 件までで、それ以上は送信順に順番待ちになります。15 分たっても始まらないタスクは失敗となり、全額返金されます。タスクの記録は 3 日間、画像のリンクは 7 日間保存されます。

## 生成にかかる時間

実測（11-21）：Relax と Fast で 4 枚約 1.5〜2 分、Turbo 約 1.5 分。アップスケール約 2 分、ズーム・パン約 1.3 分、画像プロンプトやブレンドは約 4 分。混雑時はさらにかかることがあります。

## エラーと返金

送信時のエラーはすぐに HTTP 4xx / 5xx で返り、タスクは作成されず、課金もされません。受け付け後の失敗は照会エンドポイントで報告され、確保額は全額返金されます。すべてのコードは [エラーコード](https://docs.kovapi.com/ja/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 | キーが存在しない・削除された・無効化されているか、アカウントが停止されています。 | コンソールの「API Keys」ページでキーを確認してください。 |
| 402 | insufficient_quota | このリクエストの分を確保するだけの残高がありません。ゲートウェイはまずリクエストにかかりうる最大の費用を確保するため、同時に多くの呼び出しを送ったときにも起こることがあります。 | 一度に多くの呼び出しを送った直後なら、数秒待って再試行してください。そうでなければチャージしてください。 |
| 429 | rate_limit_exceeded | このキーに設定した 1 分あたりのリクエスト数の上限を超えました（直近 60 秒で数えます）。`Retry-After` ヘッダーは付きません。 | 数秒待ってから再試行するか、コンソールでこのキーの上限を引き上げてください。 |
| 503 | service_unavailable | 当サイト側の一時的なエラーです（参照素材の保存に失敗した場合など）。`/v1/responses` が一時的に処理できないときも、`Retry-After` 付きで 503 を返します。 | しばらくしてから再試行してください。 |

### 失敗したタスク（`status` が `failed`）

| code | 発生する場面 | 対処 |
| --- | --- | --- |
| moderation_blocked | 画像：モデル提供元の安全審査がプロンプトまたは参照画像を拒否しました（コードが `content_policy_violation` の場合もあります）。 | プロンプトを書き直すか、参照画像を差し替えてください。そのまま再送信しても、たいてい再び拒否されます。 |
| upstream_error | その他の失敗：自動で再試行しても失敗した、順番待ちが 15 分を過ぎても始まらなかった、上流が理由を示さずに拒否した、などです。具体的な状況は `message` に書かれています。 | たいていは再送信すれば成功します。 |

## ポーリングの代わりに Webhook を使う

送信時に `callback_url` を付けると、タスクが終わった時点で（成功・失敗とも）、照会エンドポイントが返すものとまったく同じ内容をゲートウェイがその URL へ送ります。署名付きで、届かなかった場合は自動で再試行します。コンソールの「設定 → Webhook」で、アカウント全体の送信先を設定することもできます。 [Webhook のドキュメント →](https://docs.kovapi.com/ja/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"}'
```
