Referenties en assets

Overzicht

De meeste modellen voor Afbeelding & Video accepteren media naast de prompt: een eerste frame voor een video, afbeeldingen om te bewerken, audio om lipsynchronisatie mee uit te voeren. Elk mediaveld in de API accepteert een referentieobject in plaats van onbewerkte bytes in een vaste vorm, en elke referentie heeft een type dat aangeeft waar de media vandaan komt.

De drie typen zijn onderling uitwisselbaar overal waar een referentie wordt geaccepteerd. Hetzelfde veld kan dus in een request een generatie en in het volgende een geüploade asset accepteren.

Koppel generaties aan elkaar

Een generation-referentie hoeft niet naar een voltooide generatie te verwijzen. Verstuur de afbeelding, haal de ID uit de response en geef deze direct door aan het video-request zonder te wachten: de API zet de video achter de afbeelding in de wachtrij en start deze zodra de afbeelding is voltooid. Er wordt niets geüpload tussen de twee aanroepen.

Stel webhook in voor de laatste generatie in de keten en je hoeft helemaal nergens op te wachten. Beide aanroepen geven een response zodra hun generatie in de wachtrij staat, de hele grafiek wordt server-side uitgevoerd en je endpoint wordt aangeroepen zodra de laatste generatie een eindstatus bereikt.

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)

Alleen de laatste generatie heeft webhook nodig. Als je deze ook voor de afbeelding instelt, ontvang je ook een event voor het tussenresultaat. Dat is handig om de voortgang te rapporteren, maar is niet nodig om de keten aan te sturen. Zoals elders vereist het veld een webhook die is geabonneerd op generatie-events; zie webhooks voor Afbeelding & Video om er een in te stellen.

Als je geen endpoint hebt om callbacks te ontvangen, laat je webhook weg en poll je in plaats daarvan het einde van de keten. De tussenliggende afbeelding hoeft nog steeds niet afzonderlijk te worden gepolld — wacht één keer, bij de laatste generatie, met het interval voor die modaliteit, wat voor video maximaal eenmaal per 10 seconden is. Zie richtlijnen voor pollen .

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

Een generatie die verwijst naar onvoltooid werk wordt direct gemaakt en blijft in pending totdat alles waarnaar deze verwijst is voltooid. Je hoeft verder niets te doen om de generatie te starten. Ketens kunnen elke diepte en breedte hebben — een generatie kan wachten op meerdere referenties, die elk zelf nog wachten — dus je kunt een volledige grafiek in één keer versturen en alleen bij de uiteinden ophalen. Tijd die in de wachtrij wordt doorgebracht telt niet mee voor de timeout van de generatie.

Als een generatie waarnaar wordt verwezen mislukt, wordt de afhankelijke generatie nooit uitgevoerd: deze mislukt met de reden dependency_failed en neemt alles wat erachter in de wachtrij staat mee. Voor niets in de ingestorte keten worden kosten in rekening gebracht — een generatie waarvoor al is betaald wordt terugbetaald, en voor een generatie waarvan de prijs afhangt van uitvoer waarnaar wordt verwezen die nog niet bestaat, zoals lipsynchronisatie die wordt geprijsd op basis van de duur van een audio- generatie in behandeling, worden pas kosten in rekening gebracht wanneer deze start. Een generation_id die niet bestaat in je workspace wordt al bij de create-aanroep afgewezen, zodat een typefout direct zichtbaar wordt in plaats van als een mislukte generatie.

Media uploaden als asset

Upload een bestand naar de assets-API wanneer de media van buiten ElevenLabs komt en je deze wilt hergebruiken in meerdere generaties. Assets horen bij de workspace en blijven bestaan totdat je ze verwijdert.

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

De uploadresponse beschrijft de opgeslagen 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 is een ondertekende URL die ongeveer een uur geldig is en is null terwijl de upload nog wordt verwerkt. Haal de asset opnieuw op voor een nieuwe URL.

Opslaglimieten

Geüploade assets tellen mee voor een totale opslaglimiet voor de workspace, die afhangt van je abonnement:

Alleen bestanden die je uploadt tellen mee voor de limiet; gegenereerde uitvoer niet. Een upload die de workspace over de limiet zou brengen, wordt afgewezen met een foutmelding asset_storage_limit_exceeded voordat het bestand wordt gelezen. Verwijder assets die je niet meer nodig hebt om ruimte vrij te maken, of neem contact op met support om de limiet te laten verhogen.

Assets beheren

Geef assets weer met de nieuwste eerst, filter eventueel op naam en blader door de resultaten met de cursor uit de vorige response. page_size accepteert 1 tot 100 en is standaard 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)

Haal een afzonderlijke asset op of verwijder deze op ID. Het verwijderen van een asset heeft geen invloed op generaties die deze al hebben gebruikt.

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

Media inline doorgeven

Een inline_base64-referentie bevat de media in de requestbody, waardoor je voor eenmalige inputs geen aparte upload nodig hebt. Codeer het bestand met het standaard base64-alfabet en geef het MIME-type op.

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 content is na decodering beperkt tot 25 MB per referentie. Grotere bestanden horen in de assets- API, die veel grotere uploads accepteert en niet te maken heeft met de base64-grootteoverhead. Elke modaliteit accepteert een vaste set MIME-typen:

Referentievelden per model

Referentievelden zijn genoemd naar de rol die de media spelen. start_frame en end_frame zijn afzonderlijke afbeeldingen die een video begrenzen, image en audio zijn de vereiste inputs van een lipsynchronisatiemodel, en de losse meervoudsvormen images, videos en audios zijn vrij referentiemateriaal waaruit het model put.

Welke velden een model accepteert en welke combinaties geldig zijn, verschilt per model. Een end_frame vereist altijd een start_frame. Bij het overtreden van een beperking krijg je een validatiefout die het overtredende veld noemt. De generatie start dan nooit en er worden geen kosten in rekening gebracht.

Veo 3.1

Beide Veo-modellen accepteren start_frame, end_frame en maximaal drie vermeldingen in images. Anders dan bij andere modellen bevat elke vermelding in images de referentie samen met de rol die deze speelt:

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

Een subject-referentie plaatst het onderwerp of de scène-elementen van de afbeelding in de video; een style- referentie draagt de visuele stijl ervan over. Referentieafbeeldingen kunnen niet worden gecombineerd met start_frame of end_frame en vereisen een duur van acht seconden.

Seedance

De drie Seedance 2.0-niveaus accepteren start_frame, end_frame, maximaal 9 images, maximaal 3 videos en maximaal 3 audios, onder deze voorwaarden:

• Referenties kunnen niet worden gecombineerd met start_frame of end_frame.
• Referentieaudio vereist minstens één referentieafbeelding of -video, bijvoorbeeld om lipsynchronisatie aan te sturen.
• Het gecombineerde aantal referentiebestanden mag niet meer dan 12 zijn.

Seedance 2.5 verhoogt de limieten naar 30 images, 10 videos en 10 audios zonder gecombineerd totaal, en laat de regel vervallen dat referentieaudio een bijbehorende afbeelding of video nodig heeft. Audio-only input wordt dus geaccepteerd. Referenties kunnen nog steeds niet worden gecombineerd met start_frame of end_frame.

GPT Image

De GPT Image-modellen accepteren een mask naast images. Volledig transparante delen van het masker markeren waar de eerste referentieafbeelding mag worden bewerkt. Een masker zonder referentieafbeeldingen wordt afgewezen.

Volgende stappen