> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Riferimenti e asset > **Note** > > **Guida pratica** · Presuppone che tu abbia completato il [quickstart di Immagini e Video ](/docs/it/eleven-api/guides/cookbooks/image-and-video). ## 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. | `type` | Indica | Campi | | --------------- | -------------------------------------------------------------------- | ----------------------------- | | `generation` | L'output di un'altra generazione, completata o ancora in esecuzione. | `generation_id` | | `asset` | Un file caricato nell'API degli asset. | `asset_id` | | `inline_base64` | Contenuti codificati direttamente nel body della richiesta. | `content_base64`, `mime_type` | 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. ```python maxLines=0 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) ``` ```typescript maxLines=0 const still = await elevenlabs.flows.image.create({ modelId: "gemini-3-pro-image", prompt: "A lighthouse on a cliff at dawn, heavy fog rolling in from the sea", aspectRatio: "16:9", }); // `still` is still pending here. Submitting now queues the video behind it. const clip = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "The fog thickens and the beam sweeps across the water", startFrame: { type: "generation", generationId: still.id }, durationSecs: 8, webhook: { type: "all" }, }); console.log(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](/docs/it/eleven-api/guides/how-to/image-and-video/webhooks) 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 ](/docs/it/eleven-api/guides/cookbooks/image-and-video#polling-guidelines). ```python import time while True: result = elevenlabs.flows.video.get(clip.id) if result.status in ("completed", "failed"): break time.sleep(10) ``` ```typescript let result = await elevenlabs.flows.video.get(clip.id); while (result.status === "pending" || result.status === "generating") { await new Promise((resolve) => setTimeout(resolve, 10000)); result = await elevenlabs.flows.video.get(clip.id); } ``` 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. ```python 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), ) ) ``` ```typescript import { createReadStream } from "fs"; const asset = await elevenlabs.assets.create({ asset: createReadStream("lighthouse.png"), name: "lighthouse.png", }); console.log(asset.assetId); const clip = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "The beam sweeps across the water as the fog thickens", startFrame: { type: "asset", assetId: asset.assetId }, }); ``` La risposta al caricamento descrive l'asset archiviato: ```json { "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. > **Warning** > > L'accesso all'API degli asset con una chiave API richiede un piano Pro o superiore, lo stesso livello degli > endpoint di generazione. ### Limiti di archiviazione Gli asset caricati vengono conteggiati rispetto a un limite di archiviazione totale per il workspace, che dipende dal tuo piano: | Piano | Archiviazione asset | | ---------- | ------------------- | | Pro | 11 GB | | Scale | 33 GB | | Business | 111 GB | | Enterprise | 333 GB | 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. ```python 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) ``` ```typescript let page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse" }); for (const asset of page.assets) { console.log(asset.assetId, asset.name, asset.mimeType); } if (page.hasMore) { page = await elevenlabs.assets.list({ pageSize: 20, search: "lighthouse", cursor: page.nextCursor, }); } ``` Recupera o elimina un singolo asset tramite ID. L'eliminazione di un asset non influisce sulle generazioni che lo hanno già utilizzato. ```python asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4") elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4") ``` ```typescript const asset = await elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4"); await 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. ```python 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", ) ], ) ) ``` ```typescript import { readFile } from "fs/promises"; const encoded = (await readFile("headshot.jpg")).toString("base64"); const generation = await elevenlabs.flows.image.create({ modelId: "gpt-image-2", prompt: "Replace the background with a softly lit studio backdrop", images: [ { type: "inline_base64", contentBase64: encoded, mimeType: "image/jpeg", }, ], }); ``` > **Warning** > > I contenuti multimediali inline vengono archiviati come asset effimeri senza garanzia di conservazione e possono essere eliminati una volta > completata la generazione. Carica invece il file nell'API degli asset quando devi fare riferimento allo > stesso input più di una volta. 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: | Riferimento | `mime_type` accettati | | ----------- | ------------------------------------------------------------------- | | Immagine | `image/jpeg`, `image/png`, `image/webp`, `image/heic`, `image/heif` | | Audio | `audio/mpeg`, `audio/wav` | | Video | `video/mp4`, `video/quicktime`, `video/webm` | ## 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: ```json { "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 > **Warning** > > I modelli ByteDance sono disabilitati per impostazione predefinita e richiedono un'approvazione esplicita prima dell'uso. I clienti Enterprise > possono contattare l'assistenza per richiedere l'accesso. 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 #### [Webhook](/docs/it/eleven-api/guides/how-to/image-and-video/webhooks) Ricevi il risultato di una generazione invece di eseguire il polling. #### [Panoramica di Immagini e Video](/docs/it/overview/capabilities/image-video) Confronta le funzionalità dei modelli, i formati supportati e la disponibilità. #### [Riferimento API](/docs/it/api-reference/flows/image/create) Esplora gli endpoint per immagini, video e asset.