MAI Image 2.6 API: Bilder erstellen, bearbeiten und abrufen

Bei der ersten Integration von MAI Image 2.6 entscheidest du, welchen Dienstvertrag deine Anwendung verwendet. Microsoft dokumentiert Generierung und Bearbeitung über Foundry. Auf reAPI nutzen beide Vorgänge den Endpunkt zur Bildgenerierung: Ergänze für eine Bearbeitung Referenz-URLs und frage anschließend die zurückgegebene Aufgaben-ID ab. Die Modellnamen ähneln sich, Authentifizierung, Anfragekörper und Antworten sind jedoch nicht austauschbar.^[1]

Diese Anleitung folgt dem reAPI-Vertrag für mai-image-2.6. Beginne mit einer reinen Textanfrage, bevor du Referenzen oder automatische Bildausschnitte ergänzt. So bleibt die Integration bei Fehlern überschaubar. Halte die vollständige Parameterreferenz neben deiner Implementierung bereit. Der MAI Image 2.6 Playground bietet dieselben Einstellungen und aktuelle Schätzungen.^[2]

Das Wichtigste auf einen Blick

• Sende mai-image-2.6 mit einem nicht leeren Prompt an den Bilder-Endpunkt. Eine Anfrage erzeugt ein Bild.^[2]
• Verwende ein Seitenverhältnis mit 1K oder 2K oder ein gültiges Pixelmaßpaar. Dieser Endpunkt akzeptiert kein 4K.^[2]
• Gib für Referenzbearbeitungen bis zu fünf geordnete öffentliche Bild-URLs an. Mit Referenzen bestimmt das Modell die Ausgabemaße.^[2]
• Speichere die Aufgaben-ID und frage sie bis completed oder failed ab. Die Einreichung allein enthält noch kein fertiges Bild.^[2]
• Betrachte den angezeigten Betrag als Schätzung. Nach Abschluss wird die Reservierung abgeglichen; genaue Abrechnungsdaten erhältst du mit ?include=billing.^[2]

Die erste MAI Image 2.6-Anfrage senden

Erstelle einen reAPI-Schlüssel und speichere ihn in deiner Serverumgebung als REAPI_API_KEY. Die Anfrage braucht ein Modell und einen nicht leeren Prompt. Dieses Beispiel fordert ein quadratisches Bild mit expliziten Maßen an, damit sich die gewünschte Bildfläche leicht prüfen lässt. Es ist eine Beispielanfrage und keine Zusage, dass jedes erzeugte Objekt das Briefing perfekt erfüllt.

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer $REAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.6",
    "prompt": "A matte ivory ceramic teapot on a pale blue table, soft daylight, product photography.",
    "width": 1024,
    "height": 1024,
    "n": 1
  }'

Die API-ID enthält vor 6 einen Punkt. Die URL der Modellseite verwendet /models/mai-image-2-6; dieser Slug mit Bindestrichen ist eine andere Zeichenfolge. Speichere die zurückgegebene Aufgaben-id, sobald die Einreichung gelingt. Du brauchst sie zum Abrufen des Ergebnisses, zur Fehlerzuordnung oder zur Wiederherstellung nach einer unterbrochenen Clientverbindung. Eine Anfrage erzeugt ein Bild; ein höheres n ist kein unterstützter Batch.^[2]

Halte den Schlüssel aus Browsercode heraus. Ein Frontend kann das Briefing an dein Backend senden, das den Bearer-Token ergänzt und die Anfrage absendet. Gib je nach Zugriffsdesign deine eigene Auftragskennung oder die Aufgaben-ID an das Frontend zurück. Der Schlüssel gehört weder in Query-Strings noch in Screenshots oder kopierte Fehlerberichte.

Die bereits eingereichte Aufgabe abfragen

Eine erfolgreiche Einreichung bestätigt den Empfang; sie liefert noch kein fertiges Bild. Frage GET /api/v1/tasks/:id ab, bis die Aufgabe completed oder failed meldet. Eine abgeschlossene Aufgabe stellt das Bild unter output.image_urls bereit; bei einem Fehler findest du error. Der ältere Wert usage.credits ist auf ganze Credits gerundet. Für genaue Abrechnung verwende ?include=billing und prüfe billing.credits_exact und billing.cost_usd sowie gegebenenfalls Nachweise über belastete Beträge und Fehlbeträge. Das Abfragen der ursprünglichen Aufgabe startet keine weitere Generierung.^[2]

const taskId = submittedTask.id;
const headers = { Authorization: `Bearer ${process.env.REAPI_API_KEY}` };
const deadline = Date.now() + 5 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://reapi.ai/api/v1/tasks/${encodeURIComponent(taskId)}`,
    { headers },
  );
  if (!response.ok) {
    throw new Error(`Task lookup failed: HTTP ${response.status}; task ${taskId}`);
  }
  const task = await response.json();
  if (task.status === 'completed') {
    console.log(task.output.image_urls, task.usage);
    break;
  }
  if (task.status === 'failed') {
    throw new Error(JSON.stringify({ taskId, error: task.error }));
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

submittedTask bezeichnet hier die geparste Antwort einer erfolgreichen Einreichung. Die Frist von fünf Minuten ist ein Anwendungsbeispiel und keine Latenzgarantie. Bewahre nach ihrem Ablauf taskId auf und zeige an, dass die Anwendung nicht mehr wartet. Bezeichne die Generierung nur als fehlgeschlagen, wenn die Aufgabe einen Fehler meldet. Ein produktiver Client sollte nach der Schleife einen eigenen Timeout-Status zurückgeben und eine erneute Statusabfrage dieser Aufgabe anbieten.

Bei einem Netzwerkfehler nach dem Absenden bleibt offen, ob der Server die Anfrage vor dem Verbindungsabbruch angenommen hat. Automatisches Wiederholen jedes POST kann weitere kostenpflichtige Aufgaben erzeugen. Trenne Einreichung und Statusabfrage und sichere jede zurückgegebene ID vor optionalen UI-Aktionen.

Eine vom Endpunkt akzeptierte Größe wählen

Für eine reine Textanfrage an MAI Image 2.6 verwendest du ein Seitenverhältnis mit einer Auflösungsstufe oder konkrete Maße. Der Endpunkt akzeptiert 1K und 2K, kein 4K. Jede explizit angegebene Seite muss mindestens 768 Pixel lang sein; die Gesamtfläche darf 2.359.296 Pixel nicht überschreiten. Seitenverhältnisse bestehen aus positiven Ganzzahlen und reichen von 1:4 bis 4:1.^[2]

Gemeinsam angegebene Breite und Höhe haben Vorrang vor Pixelmaßen in size; diese haben wiederum Vorrang vor Seitenverhältnis und Auflösung. Verwende möglichst nur eine eindeutige Größenmethode. width: 1024, height: 1024 zusammen mit size: "16:9" beschreibt beispielsweise widersprüchliche Wünsche, auch wenn die dokumentierte Rangfolge die Anfrage auflöst. Dein Formular kann diese Verwirrung vermeiden.

Maße werden auf Vielfache von 32 abgerundet. 1000 × 1000 entspricht nach dieser Regel daher 992 × 992. Wenn dein Layout eine genaue Liefergröße braucht, fordere gültige Vielfache an und prüfe die Maße der heruntergeladenen Datei. Behandle späteres Zuschneiden oder Skalieren als eigenen Anwendungsschritt.^[2]

Von der Generierung zur Referenzbearbeitung wechseln

Ergänze image_urls in der MAI Image 2.6-Anfrage für visuelle Referenzen. Der reAPI-Endpunkt akzeptiert bis zu fünf öffentliche HTTP(S)-Bild-URLs. Der Prompt bleibt erforderlich. Behalte die Reihenfolge bei und erkläre, welches Bild Szene, Motiv oder Stil vorgibt.^[2]

{
  "model": "mai-image-2.6",
  "prompt": "Use the first image as the room and the second as the chair. Replace the chair beside the window. Preserve the floor, window, and camera view.",
  "image_urls": [
    "https://example.com/room.jpg",
    "https://example.com/chair.jpg"
  ],
  "web_grounding": false
}

Ersetze die Beispiel-URLs durch erreichbare Bilddateien, vorzugsweise JPEG oder PNG. Eine URL, die erst nach Anmeldung funktioniert, eignet sich nicht als Referenz für diese Anfrage. Prüfe, dass sie die gewünschten Bilddaten liefert und keinen HTML-Betrachter oder eine abgelaufene Zugriffsseite.

Für Referenzbearbeitung gilt eine andere Größenregel: Das Modell bestimmt die Ausgabemaße; size, resolution, width und height steuern dieses Ergebnis nicht. Referenzen in einer zuvor reinen Textanfrage ändern damit mehr als den visuellen Kontext. Sie ändern auch, welche Bildmaße deine Anwendung zusagen kann.^[2]

Leite aus „den Raum unverändert lassen“ keine Garantie für pixelgenaue Identität ab. Prüfe das bearbeitete Objekt, benachbarte Kanten, Spiegelungen und Details, die erhalten bleiben sollten. Kontrolliere bei Produktabläufen zusätzlich Logos, Beschriftungen und physische Proportionen. Das sind vorgeschlagene Abnahmekriterien; diese Anleitung behauptet keine gemessene Modellgenauigkeit für solche Aufgaben.

Automatischen Bildausschnitt und Webkontext gezielt nutzen

auto_aspect_ratio: true lässt MAI Image 2.6 aus dem Prompt einen Bildausschnitt ableiten, ebenso wie size: "auto". Das hilft beim Erkunden von Kompositionen, eignet sich aber weniger, wenn der nächste Schritt eine feste Bildfläche verlangt. Die automatische Wahl macht auch die Pixelzahl vor Abschluss unsicher.

web_grounding ist ein eigener boolescher Wert mit dem Standard false. Microsoft beschreibt Webkontext als Teil der kreativen Eingaben des Modells. Der Schalter macht jedoch nicht jede dargestellte Beschriftung oder Tatsache verlässlich. Prüfe Informationen, die für das fertige Motiv relevant sind.^[3]

Keiner der Schalter ersetzt einen klaren Prompt. Beschreibe zuerst Motiv, Komposition, Materialien und gewünschte Änderung. Aktiviere dann die zum Briefing passenden Einstellungen. Mit einem Protokoll der gesendeten Werte kannst du später Promptänderungen von Einstellungsänderungen unterscheiden.

Die Schätzung verstehen, bevor du Wiederholungen automatisierst

Die Kosten für MAI Image 2.6 hängen von Eingaben und generierten Pixeln ab. reAPI reserviert beim Einreichen einen geschätzten Betrag und gleicht ihn nach Abschluss ab. Der endgültige Betrag kann niedriger oder höher sein. Referenzbilder und vom Modell gewählte Maße sind Gründe dafür, dass die Schätzung kein fester Preis pro Bild ist.^[2]

Nutze die aktuelle Schätzung auf der Modellseite für deine geplante Anfrage. Die separate Anleitung zu Preisen und Flash erklärt, warum ein quadratisches Bild, eine Referenzbearbeitung und ein breites Bild unterschiedliche Budgetfälle sind. Dieser Artikel schreibt keinen Tarif in Beispielcode fest.

Fehlgeschlagene Generierungen werden nach dem Aufgabenvertrag erstattet. Ein fertiges Bild, das dir nicht gefällt, bleibt eine abgeschlossene Generierung. Plane kreative Wiederholungen deshalb als eigene Aufgaben ein. Notiere akzeptierte Ergebnisse und die benötigten Versuche, damit deine Auswertung die Kosten eines nutzbaren Motivs statt nur einer einzelnen Einreichung vergleichen kann.

Häufige Fragen zur Integration von MAI Image 2.6

Welche Modell-ID muss ich senden?

Sende mai-image-2.6 mit dem Punkt vor 6. Der Seitenslug mai-image-2-6 ist für Website-URLs bestimmt und ist nicht die Modell-ID der Anfrage.^[2]

Kann eine Anfrage mehrere Bilder generieren?

Nein. Dieser Endpunkt unterstützt n: 1. Sende für weitere Versuche eigene Anfragen und rechne jede Aufgabe separat ab.^[2]

Kann MAI Image 2.6 über diesen Endpunkt ein 4K-Bild erstellen?

Nein. Dokumentiert sind 1K und 2K. Explizite Maße müssen mindestens 768 Pixel pro Seite und höchstens 2.359.296 Pixel Gesamtfläche einhalten.^[2]

Warum ignoriert eine Bearbeitung meine Breite und Höhe?

Referenzbilder ändern das Größenverhalten. Das Modell wählt die Bearbeitungsmaße; size, resolution, width und height steuern das Ergebnis nicht mehr. Prüfe die zurückgegebene Datei, bevor du eine Liefergröße zusagst.^[2]

Ist Webkontext erforderlich?

Nein. web_grounding steht standardmäßig auf false. Aktiviere es, wenn Webkontext zum Briefing passt, und prüfe weiterhin dargestellte Fakten und Beschriftungen im fertigen Bild.^[2][3]

Bedeutet ein Timeout bei der Statusabfrage, dass die Generierung fehlgeschlagen ist?

Nein. Die Clientfrist bedeutet nur, dass der Client nicht mehr wartet. Behalte die Aufgaben-ID und frage den Status erneut ab. Die Generierung ist erst fehlgeschlagen, wenn die Aufgabe failed meldet.^[2]

Download-Suchen und Modellwahl

Ein API-Client ist kein herunterladbarer Modell-Checkpoint. Diese Integration ruft einen gehosteten Dienst auf und installiert keine Modellgewichte. Microsoft dokumentiert Foundry-Bereitstellungen für Standardmodell und Flash; diese Anleitungen sind vom reAPI-Endpunkt dieses Artikels getrennt.^[1]

Die Anfrage-ID mai-image-2.6 wählt das Standardmodell MAI Image 2.6. Hänge nicht flash an und setze keinen Bereitstellungsnamen ein, sofern der verwendete Dienst dieses Modell nicht ausdrücklich dokumentiert. Halte für die erste Integration Modell-ID, Endpunkt, Anfragekörper und Antwortparser in einem geprüften Beispiel zusammen. Ergänze alternative Modelle erst nach einer unabhängigen Prüfung ihrer Verträge.

Quellen

1. Microsoft Learn. MAI-Bildmodelle in Microsoft Foundry bereitstellen und verwenden. Abgerufen am 9. Oktober 2026 unter learn.microsoft.com/azure/foundry/foundry-models/how-to/use-foundry-models-mai-image.
2. reAPI. Vertrag für Anfragen, Größen, Statusabfragen und Abrechnung von MAI Image 2.6. Geprüft am 9. Oktober 2026: reapi.ai/docs/mai-image-2-6.
3. Microsoft AI. MAI-Image-2.6. Abgerufen am 9. Oktober 2026 unter microsoft.ai/models/mai-image-2-6.