Referenser och resurser

Översikt

De flesta Bild och video-modeller accepterar medier tillsammans med prompten: en första bildruta för en video, bilder att redigera eller ljud att läppsynka mot. Varje mediefält i API:et tar emot ett referensobjekt i stället för råa byte i ett fast format, och varje referens är märkt med en type som anger var mediet kommer ifrån.

De tre typerna kan användas omväxlande överallt där en referens accepteras, så samma fält kan ta emot en generering i en begäran och en uppladdad resurs i nästa.

Koppla en generering till nästa

En generation-referens behöver inte peka på en generering som har slutförts. Skicka bilden, ta ID:t från svaret och skicka det direkt i videobegäran utan att vänta: API:et köar videon efter bilden och startar den när bilden är klar. Inget laddas upp mellan de två anropen.

Ange webhook för den sista genereringen i kedjan så behöver du inte vänta alls. Båda anropen returnerar så snart deras generering har köats, hela grafen körs på servern och din slutpunkt anropas när den sista genereringen når en slutstatus.

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)

Endast den sista genereringen behöver webhook. Om du även anger det för bilden skickas en händelse för mellanresultatet, vilket är användbart för att rapportera förloppet men inte behövs för att driva kedjan. Precis som på andra ställen kräver fältet en webhook som prenumererar på genereringshändelser. Se webhooks för Bild och video för att konfigurera en.

Om du inte har en slutpunkt som kan ta emot återanrop kan du utelämna webhook och polla slutet av kedjan i stället. Den mellanliggande bilden behöver fortfarande inte pollas separat – vänta en gång på den sista genereringen, med intervallet för dess modalitet, vilket för video är högst en gång var tionde sekund. Se riktlinjer för pollning.

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

En generering som refererar till oavslutat arbete skapas omedelbart och har status pending tills allt den refererar till är klart. Du behöver inte göra något mer för att starta den. Kedjor kan ha valfritt djup och bredd – en generering kan vänta på flera referenser som var och en fortfarande väntar – så du kan skicka in en hel graf i ett svep och bara hämta resultaten vid dess löv. Tid som spenderas i kö räknas inte mot genereringens timeout.

Om en refererad generering misslyckas körs aldrig den beroende genereringen: den misslyckas med anledningen dependency_failed och tar med sig allt som köats efter den. Ingenting i den avbrutna kedjan debiteras – en generering som redan har betalats återbetalas, och en vars pris beror på en refererad utdata som ännu inte finns, exempelvis en läppsynkning vars pris beror på längden på en väntande ljudgenerering, debiteras först när den startar. Ett generation_id som inte finns i din arbetsyta avvisas redan i create-anropet, så ett skrivfel visas direkt i stället för som en misslyckad generering.

Ladda upp medier som en resurs

Ladda upp en fil till resurs-API:et när mediet kommer utanför ElevenLabs och du vill återanvända den i flera genereringar. Resurser tillhör arbetsytan och finns kvar tills du tar bort dem.

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

Uppladdningssvaret beskriver den lagrade resursen:

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

content_url är en signerad URL som är giltig i ungefär en timme och har värdet null medan uppladdningen fortfarande bearbetas. Hämta resursen igen för en ny URL.

Lagringsgränser

Uppladdade resurser räknas mot en sammanlagd lagringsgräns för arbetsytan, som beror på ditt abonnemang:

Endast filer som du laddar upp räknas mot gränsen; genererade utdata gör det inte. En uppladdning som skulle överskrida arbetsytans gräns avvisas med felet asset_storage_limit_exceeded innan filen läses. Ta bort resurser du inte längre behöver för att frigöra utrymme, eller kontakta supporten för att höja gränsen.

Hantera resurser

Lista resurser med de nyaste först, filtrera eventuellt efter namn och bläddra igenom resultat med markören från föregående svar. page_size accepterar 1 till 100 och har standardvärdet 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)

Hämta eller ta bort en enskild resurs efter ID. Om du tar bort en resurs påverkas inte genereringar som redan har använt den.

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

Skicka medier integrerat

En inline_base64-referens bär mediet i begärandetexten, vilket undviker en separat uppladdning för engångsindata. Koda filen med standardalfabetet för base64 och ange dess MIME-typ.

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

Integrerat innehåll är begränsat till 25 MB per referens efter avkodning. Större filer hör hemma i resurs- API:et, som accepterar mycket större uppladdningar och inte har base64-storleksbegränsningen. Varje modalitet accepterar en fast uppsättning MIME-typer:

Referensfält per modell

Referensfält namnges efter den roll mediet spelar. start_frame och end_frame är enskilda bilder som avgränsar en video, image och audio är de obligatoriska indata för en läppsynkningsmodell och pluralerna images, videos och audios är fritt referensmaterial som modellen använder.

Vilka fält en modell accepterar och vilka kombinationer som är giltiga varierar mellan modeller. En end_frame kräver alltid en start_frame. Ett brott mot en begränsning ger ett valideringsfel som anger det berörda fältet, så genereringen startar aldrig och debiteras aldrig.

Veo 3.1

Båda Veo-modellerna accepterar start_frame, end_frame och upp till tre poster i images. Till skillnad från andra modeller omsluter varje post i images referensen tillsammans med rollen den spelar:

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

En subject-referens placerar bildens motiv eller scenelement i videon; en style- referens överför dess visuella stil. Referensbilder kan inte kombineras med start_frame eller end_frame och kräver en längd på åtta sekunder.

Seedance

De tre Seedance 2.0-nivåerna accepterar start_frame, end_frame, upp till 9 images, upp till 3 videos och upp till 3 audios, med följande begränsningar:

• Referenser kan inte kombineras med start_frame eller end_frame.
• Referensljud kräver minst en referensbild eller -video, till exempel för att driva läppsynkning.
• Det sammanlagda antalet referensfiler får inte överstiga 12.

Seedance 2.5 höjer gränserna till 30 images, 10 videos och 10 audios utan någon sammanlagd gräns, och tar bort regeln att referensljud behöver en tillhörande bild eller video, så endast ljud som indata accepteras. Referenser kan fortfarande inte kombineras med start_frame eller end_frame.

GPT Image

GPT Image-modellerna accepterar en mask tillsammans med images. Helt transparenta områden i masken anger var den första referensbilden får redigeras. En mask utan referensbilder avvisas.

Nästa steg