> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Bild & Video – Schnellstart Die Bild & Video API ist asynchron. Sie übermitteln eine Generierung und laden das Ergebnis nach Abschluss über eine signierte URL herunter. Bilder und Videos haben separate Endpunkte, aber Anfrage- und Antwortstruktur sind für beide gleich. Es gibt zwei Wege, das Ergebnis abzurufen. Die [Webhook-Zustellung](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks) ist die empfohlene Methode und wird in den folgenden Beispielen verwendet: ElevenLabs ruft Ihren Endpunkt auf, sobald eine Generierung einen endgültigen Status erreicht. So entsteht keine Wartezeit. Polling ist die Alternative, wenn Sie keinen Endpunkt für einen Callback haben. Jedes Beispiel zeigt, wie Sie darauf zurückgreifen können. > **Warning** > > Die Bild & Video API erfordert den Pro-Tarif oder höher. Aufrufe aus einem Workspace unterhalb dieser Stufe werden > mit dem Fehler `402 paid_plan_required` abgelehnt. Ihr API-Schlüssel benötigt außerdem für den Workspace die Berechtigung Bild & Video oder > Flows. ## Bild generieren #### API-Schlüssel erstellen [Erstellen Sie hier im Dashboard einen API-Schlüssel](https://elevenlabs.io/app/settings/api-keys), den Sie für den sicheren [Zugriff auf die API](/docs/de/api-reference/authentication) verwenden. Speichern Sie den Schlüssel als verwaltetes Secret und übergeben Sie ihn je nach Präferenz an die SDKs entweder als Umgebungsvariable über eine `.env`-Datei oder direkt in der Konfiguration Ihrer App. **`.env`** ```js title=".env" ELEVENLABS_API_KEY= ``` #### SDK installieren #### SDK Wir verwenden außerdem die Bibliothek `dotenv`, um unseren API-Schlüssel aus einer Umgebungsvariable zu laden. ```python pip install elevenlabs pip install python-dotenv ``` ```typescript npm install @elevenlabs/elevenlabs-js npm install dotenv ``` #### CLI Installieren Sie die ElevenLabs CLI. Homebrew (macOS) und Scoop (Windows) werden empfohlen. **`Homebrew (macOS)`** ```bash title="Homebrew (macOS)" brew install elevenlabs/tap/elevenlabs ``` **`Scoop (Windows)`** ```powershell title="Scoop (Windows)" scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket scoop install elevenlabs ``` **`npm`** ```bash title="npm" npm install -g @elevenlabs/cli ``` **`curl`** ```bash title="curl" curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh ``` > **Tip** > > Arbeiten Sie mit einem KI-Coding-Assistenten? Führen Sie in Ihrem Projekt `elevenlabs generate-skills` aus, um für jede Befehlsgruppe eine > `SKILL.md` in `skills/` zu schreiben. So kennt Ihr Assistent den gesamten Funktionsumfang der CLI, > ohne dass Sie Dokumentation einfügen müssen. Mit `--output-dir` können Sie sie an einem anderen Ort ablegen. Dies liest die eigene > eingebettete API-Definition der CLI, benötigt also keinen API-Schlüssel und funktioniert offline — und bleibt mit > der von Ihnen installierten CLI-Version synchron. Authentifizieren Sie sich anschließend — dadurch wird Ihr Browser geöffnet, um die CLI zu autorisieren: ```bash elevenlabs auth login ``` #### Generierung übermitteln Jedes Modell hat eine eigene Anfrageklasse. Deren Felder entsprechen den Parametern, die das Modell akzeptiert. Beim Wechsel des Modells können sich daher die verfügbaren Felder ändern. Unbekannte Felder werden abgelehnt, nicht ignoriert. `webhook` fordert die Zustellung des fertigen Ergebnisses an die Webhooks Ihres Workspace an. Der Aufruf wird daher zurückgegeben, sobald die Generierung eingereiht wurde. Dies erfordert einen Webhook, der Generierungsereignisse abonniert hat. Informationen zur Einrichtung finden Sie unter [Bild & Video- Webhooks](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks). Alternativ lassen Sie das Feld weg und verwenden Polling. #### SDK ```python # example.py import os from dotenv import load_dotenv from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All from elevenlabs.client import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) generation = elevenlabs.flows.image.create( request=ImageGenerationRequest_Gemini3ProImage( prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", aspect_ratio="16:9", resolution="2K", webhook=WebhookTarget_All(), ) ) print(generation.id, generation.status) ``` ```typescript // example.mts import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; import "dotenv/config"; const elevenlabs = new ElevenLabsClient(); const generation = await elevenlabs.flows.image.create({ modelId: "gemini-3-pro-image", prompt: "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", aspectRatio: "16:9", resolution: "2K", webhook: { type: "all" }, }); console.log(generation.id, generation.status); ``` #### CLI Die CLI übermittelt dieselbe Anfrage als JSON, führt dann Polling durch, bis die Generierung abgeschlossen ist, und lädt das Ergebnis herunter: ```bash # 1. Submit the generation (note the returned id) elevenlabs flows image create --json '{ "model_id": "gemini-3-pro-image", "prompt": "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", "aspect_ratio": "16:9", "resolution": "2K" }' # 2. Poll until the status is "completed" elevenlabs flows image get --generation-id --query status # 3. Read the signed content URL, then download the image elevenlabs flows image get --generation-id --query content_url curl -o corgi.png "" ``` Die Antwort enthält nur die Generierungs-ID. Eine neu erstellte Generierung hat immer den Status `pending`: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "pending" } ``` #### Ergebnis abrufen Da die Anfrage `webhook` verwendet, sendet ElevenLabs ein `flows_generation`-Ereignis an Ihren Endpunkt, sobald die Generierung `completed` oder `failed` erreicht. Die `data` des Ereignisses entsprechen der Antwort des GET-Endpunkts. Unter [Bild & Video-Webhooks](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks) erfahren Sie, wie Sie den empfangenden Handler implementieren. Wenn Sie keinen Endpunkt für Callbacks haben, entfernen Sie `webhook` aus der obigen Anfrage und verwenden Sie stattdessen Polling. Rufen Sie die Generierung ab, bis ihr Status `completed` oder `failed` lautet. Warten Sie bei einem Bild zwischen den Anfragen mindestens zwei Sekunden – die Intervalle je Modalität finden Sie unter [Polling-Richtlinien](#polling-guidelines). ```python maxLines=0 import time import requests while True: result = elevenlabs.flows.image.get(generation.id) if result.status in ("completed", "failed"): break time.sleep(2) if result.status == "failed": raise RuntimeError(f"{result.failure_reason}: {result.error_message}") with open("corgi.png", "wb") as f: f.write(requests.get(result.content_url).content) ``` ```typescript maxLines=0 import { writeFile } from "fs/promises"; let result = await elevenlabs.flows.image.get(generation.id); while (result.status === "pending" || result.status === "generating") { await new Promise((resolve) => setTimeout(resolve, 2000)); result = await elevenlabs.flows.image.get(generation.id); } if (result.status === "failed") { throw new Error(`${result.failureReason}: ${result.errorMessage}`); } const response = await fetch(result.contentUrl); await writeFile("corgi.png", Buffer.from(await response.arrayBuffer())); ``` In beiden Fällen enthält eine abgeschlossene Generierung dieselben Felder: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "completed", "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb", "content_mime_type": "image/png" } ``` #### Code ausführen ```python python example.py ``` ```typescript npx tsx example.mts ``` Die Generierung wird eingereiht und ihre ID ausgegeben. Bei Webhook-Zustellung trifft das Bild an Ihrem Endpunkt ein; bei der Polling-Variante wird es als `corgi.png` gespeichert. ## Video generieren Videogenerierungen verwenden `flows.video` und folgen demselben Muster aus Übermitteln und Abrufen. Ein Video kann mehrere Minuten dauern. Deshalb verwendet dieses Beispiel die Webhook-Zustellung mit `webhook`, statt auf das Ergebnis zu warten. ```python from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All generation = elevenlabs.flows.video.create( request=VideoGenerationRequest_Veo31FastGenerate001( prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic", duration_secs=8, aspect_ratio="16:9", resolution="1080p", generate_audio=True, webhook=WebhookTarget_All(), ) ) print(generation.id) ``` ```typescript const generation = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic", durationSecs: 8, aspectRatio: "16:9", resolution: "1080p", generateAudio: true, webhook: { type: "all" }, }); console.log(generation.id); ``` Der Aufruf wird zurückgegeben, sobald die Generierung eingereiht ist. Das fertige Ergebnis wird an jeden Webhook in Ihrem Workspace zugestellt, der Generierungsereignisse abonniert hat. Die Videoausgabe ist MP4. Daher meldet die abgeschlossene Nutzlast für `content_mime_type` den Wert `video/mp4`. Informationen zum Konfigurieren eines Webhooks und zum Implementieren des empfangenden Handlers finden Sie unter [Bild & Video-Webhooks](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks). > **Warning** > > `webhook` erfordert mindestens einen Workspace-Webhook, der Generierungsereignisse abonniert hat. Ohne einen solchen > wird der Erstellungsaufruf abgelehnt, statt eine Generierung zu starten, deren Ergebnis nirgendwo zugestellt werden kann. Entfernen Sie > das Feld, um auf Polling mit `flows.video.get` zurückzugreifen, und führen Sie Polling höchstens einmal pro 10 > Sekunden durch. ## Ergebnisse abrufen Webhooks und Polling liefern dieselbe Nutzlast. Die Wahl hängt also davon ab, wie Sie darauf warten, nicht davon, was Sie erhalten. | | Webhook-Zustellung | Polling | | ------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | | Am besten für | Standard für beide Modalitäten und jeden Produktionseinsatz | Skripte und Umgebungen ohne öffentlichen Endpunkt | | Erfordert | Einen HTTPS-Endpunkt, der Generierungsereignisse abonniert hat | Nichts | | Wartekosten | Keine; Sie werden benachrichtigt, sobald die Generierung abgeschlossen ist | Eine Anfrage pro Abfrage und Generierung | Verwenden Sie Webhooks, wo immer möglich. Nutzen Sie Polling, wenn Sie keinen Callback empfangen können, und halten Sie sich dabei an die unten genannten Intervalle. ### Webhook-Ziele auswählen `webhook` akzeptiert zwei Formen. `WebhookTarget_All` erreicht jeden Webhook, der Generierungsereignisse abonniert hat. Das ist der richtige Standard, da er auch funktioniert, wenn Webhooks rotiert oder ersetzt werden. `WebhookTarget_Ids` beschränkt die Zustellung auf bestimmte Webhooks. Das ist sinnvoll, wenn ein Workspace an mehrere Empfänger verteilt und ein bestimmter Job nur einen davon erreichen soll: ```python from elevenlabs import WebhookTarget_Ids webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"]) ``` ```typescript const webhook = { type: "ids", ids: ["Q8mVr2LpXcT4nB6yJdKw"] }; ``` Jede ID muss bereits Generierungsereignisse abonniert haben. Die Angabe eines nicht abonnierten Webhooks wird abgelehnt und nicht stillschweigend ignoriert. Die zugestellte Nutzlast ist identisch mit der Rückgabe des GET-Endpunkts. Ein Handler, der für einen geschrieben wurde, funktioniert daher auch für den anderen. Der [Webhook-Leitfaden](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks) erklärt die Konfiguration eines Webhooks, die Signaturprüfung und die Ereignisverarbeitung. ### Richtlinien für Polling Die Laufzeit einer Generierung hängt vom Modell, der Auflösung und bei Videos von der Dauer ab. Fragen Sie daher in einem Intervall ab, das zu Ihrer Anfrage passt, statt in einer festen Schleife: * **Bilder**: Fragen Sie höchstens alle 2 Sekunden ab. Die meisten sind innerhalb weniger Sekunden fertig. * **Videos**: Fragen Sie höchstens alle 10 Sekunden ab. Rechnen Sie mit Minuten statt Sekunden und passen Sie das Intervall an `duration_secs` und `resolution` an. Für beide gelten zwei Regeln. Erhöhen Sie das Intervall, wenn eine Generierung lange läuft — durch Verdopplung bis auf etwa eine Minute vermeiden Sie, dass eine langsame Generierung Hunderte Anfragen auslöst. Begrenzen Sie außerdem die Schleife, damit eine festhängende Generierung in Ihrem eigenen Code mit einem Timeout endet und nicht in einer unbegrenzten Schleife. Schnelleres Polling bringt nichts: Der Status einer Generierung ändert sich nicht früher, nur weil Sie zweimal fragen. Dauerhaft aggressives Polling kann [429-Antworten](/docs/de/eleven-api/resources/errors#rate-limiting-and-concurrency) zurückgeben, die Sie mit exponentiellem Backoff behandeln sollten. ## Lebenszyklus einer Generierung Eine Generierung durchläuft vier Status. Die beiden Endstatus enthalten unterschiedliche Felder. Prüfen Sie daher `status`, bevor Sie den Rest der Antwort lesen. | Status | Bedeutung | | ------------ | ----------------------------------------------------------------------------------------------- | | `pending` | Die Generierung ist in der Warteschlange. Dies ist der Status jeder neu erstellten Generierung. | | `generating` | Das Modell läuft. | | `completed` | Die Ausgabe ist bereit. Die Antwort enthält `content_url` und `content_mime_type`. | | `failed` | Die Generierung hat keine Ausgabe erzeugt. Die Antwort enthält die Fehlerdetails. | > **Warning** > > `content_url` ist eine signierte URL, die etwa eine Stunde nach Rückgabe der Antwort abläuft. Rufen > Sie die Generierung erneut ab, um eine aktuelle URL zu erhalten, statt die signierte URL selbst zu speichern. ## Fehler behandeln Eine fehlgeschlagene Generierung meldet eine Kategorie in `failure_reason` zusammen mit einer menschenlesbaren `error_message`: ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "failed", "failure_reason": "moderated", "error_message": "The prompt was rejected by content moderation. You were not charged for this generation." } ``` | `failure_reason` | Ursache | | -------------------- | ----------------------------------------------------------------------------- | | `timeout` | Das Modell hat nicht rechtzeitig ein Ergebnis zurückgegeben. | | `model_error` | Der Modellanbieter hat einen Fehler zurückgegeben oder keine Ausgabe erzeugt. | | `moderated` | Der Prompt oder eine Eingabe wurde von der Inhaltsmoderation abgelehnt. | | `invalid_parameters` | Die Parameter wurden abgelehnt, als die Generierung das Modell erreichte. | | `dependency_failed` | Eine referenzierte Generierung, von der diese abhängt, ist fehlgeschlagen. | | `charging_failed` | Dem Workspace konnte die Generierung nicht berechnet werden. | | `internal_error` | Ein unerwarteter Fehler ist aufgetreten. | Fehlgeschlagene Generierungen werden nicht berechnet. Parameterprobleme, die im Voraus erkannt werden können — ein nicht unterstütztes Feld, ein Wert außerhalb des zulässigen Bereichs eines Modells oder eine ungültige Kombination von Referenzeingaben — werden stattdessen von der Erstellungsanfrage abgelehnt, bevor eine Generierung beginnt. ## Preise Generierungen werden in Credits berechnet. Die Kosten hängen vom Modell, den gewählten Parametern wie Auflösung und Dauer sowie den bereitgestellten Eingaben ab. Eine Generierung kostet über die API genauso viel wie in der ElevenLabs-App, in der die Kosten vor dem Absenden angezeigt werden. Unter [Bild & Video im Playground](/docs/de/eleven-creative/playground/image-video) erfahren Sie, wie die Kosten für eine bestimmte Kombination aus Modell und Einstellungen angezeigt werden. ## Ihre Generierungen auflisten Jeder Endpunkt listet die über ihn erstellten Generierungen auf, die neuesten zuerst. Die Ergebnisse sind auf Ihren Workspace und diese API beschränkt. In der ElevenLabs-App erstellte Generierungen werden daher nicht angezeigt. ```python page = elevenlabs.flows.image.list(page_size=20, status="completed") for item in page.generations: print(item.id, item.content_url) while page.has_more: page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor) for item in page.generations: print(item.id, item.content_url) ``` ```typescript let page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed" }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } while (page.hasMore) { page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed", cursor: page.nextCursor, }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } } ``` `page_size` akzeptiert Werte von 1 bis 100 und hat standardmäßig den Wert 30. Übergeben Sie `status`, um nur Generierungen in einem Lebenszyklusstatus zurückzugeben, und `model_id`, um nur Generierungen eines einzelnen Modells zurückzugeben. Behandeln Sie `next_cursor` als undurchsichtig: Übergeben Sie den exakten Wert erneut und stoppen Sie, wenn `has_more` `false` ist. ## Verfügbare Modelle Die API stellt eine Auswahl der in der ElevenLabs-App verfügbaren Modelle bereit. Jedes Modell akzeptiert nur die für es aufgeführten Parameter — das Senden eines Felds, das von einem anderen Modell unterstützt wird, führt zu einem Validierungsfehler. > **Warning** > > ByteDance-Modelle sind standardmäßig deaktiviert und erfordern vor der Nutzung eine ausdrückliche > Genehmigung. Bis der Zugriff gewährt wurde, wird eine Anfrage mit einem dieser Modelle mit einem > `model_access_denied`-Fehler abgelehnt. Enterprise-Kunden können den Support kontaktieren, um Zugriff zu beantragen. ### Bildmodelle | `model_id` | Referenzbilder | Ausgabesteuerungen | | ----------------------------- | --------------------------- | ----------------------------------------------------------------------------- | | `gpt-image-1` | Bis zu 5, plus eine `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-1.5` | Bis zu 5, plus eine `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-2` | Bis zu 10, plus eine `mask` | 15 Seitenverhältnisse, `resolution` (1K, 2K, 4K), `quality` | | `gpt-image-2.5-sunburst` | Bis zu 10, plus eine `mask` | 15 Seitenverhältnisse, `resolution` (1K, 2K, 4K), `quality` (bis `max`) | | `gpt-image-2.5-flare` | Bis zu 10, plus eine `mask` | 15 Seitenverhältnisse, `resolution` (1K, 2K, 4K), `quality` (bis `max`) | | `gemini-2.5-flash-image` | Bis zu 5 | `aspect_ratio` | | `gemini-3-pro-image` | Bis zu 10 | `aspect_ratio`, `resolution` (1K, 2K, 4K) | | `gemini-3.1-flash-image` | Bis zu 14 | `aspect_ratio` (einschließlich 1:4, 4:1, 1:8, 8:1), `resolution` (512 bis 4K) | | `gemini-3.1-flash-lite-image` | Bis zu 14 | `aspect_ratio`, `resolution` (1K) | | `bytedance-seedream-5-lite` | Bis zu 10 | `aspect_ratio`, `resolution` (2K, 3K), `seed` | | `bytedance-seedream-5-pro` | Bis zu 10 | `aspect_ratio`, `resolution` (1K, 2K), `seed` | Die GPT Image 2.5-Modelle akzeptieren für `quality` die Werte `low`, `medium`, `high`, `xhigh` und `max`; der Standardwert ist `high`. GPT Image 2 unterstützt maximal `high`; der Standardwert ist `medium`. ### Videomodelle | `model_id` | Medieneingaben | Ausgabesteuerungen | | ---------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-001` | `start_frame`, `end_frame`, bis zu 3 `images` mit einer `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `veo-3.1-fast-generate-001` | `start_frame`, `end_frame`, bis zu 3 `images` mit einer `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `bytedance-seedance-v2` | `start_frame`, `end_frame`, bis zu 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 bis 15), 7 Seitenverhältnisse, `resolution` (480p bis 4k), `generate_audio` | | `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, bis zu 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 bis 15), 7 Seitenverhältnisse, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, bis zu 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 bis 15), 7 Seitenverhältnisse, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2.5` | `start_frame`, `end_frame`, bis zu 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (4 bis 30), 7 Seitenverhältnisse, `resolution` (480p, 720p), `generate_audio` | | `creatify-aurora` | `image` und `audio`, beide erforderlich | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale` | Informationen zu Modellfunktionen, Verfügbarkeit und Preisen finden Sie in der [Übersicht zu Bild & Video](/docs/de/overview/capabilities/image-video). ## Nächste Schritte #### [Referenzen und Assets](/docs/de/eleven-api/guides/how-to/image-and-video/references) Steuern Sie eine Generierung mit einer vorherigen Generierung, einem hochgeladenen Asset oder Inline-Medien. #### [Webhooks](/docs/de/eleven-api/guides/how-to/image-and-video/webhooks) Erhalten Sie das Ergebnis einer Generierung, statt es per Polling abzufragen. #### [API-Referenz](/docs/de/api-reference/flows/image/create) Entdecken Sie die Endpunkte für Bilder, Videos und Assets.