MiniMax H3-Image API: So generierst und bearbeitest du Bilder

Die MiniMax H3-Image API erzeugt und bearbeitet Bilder über zwei REST-Endpunkte: POST /v1/images/generations für Text-zu-Bild und POST /v1/images/edits für Bearbeitungen mit 1 bis 16 Referenzbildern. Sie senden einen Bearer-Key, die Modell-ID MiniMax-H3-Image (oder MiniMax-H3-Image-Highspeed), einen Prompt und eine Größe und erhalten Bild-URLs oder Base64-Daten zurück. Die API läuft auf derselben MiniMax-Entwicklerplattform wie die MiniMax M3 API. Die Ausgabe erreicht bis zu etwa 16 Megapixel ohne Upscaler.

Unten: der API-Key, die relevanten Felder, Bildbearbeitung, Preise inklusive Einführungsrabatt und ein agentengestützter Test mit der Apidog CLI. Neu beim Modell? Beginnen Sie mit Was ist MiniMax H3-Image?.

Was ist die MiniMax H3-Image API?

Die MiniMax H3-Image API ist MiniMax’ gehosteter Endpunkt für das Open-Weight-Modell H3-Image, das Text-zu-Bild-Generierung und Bildbearbeitung mit mehreren Referenzen in einem einzigen Checkpoint vereint. Er ist unter https://api.minimax.io erreichbar, nimmt JSON-Anfragen entgegen und ist mit den images.generate- und images.edit-Aufrufen des OpenAI SDKs kompatibel – bestehender Bildcode braucht also meist nur eine neue Base-URL und einen neuen Modellnamen.

Die Gewichte sind ebenfalls öffentlich: Die Modellkarte auf Hugging Face listet einen Diffusion Transformer mit 33,1 Mrd. Parametern unter der MiniMax-H3-Image Community License. Selbst-Hosting erfordert rund 69 GB für den Checkpoint plus einen 66,7-GB-Text-Encoder, daher ist die API für die meisten Teams der praktikable Weg.

Die gehostete Seite, laut MiniMax’ API-Referenz vom 11.11.2026:

Ihren MiniMax-API-Key holen

1. Melden Sie sich auf der MiniMax-Entwicklerplattform an.
2. Öffnen Sie Account Management, dann API Keys, und erstellen Sie einen Key.
3. Laden Sie Guthaben auf. Eine Anfrage ohne Guthaben schlägt mit HTTP 402 und Fehlercode 1008 fehl (unzureichendes Guthaben).
4. Exportieren Sie den Key, sodass Ihr Code und Ihr Agent ihn aus der Umgebung lesen und nie aus einer committeten Datei:

export MINIMAX_API_KEY="your-key-here"

Jeder Aufruf sendet ihn als Authorization: Bearer $MINIMAX_API_KEY.

Ihre erste Text-zu-Bild-Anfrage

Der kleinste sinnvolle Aufruf benötigt model, prompt und entweder eine Größe oder eine Area-Stufe:

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"
  }'

Mit dem OpenAI Python SDK richten Sie base_url auf MiniMax und deaktivieren Retries:

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

Die Zeile max_retries=0 ist wichtig. Der Endpunkt ist nicht idempotent: Der Server beendet einen Job und berechnet ihn ab, selbst wenn Ihr Client das Zeitlimit überschreitet – ein automatischer Retry führt also zu doppelter Abrechnung. Setzen Sie stattdessen ein Timeout von 600 Sekunden.

Anfrageparameter, die wichtig sind

Die Ausgabegröße steuern Sie auf einem von zwei Wegen, und beide lassen sich nicht mischen.

Exakte Pixel. Setzen Sie size auf BREITExHÖHE, zum Beispiel 4096x4096. Die Gesamtfläche muss zwischen 655.360 und 20.000.000 Pixeln liegen, das Seitenverhältnis zwischen 1:3 und 3:1. Senden Sie in diesem Modus weder aspect_ratio noch area – auch nicht als auto –, sonst erhalten Sie einen 400-Fehler.

Stufe plus Verhältnis. Lassen Sie size auf auto und setzen Sie area (1K, 2K oder 4K, Standard 4K) sowie aspect_ratio (beliebiges X:Y von 1:3 bis 3:1). Der Server berechnet die Pixel; 2K bei 16:9 ergibt 2720 x 1536.

Die weiteren Felder:

Zwei Regeln sorgen regelmäßig für Verwirrung. Erstens: Wenn Sie die Prompt-Verbesserung deaktivieren, müssen Sie eine exakte size oder ein explizites aspect_ratio angeben; auto liefert einen 400-Fehler. Zweitens begrenzt b64_json die Gesamtausgabefläche: 20.000.000 Pixel für PNG (ein Bild beliebiger Größe) und 80.000.000 für JPEG oder WebP (vier 4K-Bilder oder zehn 2K-Bilder). Für größere Stapel verwenden Sie URLs.

Laut Modellkarte arbeitet H3-Image bei rund 16 MP am besten: 4096x4096 (1:1), 5472x3072 (16:9) oder 6272x2688 (21:9).

Bilder mit bis zu 16 Referenzen bearbeiten

Die Bearbeitung nutzt dieselben Felder plus ein images-Array. Verweisen Sie in den Eingaben anhand ihrer Position im Prompt („Bild 1“, „Bild 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"])

Der Endpunkt akzeptiert auch multipart/form-data – genau das sendet images.edit des OpenAI SDKs beim Hochladen von Dateien. Limits laut der Edits-Referenz:

• 1 bis 16 Bilder in JPG, PNG, WebP, HEIC oder HEIF
• Jede Seite zwischen 128 und 8.192 Pixeln, Verhältnis von langer zu kurzer Seite maximal 4:1
• Gesamter Request-Body bis zu 64 MiB; base64 verursacht etwa ein Drittel mehr, daher bei großen Eingaben auf öffentliche URLs umsteigen

Antwort lesen und Fehler behandeln

Eine erfolgreiche Anfrage gibt pro angefordertem Bild genau ein data-Element zurück, in der richtigen Reihenfolge:

{
  "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..."
}

Drei Gewohnheiten halten Ihre Integration sauber:

1. Jedes Element auf error prüfen. Der HTTP-Status ist 200, wenn mindestens ein Bild erfolgreich ist – ein 200 bedeutet also nicht, dass alle n Bilder zurückgekommen sind. Wenn jedes Bild fehlschlägt, erhalten Sie stattdessen 402, 422 oder 500.
2. URLs sofort herunterladen. MiniMax garantiert nicht, dass die URL dauerhaft verfügbar bleibt, also kopieren Sie die Datei in Ihren eigenen Speicher.
3. request_id protokollieren. Es ist die Trace-ID, nach der der Support fragt.

Ratenlimits liefern den Status 429. Code 1002 bedeutet, dass Sie das Limit für Bilder pro Minute überschritten haben; jede Anfrage zählt als n Bilder, ein Stapel mit 10 verbraucht also auf einmal 10 Ihres Kontingents.

MiniMax H3-Image Preise und der Einführungsrabatt

Die Abrechnung erfolgt pro Token, und Sie zahlen nur für Bilder, die erfolgreich sind. Laut MiniMax’ Preisseite, gelesen am 11.11.2026:

MiniMax veröffentlicht auch Beispielkosten pro Bild für das Standardmodell:

Highspeed kostet pro Bild etwa das 1,6- bis 2-Fache (0,13001 $ für 4K, 0,06501 $ rabattiert). Die Prompt-Länge verschiebt die Input-Seite, betrachten Sie diese Werte also als Schätzungen.

Einführungsangebot: Bis zum 17. November 2026, 16:00 UTC, gewährt MiniMax 50 % Rabatt auf die Gesamtkosten der Anfrage für beide Modelle, wenn das gelieferte Bild mindestens 16.600.000 Pixel hat. Ein 4096x4096-Bild (16.777.216 Pixel) qualifiziert sich; ein 2K-Bild nicht. Auf der Suche nach kostenlosen Alternativen? Sehen Sie wie Sie MiniMax H3-Image kostenlos nutzen.

Ihren Coding-Agenten mit der Apidog CLI testen lassen

Bild-APIs scheitern still: ein 200 mit der Hälfte der Bilder fehlend, eine Größenregel, die man vergessen hat. Lassen Sie Ihren Coding-Agenten (Claude Code, Codex, Cursor) wiederholbare Tests mit der Apidog CLI erstellen, statt Antworten von Hand zu prüfen.

Einmalige Einrichtung:

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

Geben Sie Ihrem Agenten dann einen Prompt:

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.

Der Agent liest jedes Payload-Schema, validiert sein JSON, erstellt die Ressourcen und führt den Testfall aus:

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 übergibt Ihren Key zur Laufzeit, sodass er nie in einer gespeicherten Datei landet. Der cli-Reporter gibt jede Assertion als bestanden oder fehlgeschlagen aus; json schreibt einen Bericht, den Ihr Agent ausliest. Halten Sie den Test bei 1K: Jeder Lauf ist eine echte, abrechenbare Generierung. Dasselbe Kommando läuft in CI mit -r junit (siehe den Apidog-CLI-CI/CD-Leitfaden und Apidog CLI in Claude Code). Apidogs Free-Plan deckt bis zu 4 Nutzer ab.

Standard oder Highspeed: welche Modell-ID?

Beide IDs nehmen identische Parameter entgegen – der Wechsel ist also nur ein String-Änderung. Verwenden Sie MiniMax-H3-Image für finale Assets und kostenkritische Stapel, und MiniMax-H3-Image-Highspeed für interaktive Vorschauen, bei denen Latenz wichtiger ist als Preis. Die API-Referenz nennt keine Latenzwerte, also messen Sie selbst mit Ihren Prompts. Alternativen vergleichen? Lesen Sie MiniMax H3-Image vs. Nano Banana 2.1, den Nano Banana 2.1 API-Leitfaden oder den GPT Image 2.6 API-Leitfaden.

FAQ

Wie lautet die Modell-ID für MiniMax H3-Image? Verwenden Sie MiniMax-H3-Image für das Standardmodell oder MiniMax-H3-Image-Highspeed für die schnellere, teurere Variante. Beide funktionieren auf /v1/images/generations und /v1/images/edits mit denselben Parametern.

Funktioniert die MiniMax H3-Image API mit dem OpenAI SDK? Ja. Setzen Sie base_url="https://api.minimax.io/v1" und rufen Sie images.generate oder images.edit auf. Setzen Sie max_retries=0, denn Retries erzeugen neue, abrechenbare Generierungen.

Wie viele Referenzbilder kann ich für Bearbeitungen verwenden? 1 bis 16 pro Anfrage, jeweils 128 bis 8.192 Pixel pro Seite, mit einem Request-Body unter 64 MiB insgesamt.

Wie viel kostet ein MiniMax-H3-Image-Bild? MiniMax’ Beispiele beziffern einen Standard-Text-zu-Bild-Aufruf auf etwa 0,022 $ für 1K und 0,069 $ für 4K; 4K ist bis zum 17. November 2026, 16:00 UTC, auf etwa 0,034 $ halbiert.

Warum habe ich einen 200 erhalten, aber weniger Bilder als angefordert? Ein Teilerfolg liefert 200. Fehlgeschlagene Elemente, einschließlich derer, die die Sicherheitsprüfung blockiert hat, enthalten statt einer url ein error-Objekt – und dafür werden Sie nicht abgerechnet.