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 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.

Bild generieren

ELEVENLABS_API_KEY=<your_api_key_here>

pip install elevenlabs
pip install python-dotenv

# 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)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}

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)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}

python example.py

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.

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)

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.

Ergebnisse abrufen

Webhooks und Polling liefern dieselbe Nutzlast. Die Wahl hängt also davon ab, wie Sie darauf warten, nicht davon, was Sie erhalten.

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:

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_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 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 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.

Fehler behandeln

Eine fehlgeschlagene Generierung meldet eine Kategorie in failure_reason zusammen mit einer menschenlesbaren error_message:

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

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 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.

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)

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.

Bildmodelle

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

Informationen zu Modellfunktionen, Verfügbarkeit und Preisen finden Sie in der Übersicht zu Bild & Video.

Nächste Schritte