Referenzen und Assets

Überblick

Die meisten Image-&-Video-Modelle akzeptieren Medien zusammen mit dem Prompt: ein erstes Bild für ein Video, Bilder zum Bearbeiten oder Audio zum Lippensynchronisieren. Jedes Medienfeld in der API verwendet ein Referenzobjekt statt Rohdaten in einem festen Format. Jede Referenz hat einen type, der angibt, woher das Medium stammt.

Die drei Arten sind überall austauschbar, wo eine Referenz akzeptiert wird. Dasselbe Feld kann also in einem Request eine Generierung und im nächsten ein hochgeladenes Asset verwenden.

Eine Generierung mit der nächsten verketten

Eine generation-Referenz muss nicht auf eine abgeschlossene Generierung verweisen. Senden Sie die Bildgenerierung, entnehmen Sie die ID aus der Antwort und übergeben Sie sie direkt an den Video-Request, ohne zu warten: Die API reiht das Video hinter dem Bild ein und startet es, sobald das Bild fertig ist. Zwischen den beiden Aufrufen wird nichts hochgeladen.

Setzen Sie webhook für die letzte Generierung in der Kette, müssen Sie überhaupt nicht warten. Beide Aufrufe kehren zurück, sobald ihre Generierung eingereiht ist, der gesamte Graph wird serverseitig ausgeführt und Ihr Endpoint wird aufgerufen, wenn die letzte Generierung einen Endstatus erreicht.

from elevenlabs import (
    ImageGenerationRequest_Gemini3ProImage,
    ImageReference_Generation,
    VideoGenerationRequest_Veo31FastGenerate001,
    WebhookTarget_All,
)
still = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
        aspect_ratio="16:9",
    )
)
# `still` is still pending here. Submitting now queues the video behind it.
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The fog thickens and the beam sweeps across the water",
        start_frame=ImageReference_Generation(generation_id=still.id),
        duration_secs=8,
        webhook=WebhookTarget_All(),
    )
)
print(clip.id)

Nur die letzte Generierung benötigt webhook. Wenn Sie ihn auch für das Bild setzen, wird zusätzlich ein Ereignis für das Zwischenergebnis ausgeliefert. Das ist für Fortschrittsmeldungen nützlich, aber nicht nötig, um die Kette auszuführen. Wie an anderer Stelle erfordert das Feld einen Webhook, der Generierungsereignisse abonniert hat; unter Image-&-Video-Webhooks erfahren Sie, wie Sie einen einrichten.

Ohne Endpoint für Callbacks lassen Sie webhook weg und pollen stattdessen das Ende der Kette. Das Zwischenbild muss weiterhin nicht separat abgefragt werden — warten Sie einmal auf die letzte Generierung, im Intervall für ihre Modalität, bei Video höchstens einmal alle 10 Sekunden. Siehe Richtlinien zum Polling.

import time
while True:
    result = elevenlabs.flows.video.get(clip.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(10)

Eine Generierung, die auf noch nicht abgeschlossene Arbeit verweist, wird sofort erstellt und bleibt in pending, bis alles, worauf sie verweist, abgeschlossen ist. Zum Starten ist keine weitere Aktion erforderlich. Ketten können beliebig tief und breit sein — eine Generierung kann auf mehrere Referenzen warten, die jeweils selbst noch warten — sodass ein ganzer Graph in einem Durchgang eingereicht und nur an seinen Endpunkten abgefragt werden kann. Die Wartezeit zählt nicht zum Timeout der Generierung.

Wenn eine referenzierte Generierung fehlschlägt, wird die abhängige nie ausgeführt: Sie schlägt mit dem Grund dependency_failed fehl und nimmt alles mit, was dahinter eingereiht ist. Für nichts in der abgebrochenen Kette werden Kosten berechnet — eine bereits bezahlte Generierung wird erstattet, und eine Generierung, deren Preis von einer noch nicht vorhandenen referenzierten Ausgabe abhängt, etwa eine Lippensynchronisierung mit Preis nach Dauer einer ausstehenden Audiogenerierung, wird erst berechnet, wenn sie startet. Eine generation_id, die in Ihrem Workspace nicht existiert, wird bereits beim Erstellungsaufruf abgelehnt. Ein Tippfehler wird also sofort erkannt statt als fehlgeschlagene Generierung.

Medien als Asset hochladen

Laden Sie eine Datei in die Assets-API hoch, wenn das Medium von außerhalb von ElevenLabs stammt und Sie es über mehrere Generierungen hinweg wiederverwenden möchten. Assets gehören zum Workspace und bleiben bestehen, bis Sie sie löschen.

from elevenlabs import ImageReference_Asset, VideoGenerationRequest_Veo31FastGenerate001
with open("lighthouse.png", "rb") as f:
    asset = elevenlabs.assets.create(asset=f, name="lighthouse.png")
print(asset.asset_id)
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The beam sweeps across the water as the fog thickens",
        start_frame=ImageReference_Asset(asset_id=asset.asset_id),
    )
)

Die Upload-Antwort beschreibt das gespeicherte Asset:

{
  "asset_id": "5xM2KqOnZyce22SPZ9d4",
  "name": "lighthouse.png",
  "mime_type": "image/png",
  "created_at_unix": 1721520000,
  "content_url": "https://storage.googleapis.com/assets/5xM2KqOnZyce22SPZ9d4"
}

content_url ist eine signierte URL, die etwa eine Stunde gültig ist, und während der Upload noch verarbeitet wird null. Rufen Sie das Asset erneut ab, um eine neue URL zu erhalten.

Speicherlimits

Hochgeladene Assets zählen zum gesamten Speicherlimit des Workspace, das von Ihrem Plan abhängt:

Nur die von Ihnen hochgeladenen Dateien zählen zum Limit; generierte Ausgaben nicht. Ein Upload, der das Limit des Workspace überschreiten würde, wird mit dem Fehler asset_storage_limit_exceeded abgelehnt, bevor die Datei gelesen wird. Löschen Sie nicht mehr benötigte Assets, um Speicher freizugeben, oder wenden Sie sich an den Support, um das Limit erhöhen zu lassen.

Assets verwalten

Listen Sie Assets mit den neuesten zuerst auf, filtern Sie optional nach Namen und blättern Sie mit dem Cursor aus der vorherigen Antwort durch die Ergebnisse. page_size akzeptiert 1 bis 100 und hat standardmäßig den Wert 30.

page = elevenlabs.assets.list(page_size=20, search="lighthouse")
for asset in page.assets:
    print(asset.asset_id, asset.name, asset.mime_type)
if page.has_more:
    page = elevenlabs.assets.list(page_size=20, search="lighthouse", cursor=page.next_cursor)

Rufen Sie ein einzelnes Asset anhand seiner ID ab oder löschen Sie es. Das Löschen eines Assets wirkt sich nicht auf Generierungen aus, die es bereits verwendet haben.

asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4")
elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4")

Medien inline übergeben

Eine inline_base64-Referenz enthält das Medium im Request-Body und vermeidet damit einen separaten Upload für einmalige Eingaben. Kodieren Sie die Datei mit dem Standard-Base64-Alphabet und geben Sie ihren MIME-Typ an.

import base64
from elevenlabs import ImageGenerationRequest_GptImage2, ImageReference_InlineBase64
with open("headshot.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_GptImage2(
        prompt="Replace the background with a softly lit studio backdrop",
        images=[
            ImageReference_InlineBase64(
                content_base64=encoded,
                mime_type="image/jpeg",
            )
        ],
    )
)

Inline-Inhalte sind nach dem Dekodieren auf 25 MB pro Referenz begrenzt. Größere Dateien gehören in die Assets- API, die deutlich größere Uploads akzeptiert und nicht den Base64-Größenaufschlag verursacht. Jede Modalität akzeptiert eine feste Auswahl an MIME-Typen:

Referenzfelder nach Modell

Referenzfelder sind nach der Rolle benannt, die das Medium spielt. start_frame und end_frame sind einzelne Bilder, die ein Video begrenzen. image und audio sind die erforderlichen Eingaben eines Lippensynchronisierungsmodells, und die bloßen Pluralformen images, videos und audios sind frei verwendbares Referenzmaterial, auf das das Modell zurückgreift.

Welche Felder ein Modell akzeptiert und welche Kombinationen gültig sind, unterscheidet sich je nach Modell. Ein end_frame erfordert immer einen start_frame. Bei Verletzung einer Einschränkung wird ein Validierungsfehler mit Angabe des betroffenen Feldes zurückgegeben. Die Generierung startet dann nicht und wird nicht berechnet.

Veo 3.1

Beide Veo-Modelle akzeptieren start_frame, end_frame und bis zu drei Einträge in images. Anders als bei anderen Modellen enthält jeder Eintrag in images sowohl die Referenz als auch die Rolle, die sie spielt:

{
  "images": [
    {
      "image": { "type": "asset", "asset_id": "5xM2KqOnZyce22SPZ9d4" },
      "role": "subject"
    },
    {
      "image": { "type": "asset", "asset_id": "7pQ4LnBvXkR2mT9wYcHd" },
      "role": "style"
    }
  ]
}

Eine subject-Referenz platziert das Motiv oder Szenenelemente des Bildes im Video; eine style- Referenz überträgt dessen visuellen Stil. Referenzbilder können nicht mit start_frame oder end_frame kombiniert werden und erfordern eine Dauer von acht Sekunden.

Seedance

Die drei Seedance-2.0-Stufen akzeptieren start_frame, end_frame, bis zu 9 images, bis zu 3 videos und bis zu 3 audios, vorbehaltlich dieser Einschränkungen:

• Referenzen können nicht mit start_frame oder end_frame kombiniert werden.
• Referenz-Audio erfordert mindestens ein Referenzbild oder -video, etwa um Lippensynchronisierung zu steuern.
• Die Gesamtzahl der Referenzdateien darf 12 nicht überschreiten.

Seedance 2.5 erhöht die Obergrenzen auf 30 images, 10 videos und 10 audios ohne Gesamtlimit und hebt die Regel auf, dass Referenz-Audio ein begleitendes Bild oder Video benötigt. Dadurch wird reine Audioeingabe akzeptiert. Referenzen können weiterhin nicht mit start_frame oder end_frame kombiniert werden.

GPT Image

Die GPT-Image-Modelle akzeptieren eine mask zusammen mit images. Vollständig transparente Bereiche der Maske markieren, wo das erste Referenzbild bearbeitet werden darf. Eine Maske ohne Referenzbilder wird abgelehnt.

Nächste Schritte