> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Muse Image Ext Bildgenerierung > Erzeugt pro Anfrage ein WebP-Bild aus Text oder bis zu 9 Referenzbildern. > [!NOTE] > > 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`. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Idempotency-Key: ' \ --data '{ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={ "Authorization": "Bearer ", "Accept": "application/json", "Idempotency-Key": "" }, json={ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 } ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json", Accept: "application/json", "Idempotency-Key": "" }, body: JSON.stringify({ "model": "muse-image-ext", "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text", "aspect_ratio": "1:1", "n": 1 }) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## Anfrageheader **Authorization** `string` *required* Verwenden Sie einen APIMart API Key als `Bearer `. Absenden und Abfragen erfordern die Authentifizierung mit derselben Benutzeridentität. **Idempotency-Key** `string` Dringend empfohlen. Verwenden Sie für jede unabhängige Generierung einen neuen Schlüssel (1–191 sichtbare ASCII-Zeichen; UUID empfohlen). Ersetzen Sie `` 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 **model** `string` *required* Fester Wert: `muse-image-ext`. **prompt** `string` *required* 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. **image\_urls** `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. **aspect\_ratio** `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` **size** `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. **n** `integer` (default: 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. > [!NOTE] > > 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 **webhook** `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. **language** `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 ```json theme={null} { "model": "muse-image-ext", "prompt": "Keep the cup from the reference image and place it on a wooden cafe table in warm natural light", "image_urls": [ "https://your-cdn.example/cup.png" ], "n": 1 } ``` 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. > **Optionale Antwortversion: 2026-07-27** > > 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`. > > ```json theme={null} > { > "code": 202, > "request_id": "req_example", > "data": { > "id": "task_01K...", > "object": "generation.task", > "type": "image", > "status": "pending", > "progress": 0, > "poll_url": "/v1/tasks/task_01K..." > } > } > ``` > > 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](https://docs.apimart.ai/de/api-reference/tasks/status.md). ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/?language=de' \ --header 'Authorization: Bearer ' ``` 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. | `data.status` | Vorgehen | | - | - | | `pending` / `processing` | In der Warteschlange oder in Bearbeitung; weiter abfragen. | | `completed` | Generierung erfolgreich; Polling beenden und Ergebnis-URL lesen. | | `failed` | Generierung fehlgeschlagen; Polling beenden und `data.error.message` lesen. | | `unknown` / … | Status unklar. ID behalten und Abfragen begrenzt wiederholen; nicht als Erfolg werten oder automatisch neu generieren. | 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): ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "images": [ { "url": [ "https://cdn.example/generated-image.webp" ] } ] } } } ``` 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. | HTTP / `error.code` | Vorgehen | | - | - | | `400 / invalid_request_error` | Prompt, Referenzanzahl, Seitenverhältnis, Ausgabeanzahl und feste Ausgabespezifikationen prüfen. | | `409 / idempotency_in_progress` | Gemäß `Retry-After` warten und die ursprüngliche Anfrage mit demselben Idempotenzschlüssel erneut senden. | | `409 / idempotency_key_reused` | Derselbe Schlüssel wurde für unterschiedliche Anfragen verwendet. Schlüsselverwaltung korrigieren; jede unabhängige Generierung benötigt einen neuen Schlüssel. | | `409 / idempotency_result_indeterminate` | Automatisches erneutes Absenden stoppen und Schlüssel sowie Aufgabendaten zur Untersuchung aufbewahren. | | `429` | Vor dem erneuten Versuch gemäß `Retry-After` warten. | 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.