Riferimenti e asset

Panoramica

La maggior parte dei modelli di Immagini e Video accetta contenuti multimediali insieme al prompt: un primo fotogramma per un video, immagini da modificare, audio con cui effettuare il lip-sync. Ogni campo dell’API che accetta contenuti multimediali riceve un oggetto di riferimento anziché byte non elaborati in un formato fisso, e ogni riferimento è contrassegnato con un type che indica da dove provengono i contenuti.

I tre tipi sono intercambiabili ovunque sia accettato un riferimento, quindi lo stesso campo può ricevere una generazione in una richiesta e un asset caricato in quella successiva.

Collega una generazione alla successiva

Un riferimento generation non deve necessariamente indicare una generazione completata. Invia l’immagine, estrai l’ID dalla risposta e passalo direttamente alla richiesta video senza attendere: l’API mette in coda il video dopo l’immagine e lo avvia non appena l’immagine viene completata. Non viene caricato nulla tra le due chiamate.

Imposta webhook sull’ultima generazione della catena e non dovrai attendere nulla. Entrambe le chiamate restituiscono non appena la relativa generazione viene messa in coda, l’intero grafo viene eseguito lato server e il tuo endpoint viene chiamato quando la generazione finale raggiunge uno stato terminale.

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)

Solo l’ultima generazione richiede webhook. Impostandolo anche sull’immagine riceverai un evento anche per il risultato intermedio, utile per segnalare l’avanzamento ma non necessario per eseguire la catena. Come in altri casi, il campo richiede un webhook sottoscritto agli eventi di generazione; consulta Webhook di Immagini e Video per configurarne uno.

Senza un endpoint per ricevere callback, ometti webhook ed esegui invece il polling alla fine della catena. Anche l’ immagine intermedia non richiede un proprio polling: attendi una sola volta, sull’ultima generazione, all’ intervallo previsto per la relativa modalità, che per i video non deve superare una volta ogni 10 secondi. Consulta le linee guida per il polling .

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

Una generazione che fa riferimento a elaborazioni non completate viene creata immediatamente e rimane in pending finché non viene completato tutto ciò a cui fa riferimento, senza che tu debba fare altro per avviarla. Le catene possono avere qualsiasi profondità e larghezza: una generazione può attendere più riferimenti, ciascuno a sua volta ancora in attesa, quindi un intero grafo può essere inviato in un’unica operazione e recuperato solo alle sue foglie. Il tempo trascorso in coda non viene conteggiato nel timeout della generazione.

Se una generazione referenziata non riesce, quella dipendente non viene mai eseguita: non riesce con un motivo dependency_failed e trascina con sé tutto ciò che è in coda dopo di essa. Non viene addebitato nulla nella catena interrotta: una generazione già pagata viene rimborsata, mentre una il cui prezzo dipende da un output referenziato che non esiste ancora, come un lip-sync il cui prezzo dipende dalla durata di una generazione audio in attesa, viene addebitata solo al suo avvio. Un generation_id che non esiste nel tuo workspace viene rifiutato nella chiamata di creazione stessa, quindi un errore di battitura emerge immediatamente anziché come generazione non riuscita.

Carica contenuti multimediali come asset

Carica un file nell’API degli asset quando i contenuti multimediali provengono dall’esterno di ElevenLabs e vuoi riutilizzarli tra diverse generazioni. Gli asset appartengono al workspace e persistono finché non li elimini.

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

La risposta al caricamento descrive l’asset archiviato:

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

content_url è un URL firmato valido per circa un’ora ed è null mentre il caricamento è ancora in elaborazione. Recupera di nuovo l’asset per ottenere un URL aggiornato.

Limiti di archiviazione

Gli asset caricati vengono conteggiati rispetto a un limite di archiviazione totale per il workspace, che dipende dal tuo piano:

Solo i file che carichi vengono conteggiati nel limite; gli output generati no. Un caricamento che porterebbe il workspace oltre il limite viene rifiutato con un errore asset_storage_limit_exceeded prima che il file venga letto. Elimina gli asset che non ti servono più per liberare spazio oppure contatta l’assistenza per aumentare il limite.

Gestisci gli asset

Elenca gli asset dal più recente, filtrando facoltativamente per nome, e sfoglia i risultati tramite il cursore della risposta precedente. page_size accetta da 1 a 100 e il valore predefinito è 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)

Recupera o elimina un singolo asset tramite ID. L’eliminazione di un asset non influisce sulle generazioni che lo hanno già utilizzato.

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

Passa contenuti multimediali inline

Un riferimento inline_base64 trasporta i contenuti multimediali nel body della richiesta, evitando un caricamento separato per input una tantum. Codifica il file con l’alfabeto base64 standard e dichiarane il tipo MIME.

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

I contenuti inline sono limitati a 25 MB per riferimento dopo la decodifica. I file più grandi vanno caricati nell’API degli asset, che accetta upload molto più grandi e non comporta la penalità di dimensione di base64. Ogni modalità accetta un set fisso di tipi MIME:

Campi di riferimento per modello

I campi di riferimento prendono il nome dal ruolo svolto dai contenuti multimediali. start_frame e end_frame sono singole immagini che delimitano un video, image e audio sono gli input obbligatori di un modello di lip-sync e i plurali semplici images, videos e audios sono materiali di riferimento in formato libero da cui il modello attinge.

I campi accettati da un modello e le combinazioni valide variano da modello a modello. Un end_frame richiede sempre un start_frame. La violazione di un vincolo restituisce un errore di convalida che indica il campo interessato, quindi la generazione non viene mai avviata né addebitata.

Veo 3.1

Entrambi i modelli Veo accettano start_frame, end_frame e fino a tre elementi in images. A differenza degli altri modelli, ogni elemento in images racchiude il riferimento insieme al ruolo che svolge:

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

Un riferimento subject inserisce nel video il soggetto o gli elementi della scena dell’immagine; un riferimento style ne trasferisce lo stile visivo. Le immagini di riferimento non possono essere combinate con start_frame o end_frame e richiedono una durata di otto secondi.

Seedance

I tre livelli Seedance 2.0 accettano start_frame, end_frame, fino a 9 images, fino a 3 videos e fino a 3 audios, nel rispetto dei seguenti vincoli:

• I riferimenti non possono essere combinati con start_frame o end_frame.
• L’audio di riferimento richiede almeno un’immagine o un video di riferimento, ad esempio per eseguire il lip-sync.
• Il numero totale di file di riferimento non deve superare 12.

Seedance 2.5 aumenta i limiti a 30 images, 10 videos e 10 audios senza un totale combinato e rimuove la regola secondo cui l’audio di riferimento necessita di un’immagine o un video di accompagnamento, quindi l’input composto solo da audio è accettato. I riferimenti non possono comunque essere combinati con start_frame o end_frame.

GPT Image

I modelli GPT Image accettano una mask insieme a images. Le aree completamente trasparenti della maschera indicano dove può essere modificata la prima immagine di riferimento. Una maschera senza immagini di riferimento viene rifiutata.

Passaggi successivi