Midjourney bietet keine offizielle öffentliche API. Wer eine „Midjourney-API“ einbindet, nutzt in der Regel einen Drittanbieter-Wrapper. Pfade, Felder und Zustandsmodelle unterscheiden sich je Anbieter, der Ablauf ist aber ähnlich: Aufgabe senden und ID erhalten, Status abfragen, nach Erfolg das Bild herunterladen und bei Bedarf vergrößern oder Varianten erzeugen. Dieser Beitrag folgt dieser Kette und legt den Schwerpunkt auf typische Stolperstellen und Compliance-Grenzen.

Markenhinweis: Midjourney ist eine Marke von Midjourney, Inc.; Discord ist eine Marke von Discord Inc. Dieser Beitrag dient der technischen Erläuterung und begründet keine Kooperation, Vertretung oder Billigung. Midjourney stellt derzeit keine API bereit; Bedingungen und Stabilität von Drittanbieter-Schnittstellen sind selbst zu prüfen.

1. Erst den Anbieter wählen, dann programmieren

Für Midjourney-Drittanbieter-Schnittstellen gibt es keinen einheitlichen Standard. Beim selben „Aufgabe senden“ liefert der eine task_id, der andere job_id; der eine nutzt /imagine, der andere /v1/midjourney/imagine; manche modellieren Upscale und Varianten als eigene Aufgaben, andere als Aktionsschnittstelle. Vor der Auswahl sind sechs Punkte zu klären:

  • Sind Authentifizierungsart und Base URL stabil, gibt es versionierte Pfade?
  • Welche Aufgabentypen werden unterstützt: Text zu Bild, Upscale, Varianten, Redraw, Blend, Describe?
  • Welche Statusfelder und Endzustände gibt es, werden Erfolg, Fehler, Moderationsablehnung und Timeout unterschieden?
  • Wie lange werden Ergebnisse vorgehalten, welche Download-Limits gelten, werden Callbacks unterstützt?
  • Welche Regeln gelten für Parallelität, Warteschlange und Ratenlimits, werden Fehler berechnet?
  • Wie steht es um Bestand und Ausstieg des Anbieters, sind kurze Verträge und Datenlöschung möglich?

Je näher die Schnittstellenform am bestehenden System liegt, desto geringer sind die Migrationskosten. Nicht nur die Demo ansehen, sondern zuerst Fehlercode-Dokumentation und Aufgabenabfrage prüfen.

2. Authentifizierung und Anfragekonventionen

Üblich ist ein API-Key im Request-Header zusammen mit einem JSON-Body. Das genaue Header-Feld steht in der Anbieterdokumentation; verbreitet sind Authorization: Bearer, X-API-Key oder ein eigenes Feld. Key, Base URL und Timeout gehören in die Konfiguration und nicht verstreut in den Code.

Vor dem Aufruf drei Dinge klären: Test- oder Produktionsumgebung, ob der Key an IP oder Kontingent gebunden ist, und ob die Anfrage über einen Firmen-Ausgangsproxy läuft. Viele 401 und 403 entstehen nicht durch einen falschen Key, sondern durch falsche Umgebung oder einen Proxy, der Header verändert.

3. Aufgabe senden: Prompt und Parameter

Ein typischer Submit-Request sieht so aus; die Felder dienen nur als Beispiel:

export MJ_API_KEY="ihr-anbieter-key"
export MJ_BASE_URL="https://provider.example.com"

curl -sS -X POST "$MJ_BASE_URL/v1/midjourney/imagine" \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "minimalistisches Produktfoto einer Keramiktasse, weiches Fensterlicht --ar 4:3",
    "aspect_ratio": "4:3",
    "callback_url": "https://api.example.com/callbacks/mj"
  }'

Ob Parameter wie --ar, --v und --style im Prompt durchgereicht werden, unterstützen die Anbieter unterschiedlich. Manche trennen das Seitenverhältnis in ein eigenes Feld, andere parsen den Prompt direkt. Nicht annehmen, dass Parameter wirken; nach dem Senden in den Aufgabendetails prüfen.

Nach erfolgreicher Einreichung sofort Aufgaben-ID, Geschäftsnummer, Prompt, Parameter, Einreichzeit und Bearbeiter in die Aufgabentabelle schreiben. Polling, Wiederholungen, Abgleich und Kosten Zuordnung hängen später von diesem Datensatz ab.

4. Polling: Zustandsmodell und Backoff

Status Bedeutung Empfehlung
queued In der Warteschlange Weiter warten, doppeltes Senden vermeiden
running Wird generiert Mit Backoff abfragen
succeeded Erfolgreich Ergebnis lesen und sofort persistieren
failed Fehlgeschlagen Fehlercode erfassen, Wiederholbarkeit prüfen
moderated Moderationsablehnung Prompt ändern, nicht unverändert wiederholen
expired Timeout oder Link abgelaufen Aufgabendetails prüfen, eventuell neu senden

Das Polling beginnt bei 3 bis 5 Sekunden und geht schrittweise auf 15 bis 30 Sekunden zurück; ein Gesamt-Timeout ist Pflicht. Nicht jede Sekunde fest abfragen und nicht mehrere Instanzen dieselbe Aufgabe prüfen lassen. Sobald ein Endzustand erreicht ist, das Polling beenden und Endstatus sowie Ergebnisadresse speichern.

Unterstützt der Anbieter Webhooks, kann dieser die Hauptbenachrichtigung sein. Dann sind Signaturprüfung und Idempotenz nötig, und ein periodisches Polling bleibt als Rückfallebene. Bei Wrapper-Diensten gehen Callbacks durchaus verloren.

5. Download und Persistenz

Die nach Erfolg zurückgegebene Bildadresse ist meist befristet – von wenigen Minuten bis zu Tagen, oft als temporäre Signed URL. Sie darf nicht direkt in eine Frontend-Seite geschrieben oder an Kunden ausgeliefert werden.

Richtig ist: Nach dem Erfolgsstatus sofort herunterladen, in den eigenen Objektspeicher übertragen, Aufgaben-ID, Objektpfad, Dateigröße, Prüfsumme und Downloadzeit erfassen und anschließend die interne Adresse in der Geschäftsdatenbank speichern. Downloads brauchen Timeout, Wiederholungen und Parallelitätsgrenzen; große Bilder sollten über einen serverseitigen Proxy laufen, um CORS-Probleme und Link-Leaks zu vermeiden.

Midjourney liefert üblicherweise ein Vierer-Raster plus die vergrößerten Einzelbilder. Beim Ablegen Raster und Upscales getrennt benennen und die ursprüngliche Aufgaben-ID behalten, damit spätere Varianten oder Redraws zugeordnet werden können.

6. Upscale, Varianten und Redraw

Upscale und Varianten hängen meist von der ursprünglichen Aufgaben-ID und dem Bildindex ab. Üblich ist eine neue Aufgabe mit task_id und index oder ein Aufruf der Aktionsschnittstelle. Ob der Index bei 1 oder bei 0 beginnt, ist nicht einheitlich; vor der Integration mit einer Testaufgabe klären.

Einige Praxisempfehlungen:

  • „Originalaufgabe“ und „abgeleitete Aufgabe“ als Eltern-Kind-Beziehung erfassen, um dasselbe Bild nicht mehrfach zu vergrößern.
  • Varianten können ein neues Vierer-Raster erzeugen; die Kosten werden als neue Aufgabe berechnet. Vor Batch-Läufen kalkulieren.
  • Redraw, Inpainting und Blend werden nicht von jedem Anbieter unterstützt; maßgeblich ist die Dokumentation.
  • Auch vergrößerte Bilder können an die Laufzeit der Upstream-Links gebunden sein; nach Erfolg sofort persistieren.

7. Ratenlimits, Parallelität und Kosten

Der Durchsatz eines Wrapper-Dienstes hängt vom Kontopool und der Upstream-Warteschlange ab und entspricht nicht einfach der gekauften Parallelität. Häufige Grenzen sind Aufgaben pro Minute, gleichzeitig laufende Aufgaben und Tageskontingente pro Konto. Bei 429 die Parallelität senken und exponentiell zurückweichen, nicht blind wiederholen.

Kosten sollten pro „erfolgreich geliefertem Bild“ gerechnet werden, nicht pro Einreichung. Fehler, Moderationsablehnungen, doppelte Einreichungen und Upscale-Varianten gehören in den Nenner, sonst ist der Stückpreis zu niedrig. Zuerst eine kleine Charge laufen lassen, Erfolgsquote und Durchschnittsdauer prüfen, dann schrittweise erhöhen.

8. Häufige Fehler und Diagnose

  • 401: Key fehlt, ist falsch formatiert, gehört zu einer anderen Umgebung oder das Upstream-Konto ist ungültig.
  • 403: IP nicht auf der Whitelist, Kontingent erschöpft, Berechtigung nicht freigeschaltet.
  • 404: Falscher Pfad oder falsche Aufgaben-ID, möglicherweise wurde die Aufgabe bereits bereinigt.
  • 429: Ratenlimit ausgelöst; Parallelität senken und Backoff verwenden.
  • 5xx: Fehler im Upstream oder in der Wrapper-Schicht; mit Idempotenzschlüssel prüfen, ob nichts erzeugt wurde, dann wiederholen.
  • Aufgabe failed: Fehlercode lesen und zwischen Parameter-, Moderations- und Upstream-Fehler unterscheiden.
  • Link 403/404: Ergebnisadresse abgelaufen oder authentifizierungspflichtig; über die Aufgabendetails neu beziehen.

Request-ID, Aufgaben-ID, Fehlercode und maskierte Parameter ins Log schreiben. Fehlermeldungen von Wrapper-Diensten werden oft mehrfach umformuliert; die Originalantwort zu behalten verkürzt die Fehlersuche deutlich.

9. Migrationscheckliste

Beim Wechsel zwischen Anbietern oder von einem eigenen Proxy zu einem Managed Service Punkt für Punkt prüfen:

  1. Werden Base URL, Auth-Header und Pfad vollständig ersetzt?
  2. Stimmen Feldname der Aufgaben-ID, Status-Enum und Endzustandslogik?
  3. Werden Prompt-Parameter durchgereicht oder in Felder zerlegt, wirken --ar und --v?
  4. Sind Aufrufart und Indexregeln für Upscale, Varianten und Redraw identisch?
  5. Sind Gültigkeit der Ergebnislinks, Download-Limits und Persistenzlogik geprüft?
  6. Werden Callbacks unterstützt, sind Signaturprüfung und Idempotenz umgesetzt?
  7. Wurden Ratenlimits, Parallelität, Timeouts und Wiederholungen neu getestet?
  8. Stimmen Abrechnungsmaßstab, Erstattung bei Fehlern und Rechnungsabgleich?

Nach der Migration zuerst eine Charge echter Geschäftsmuster laufen lassen und Erfolgsquote, Durchschnittsdauer und Stückkosten vergleichen, dann vollständig umstellen. Ohne Abgleich und Rollback-Plan nicht auf einmal wechseln.

Häufige Fragen

Liefert die Midjourney-API Bilder synchron?

Meist nicht. Das Senden liefert nur eine Aufgaben-ID; danach wird gepollt oder auf einen Callback gewartet, erst dann folgt der Download. Eine synchrone Auslegung führt leicht zu Timeouts und doppelten Einreichungen.

Wie lange muss typischerweise gepollt werden?

Das hängt von Warteschlange und Upstream-Last ab; üblich sind Sekunden bis mehrere Minuten. Empfohlen: bei 3 bis 5 Sekunden beginnen, schrittweise zurückweichen, ein Gesamt-Timeout setzen und nach dessen Ablauf die Aufgabendetails prüfen statt sofort neu zu senden.

Das unterscheidet sich stark; möglich sind Minuten, Stunden oder Tage. In der Produktion nicht auf Upstream-Links verlassen, sondern nach Erfolg sofort in den eigenen Objektspeicher übertragen.

Wie ruft man Upscale und Varianten auf?

Meist mit ursprünglicher Aufgaben-ID plus Bildindex, entweder als abgeleitete Aufgabe oder über eine Aktionsschnittstelle. Indexstart und Feldnamen unterscheiden sich; mit einer Testaufgabe klären.

Worauf müssen Teams in China achten?

Zuerst Netzwerkerreichbarkeit, Datenausfuhr und Inhalts-Compliance prüfen, dann Anbieterbedingungen und Ausfallrisiko bewerten. Wer einen einheitlichen Eingang braucht, kann sich im ZSQH AI Gateway registrieren und auf der Seite Modellpreise die aktuell unterstützten Modelle prüfen. Bildschnittstellen mit Nicht-OpenAI-Protokoll nicht einfach als kompatibel behandeln.

Nächster Schritt

Zuerst mit einem einfachen Prompt die vier Schritte „senden, pollen, herunterladen, persistieren“ durchlaufen, danach Upscale, Varianten und Callbacks ergänzen. Bei der Anbieterwahl stehen Compliance und Ausstiegsmechanismen vor der Optik. Wer mehrere Modelleingänge zentral verwalten will, kann sich im ZSQH AI Gateway registrieren und auf der Seite Modellpreise verfügbare Modelle und Abrechnung prüfen.

Weitere Beiträge: