Guida rapida a Immagini e Video

L’API Immagini e Video è asincrona. Invi una generazione e, una volta completata, scarichi il risultato da un URL firmato. Immagini e video hanno endpoint separati, ma la struttura delle richieste e delle risposte è la stessa per entrambi.

Esistono due modi per ottenere il risultato. La consegna tramite webhook è quella consigliata, nonché quella usata negli esempi seguenti: ElevenLabs chiama il tuo endpoint nel momento in cui una generazione raggiunge uno stato terminale, quindi non vengono consumate risorse nell’attesa. Il polling è l’alternativa quando non hai un endpoint che possa ricevere un callback, e ogni esempio mostra come passare a questa opzione.

Genera un’immagine

ELEVENLABS_API_KEY=<your_api_key_here>

pip install elevenlabs
pip install python-dotenv

# example.py
import os
from dotenv import load_dotenv
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
        aspect_ratio="16:9",
        resolution="2K",
        webhook=WebhookTarget_All(),
    )
)
print(generation.id, generation.status)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}

import time
import requests
while True:
    result = elevenlabs.flows.image.get(generation.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(2)
if result.status == "failed":
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")
with open("corgi.png", "wb") as f:
    f.write(requests.get(result.content_url).content)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}

python example.py

Genera un video

Le generazioni video usano flows.video e seguono lo stesso schema di invio e recupero. Un video può richiedere diversi minuti, quindi questo esempio abilita la consegna tramite webhook con webhook invece di attendere il risultato.

from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All
generation = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
        duration_secs=8,
        aspect_ratio="16:9",
        resolution="1080p",
        generate_audio=True,
        webhook=WebhookTarget_All(),
    )
)
print(generation.id)

La chiamata restituisce un risultato non appena la generazione viene messa in coda e il risultato completato viene consegnato a ogni webhook del tuo workspace iscritto agli eventi di generazione. L’output video è in formato MP4, quindi il payload completato riporta content_mime_type come video/mp4. Consulta i webhook per Immagini e Video per configurare un webhook e scrivere l’handler che riceve questo evento.

Recupero dei risultati

Webhook e polling restituiscono lo stesso payload, quindi la scelta riguarda il modo in cui attendi il risultato, non ciò che ottieni.

Usa i webhook quando possibile. Ricorri al polling quando non hai dove ricevere un callback e, quando lo usi, segui gli intervalli indicati di seguito.

Scelta delle destinazioni webhook

webhook accetta due forme. WebhookTarget_All raggiunge ogni webhook iscritto agli eventi di generazione, ed è l’opzione predefinita corretta perché continua a funzionare se i webhook vengono ruotati o sostituiti. WebhookTarget_Ids limita la consegna a webhook specifici, quando un workspace distribuisce eventi a più destinatari e un determinato job deve raggiungerne uno solo:

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

Ogni ID deve essere già iscritto agli eventi di generazione; indicare un webhook non iscritto viene rifiutato anziché ignorato in silenzio. Il payload consegnato è identico a quello restituito dall’endpoint GET, quindi un handler scritto per uno funziona anche per l’altro. La guida ai webhook spiega come configurare un webhook, verificare la firma e gestire l’evento.

Linee guida sul polling

Il runtime di una generazione dipende dal modello, dalla risoluzione e, per i video, dalla durata, quindi esegui il polling con un intervallo adeguato a ciò che hai richiesto anziché con un ciclo a intervallo fisso:

• Immagini: esegui il polling non più di una volta ogni 2 secondi. La maggior parte viene completata entro pochi secondi.
• Video: esegui il polling non più di una volta ogni 10 secondi. Considera minuti, non secondi, e adatta l’intervallo in base a duration_secs e resolution.

Due regole valgono per entrambi. Riduci la frequenza quando una generazione richiede più tempo del previsto — raddoppiare l’intervallo fino a circa un minuto evita che una generazione lenta si trasformi in centinaia di richieste. E imposta un limite al ciclo, così una generazione bloccata termina con un timeout nel tuo codice anziché con un ciclo senza limiti.

Un polling più rapido non offre alcun vantaggio: lo stato di una generazione non cambia prima solo perché lo hai richiesto due volte. Un polling aggressivo e prolungato può restituire risposte 429, che dovresti gestire con un backoff esponenziale.

Ciclo di vita della generazione

Una generazione passa attraverso quattro stati. I due stati terminali contengono campi diversi, quindi verifica status prima di leggere il resto della risposta.

Gestione degli errori

Una generazione non riuscita riporta una categoria failure_reason insieme a un messaggio error_message leggibile:

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

Le generazioni non riuscite non vengono addebitate. I problemi relativi ai parametri che possono essere rilevati in anticipo — un campo non supportato, un valore al di fuori dell’intervallo consentito da un modello o una combinazione non valida di input di riferimento — vengono invece rifiutati dalla richiesta di creazione, prima che inizi qualsiasi generazione.

Prezzi

Le generazioni vengono addebitate in crediti. Il costo dipende dal modello, dai parametri scelti come risoluzione e durata e dagli input forniti. Una generazione costa quanto nell’API quanto nell’app ElevenLabs, dove il costo viene mostrato prima dell’invio. Consulta Immagini e Video nel playground per scoprire come viene presentato il costo di una determinata combinazione di modello e impostazioni.

Elenca le tue generazioni

Ogni endpoint elenca le generazioni create tramite esso, dalla più recente alla meno recente. I risultati sono limitati al tuo workspace e a questa API, quindi le generazioni create nell’app ElevenLabs non vengono visualizzate.

page = elevenlabs.flows.image.list(page_size=20, status="completed")
for item in page.generations:
    print(item.id, item.content_url)
while page.has_more:
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
    for item in page.generations:
        print(item.id, item.content_url)

page_size accetta valori da 1 a 100 e il valore predefinito è 30. Passa status per restituire solo le generazioni in un determinato stato del ciclo di vita e model_id per restituire solo le generazioni di un singolo modello. Considera next_cursor come opaco: passa nuovamente il valore esatto e interrompi quando has_more è false.

Modelli disponibili

L’API espone un sottoinsieme dei modelli disponibili nell’app ElevenLabs. Ogni modello accetta solo i parametri elencati per quel modello: l’invio di un campo supportato da un altro modello restituisce un errore di convalida.

Modelli di immagini

I modelli GPT Image 2.5 accettano valori quality di low, medium, high, xhigh e max e usano high per impostazione predefinita. GPT Image 2 arriva fino a high e usa medium per impostazione predefinita.

Modelli video

Per funzionalità, disponibilità e prezzi dei modelli, consulta la panoramica di Immagini e Video.

Passaggi successivi