MiniMax H3-Image APIで画像を生成・編集する方法

MiniMax H3-Image API は、2つのRESTエンドポイントで画像の生成と編集を提供します。テキストから画像を生成する POST /v1/images/generations と、1〜16枚の参照画像を使って編集する POST /v1/images/edits です。Bearer キー、モデルID MiniMax-H3-Image(または MiniMax-H3-Image-Highspeed)、プロンプト、サイズを送ると、画像URLまたはbase64データが返ってきます。MiniMax M3 API と同じ MiniMax 開発者プラットフォーム上で提供されています。アップスケーラーなしで約16メガピクセルまでの出力が可能です。

以下では、APIキーの取得、重要なパラメータ、画像編集、ローンチ割引を含む料金、そして Apidog CLI を使ったエージェントによるテストを紹介します。このモデルに不慣れな方は、まずMiniMax H3-Image とは何かをご覧ください。

MiniMax H3-Image API とは?

MiniMax H3-Image API は、MiniMax のオープンウェイトモデル H3-Image をホスティングするエンドポイントで、1つのチェックポイントでテキストから画像の生成と複数参照画像による編集の両方を処理します。ベースURLは https://api.minimax.io で、JSON リクエストを受け付け、OpenAI SDK の images.generate や images.edit 呼び出しと互換性があるため、既存の画像生成コードはベースURLとモデル名を変えるだけで動作します。

重みも公開されています。Hugging Face のモデルカードによると、33.1Bパラメータの拡散トランスフォーマーが MiniMax-H3-Image Community License の下で公開されています。セルフホスティングにはチェックポイント用に約69GB、テキストエンコーダー用に66.7GBが必要なため、ほとんどのチームにとってはAPIが現実的な選択肢です。

ホスト版の仕様は、MiniMax のAPIリファレンス(2026-11-11時点)によると以下の通りです。

MiniMax API キーの取得

1. MiniMax 開発者プラットフォームにサインインします。
2. アカウント管理を開き、API Keys からキーを作成します。
3. 残高をチャージします。残高がない状態でリクエストすると、HTTP 402 とエラーコード 1008(残高不足)が返されます。
4. キーを環境変数にエクスポートし、コードやエージェントがコミットするファイルからではなく環境から読み取るようにします。

export MINIMAX_API_KEY="your-key-here"

すべての呼び出しで、Authorization: Bearer $MINIMAX_API_KEY としてこのキーを送信します。

最初のテキストからの画像生成リクエスト

最小限の呼び出しには model、prompt、そしてサイズまたはエリアティアのいずれかが必要です。

curl https://api.minimax.io/v1/images/generations \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "response_format": "url"
  }'

OpenAI Python SDK を使う場合は、base_url を MiniMax に向けて、リトライを無効にします。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
    timeout=600,
    max_retries=0,
)

result = client.images.generate(
    model="MiniMax-H3-Image",
    prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
    size="2720x1536",
    response_format="url",
)
for item in result.data:
    print(item.url)  # None for an image that failed

max_retries=0 の行は重要です。このエンドポイントは冪等ではありません。クライアントがタイムアウトしても、サーバー側ではジョブが完了し課金されるため、自動リトライすると二重に課金されます。代わりに600秒のタイムアウトを設定しましょう。

重要なリクエストパラメータ

出力サイズは2つの方法のどちらかで指定でき、混在はできません。

正確なピクセル指定。size に WIDTHxHEIGHT 形式(例:4096x4096)を設定します。合計面積は655,360〜20,000,000ピクセル、アスペクト比は1:3〜3:1の範囲である必要があります。このモードでは aspect_ratio や area を送らないでください。auto であっても送ると400エラーになります。

ティア+比率指定。size を auto のままにし、area(1K、2K、4K、デフォルトは 4K)と aspect_ratio(1:3〜3:1の任意の X:Y)を設定します。サーバーがピクセル数を計算します。16:9 の 2K は2720 x 1536 を返します。

その他のフィールド:

注意すべきルールが2つあります。第一に、プロンプト拡張を無効にした場合は、正確な size または明示的な aspect_ratio を指定する必要があります。auto は400エラーになります。第二に、b64_json は合計出力面積に上限があります。PNG は20,000,000ピクセル(任意のサイズの画像1枚)、JPEG または WebP は80,000,000ピクセル(4K 画像4枚または 2K 画像10枚)です。それより大きなバッチには URL を使用してください。

モデルカードによると、H3-Image は約16MP 前後で最も良好に動作します:4096x4096(1:1)、5472x3072(16:9)、6272x2688(21:9)。

最大16枚の参照画像での編集

編集では同じフィールドに加えて images 配列を使用します。プロンプト内では入力画像を位置で参照します(「image 1」「image 2」など)。

import os, requests

resp = requests.post(
    "https://api.minimax.io/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
        "images": [
            {"image_url": "https://example.com/cat.jpg"},
            {"image_url": "https://example.com/dog.png"},
        ],
        "size": "auto",
        "response_format": "url",
    },
    timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])

このエンドポイントは multipart/form-data も受け付けます。OpenAI SDK の images.edit がファイルをアップロードする際に使う形式です。edits リファレンスによる制限は以下の通りです。

• JPG、PNG、WebP、HEIC、HEIF の画像を1〜16枚
• 各辺は128〜8,192ピクセル、長辺と短辺の比率は4:1以下
• リクエストボディ全体は最大64 MiB。base64 は約3分の1増えるため、大きな入力には公開 URL に切り替えましょう

レスポンスの読み方とエラー処理

成功した呼び出しは、リクエストした画像ごとに順番通りに data 項目を1つ返します。

{
  "data": [
    {"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
    {"error": {"code": "1027", "message": "output image failed content safety check"}}
  ],
  "output_format": "jpeg",
  "usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
  "request_id": "0217..."
}

統合を確実にするための3つの習慣があります。

1. 各項目の error を必ずチェックする。少なくとも1枚の画像が成功していれば HTTP ステータスは200になるため、200が返っても n 枚すべての画像が返ってきたとは限りません。すべての画像が失敗した場合は、代わりに402、422、500が返されます。
2. URL はすぐにダウンロードする。MiniMax によると、URL がずっと利用可能である保証はないため、自分のストレージにファイルをコピーしましょう。
3. request_id を記録する。サポートに問い合わせる際に求められるトレースIDです。

レート制限に達すると429が返されます。コード 1002 は1分あたりの画像数上限を超えたことを意味し、各リクエストは n 枚としてカウントされるため、10枚のバッチは一度にクォータの10を消費します。

MiniMax H3-Image の料金とローンチ割引

課金はトークン単位で、成功した画像に対してのみ支払います。MiniMax の料金ページ(2026-11-11時点)によると:

MiniMax は標準モデルの画像あたりの費用例も公開しています。

Highspeed は画像あたり約1.6〜2倍の費用がかかります(4K は $0.13001、割引価格は $0.06501)。プロンプトの長さによって入力側のコストが変わるため、これらは目安と考えてください。

ローンチオファー:2026年11月17日 16:00 UTC まで、生成された画像が16,600,000ピクセル以上の場合、両モデルのリクエスト総費用が50%割引になります。4096x4096 の画像(16,777,216ピクセル)は対象ですが、2K の画像は対象外です。$0 のルートをお探しですか?MiniMax H3-Image を無料で使う方法をご覧ください。

コーディングエージェントに Apidog CLI でテストさせる

画像 API は静かに失敗します。画像の半分が欠けた200レスポンスや、うっかり忘れたサイズのルールなど。レスポンスを手作業で確認する代わりに、コーディングエージェント(Claude Code、Codex、Cursor)に Apidog CLI で繰り返し実行できるテストを構築させましょう。

まず一度だけセットアップします。

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

その後、エージェントに1つのプロンプトを与えます。

In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.

エージェントは各ペイロードのスキーマを読み、JSON を検証し、リソースを作成してテストケースを実行します。

apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json

--env-var は実行時にキーを渡すため、保存されたファイルに残ることはありません。cli レポーターは各アサーションを合格/不合格として出力し、json はエージェントが読み戻せるレポートを書き出します。テストは 1K にしておきましょう。実行ごとに実際に課金される生成が行われるからです。同じコマンドは -r junit で CI でも実行できます(Apidog CLI CI/CD ガイドと Claude Code での Apidog CLI を参照)。Apidog の Free プランは最大4ユーザーまで利用できます。

Standard か Highspeed か:どちらのモデルIDを使う?

両方のIDは同一のパラメータを受け付けるため、切り替えは文字列を1つ変えるだけです。最終成果物やコスト重視のバッチには MiniMax-H3-Image を、レイテンシが価格に勝るインタラクティブなプレビューには MiniMax-H3-Image-Highspeed を使いましょう。API リファレンスにはレイテンシの数値が記載されていないため、自分のプロンプトで計測してください。代替手段を検討中ですか?MiniMax H3-Image vs Nano Banana 2.1、Nano Banana 2.1 API ガイド、または GPT Image 2.6 API ガイドをご覧ください。

FAQ

MiniMax H3-Image のモデルIDは何ですか?標準モデルには MiniMax-H3-Image を、より高速で高価なバージョンには MiniMax-H3-Image-Highspeed を使用します。両方とも同じパラメータで /v1/images/generations と /v1/images/edits で動作します。

MiniMax H3-Image API は OpenAI SDK で使えますか?はい。base_url="https://api.minimax.io/v1" を設定し、images.generate または images.edit を呼び出します。リトライは新たな課金対象の生成を引き起こすため、max_retries=0 を設定してください。

編集には参照画像を何枚まで使えますか?リクエストあたり1〜16枚で、各画像は128〜8,192ピクセル/辺、リクエストボディ全体は64 MiB 未満である必要があります。

MiniMax H3-Image の画像1枚あたりの費用は?MiniMax の例では、標準のテキストからの画像生成は 1K で約$0.022、4K で約$0.069 です。2026年11月17日 16:00 UTC までの間、4K は半額の約$0.034 になります。

リクエストした枚数より少ない画像が200で返ってきたのはなぜですか?部分的な成功では200が返ります。失敗した項目(安全チェックでブロックされたものを含む)は url の代わりに error オブジェクトを持ち、その分は課金されません。