Zum Hauptinhalt springen
POST
Diese API arbeitet asynchron. Speichern Sie nach dem Absenden die Aufgaben-ID und fragen Sie Status und Ergebnisse über GET /v1/tasks/{task_id} ab. In der Standardantwort steht die ID unter data[0].task_id.

Anfrageheader

string
erforderlich
Verwenden Sie einen APIMart API Key als Bearer <token>. Absenden und Abfragen erfordern die Authentifizierung mit derselben Benutzeridentität.
string
Dringend empfohlen. Verwenden Sie für jede unabhängige Generierung einen neuen Schlüssel (1–191 sichtbare ASCII-Zeichen; UUID empfohlen). Ersetzen Sie <unique-operation-key> in den Beispielen. Nach einem Timeout oder Netzwerkfehler müssen Endpunkt, Anfragekörper, Antwortversion und Schlüssel beim erneuten Absenden identisch bleiben. Sobald eine Aufgaben-ID vorliegt, fragen Sie nur diese Aufgabe ab.

Anfrageparameter

string
erforderlich
Fester Wert: muse-image-ext.
string
erforderlich
Beschreibung des gewünschten Inhalts. Chinesisch und Englisch werden unterstützt. Nach dem Entfernen äußerer Leerzeichen darf der Text nicht leer sein. Auch mit Referenzbildern erforderlich.
string[]
Bis zu 9 nicht leere Referenzbildeingaben. Unterstützt öffentliche URLs, Data-URIs (z. B. data:image/png;base64,...) und reines base64. Weglassen oder [] für reine Textgenerierung senden. PNG, JPEG und WebP werden empfohlen. URLs müssen ohne Browser-Anmeldecookies direkt vom Server erreichbar sein.Die ursprünglichen Daten aller Referenzbilder dürfen zusammen 11 MiB (11.534.336 Byte) nicht überschreiten. Dies ist die Gesamtgrenze, keine Grenze pro Bild. base64 vergrößert den Anfragekörper zusätzlich. Keine blob:-URLs, lokalen Dateipfade oder File-Objekte senden.
string
Unterstützt die sieben Verhältnisse unten. Ohne Angabe gilt bei Text zu Bild 1:1; mit Referenzbildern folgt das Ergebnis deren Komposition. Ein explizites Verhältnis hat Vorrang. Für automatische Auswahl das Feld weglassen, nicht "auto" senden.1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
string
Kompatibilitätsfeld für die sieben Verhältnisse oben oder auto. Pixelmaße wie 1024x1024 werden nicht unterstützt. Nur size: "auto" entspricht keiner Verhältnisangabe. Bevorzugen Sie aspect_ratio. Sind beide gültig, hat aspect_ratio Vorrang. Beide Felder werden jedoch unabhängig geprüft: Ein gültiges Verhältnis gleicht ein ungültiges size nicht aus.
integer
Standard:"1"
Nur ein Ergebnis pro Anfrage. Erlaubt ist ausschließlich die Zahl 1. Explizite Werte wie 0, negative Zahlen oder Werte über 1 führen zu einem Fehler.
Gibt eine WebP-URL zurück. Das Modell bestimmt die Bildmaße; Pixelgrößen und Stufen wie 1K / 2K / 4K sind nicht wählbar. Senden Sie weder ein nicht leeres resolution noch Zeitfelder.

Weitere optionale Parameter

string
Basis-URL des Backends für Aufgabenbenachrichtigungen. Abschließende Schrägstriche werden entfernt und /callback angehängt, z. B. https://your-backend.example/muse → https://your-backend.example/muse/callback. Bei ausschließlichem Polling weglassen.
string
Sprache der Webhook-Fehlermeldungen, ohne Einfluss auf generierte Inhalte. Unterstützt: zh, en, ja, ko, ru, fr, de, id, pt, es. Regionale Tags wie zh-CN sind nicht zulässig. Beim Polling die Sprache separat als GET-Abfrageparameter übergeben.

Generierung mit Referenzbildern

Ersetzen Sie die Beispiel-URL durch eine erreichbare Bild-URL. Das Beispiel lässt das Verhältnis weg, um der Referenzkomposition zu folgen. Für ein festes Verhältnis aspect_ratio hinzufügen. Weitere Eingaben in image_urls ergänzen, insgesamt höchstens 9.

Antwort auf das Absenden

Standardmäßig wird HTTP 200 mit einem Array in data zurückgegeben. submitted bedeutet angenommen, nicht abgeschlossen. Speichern Sie data[0].task_id und fragen Sie anschließend die Aufgabe ab.
Mit dem Header X-APIMart-Response-Version: 2026-07-27 antwortet die Einreichung mit HTTP 202. Lesen Sie die Aufgaben-ID aus data.id und den Abfragepfad aus data.poll_url.
Diese Version ändert die GET-Antwortstruktur nicht. Nach Hinzufügen dieses Headers darf die Einreichungsantwort nicht weiter über data[0].task_id ausgewertet werden.

Aufgabenstatus und Ergebnisse abfragen

Verwenden Sie die vollständige zurückgegebene Aufgaben-ID und dieselbe Benutzeridentität. language steuert optional die Sprache der Fehlermeldungen. Alle Felder finden Sie unter Aufgabenstatus.
Alle 5 Sekunden abfragen, mit höchstens einer laufenden Abfrage pro Aufgabe. Ein Client-Timeout oder gestopptes Polling beendet die Serveraufgabe nicht. ID speichern und GET-Abfragen später fortsetzen; keine neue Generierung automatisch absenden. Den Abschluss anhand von data.status bestimmen. HTTP 200 oder progress: 100 allein bedeutet keinen Generierungserfolg. Ein polling_error während der Verarbeitung ist kein endgültiger Fehler. Beispiel einer abgeschlossenen Abfrageantwort (Ergebnis-URL als Platzhalter):
In Abfrageantworten ist data ein Objekt und url ein Array von Zeichenfolgen. Das erste Ergebnis steht unter data.result.images[0].url[0]. Falls vorhanden, ist expires_at der Ablaufzeitpunkt in Unix-Sekunden. Benötigte Dateien vorher speichern. actual_time ist die Verarbeitungszeit der Aufgabe, nicht die Wiedergabedauer des Videos.

Einschränkungen und Fehlerbehandlung

Referenzvideos, Referenzaudio, Masken, Steuerung des ersten/letzten Bildes, Verlängerung und Remix werden nicht unterstützt. quality hat keinen Effekt. seed, negative_prompt, width, height, response_format und output_format gehören nicht zu den Generierungsparametern dieses Modells und sollten entfallen. async: false aktiviert keine synchrone Generierung; stream bietet keinen SSE-Generierungsstream. Auch fehlgeschlagene Aufgaben können HTTP 200 zurückgeben. Prüfen Sie data.status und data.error.message. Netzwerkfehler oder 5xx beim Absenden können nach der Annahme auftreten; daher nicht sofort mit einem neuen Schlüssel erneut senden.