Démarrage rapide d’Image & Vidéo

L’API Image & Vidéo est asynchrone. Vous soumettez une génération, puis, une fois terminée, téléchargez le résultat depuis une URL signée. Les images et les vidéos disposent de points de terminaison distincts, mais les structures des requêtes et des réponses sont les mêmes pour les deux.

Vous pouvez récupérer le résultat de deux façons. La livraison par webhook est recommandée et utilisée dans les exemples ci-dessous : ElevenLabs appelle votre point de terminaison dès qu’une génération atteint un statut final, vous ne perdez donc pas de temps à attendre. L’interrogation est une solution de repli lorsque vous ne disposez d’aucun point de terminaison pour recevoir un rappel, et chaque exemple indique comment y recourir.

Générer une image

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

Générer une vidéo

Les générations vidéo utilisent flows.video et suivent le même processus de soumission et de récupération. La génération d’une vidéo peut prendre plusieurs minutes ; cet exemple utilise donc la livraison par webhook avec webhook plutôt que d’attendre le résultat.

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)

L’appel renvoie une réponse dès que la génération est mise en file d’attente, et le résultat final est livré à chaque webhook de votre Workspace abonné aux événements de génération. La sortie vidéo est au format MP4 ; la charge utile terminée indique donc un content_mime_type de video/mp4. Consultez les webhooks Image & Vidéo pour configurer un webhook et écrire le gestionnaire qui reçoit cet événement.

Récupérer les résultats

Les webhooks et l’interrogation renvoient la même charge utile. Le choix dépend donc de la façon dont vous attendez le résultat, et non du résultat obtenu.

Utilisez les webhooks dès que possible. Utilisez l’interrogation lorsque vous n’avez aucun endroit où recevoir un rappel, et respectez les intervalles ci-dessous dans ce cas.

Choisir des cibles de webhook

webhook accepte deux formes. WebhookTarget_All atteint chaque webhook abonné aux événements de génération, ce qui constitue le bon choix par défaut, car il reste valable lorsque des webhooks sont remplacés ou renouvelés. WebhookTarget_Ids limite la livraison à des webhooks spécifiques, lorsqu’un Workspace distribue les événements à plusieurs consommateurs et qu’une tâche donnée ne doit atteindre qu’un seul d’entre eux :

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

Chaque ID doit déjà être abonné aux événements de génération ; indiquer un webhook non abonné est rejeté plutôt que silencieusement ignoré. La charge utile livrée est identique à celle renvoyée par le point de terminaison GET ; un gestionnaire conçu pour l’un fonctionne donc pour l’autre. Le guide des webhooks explique comment configurer un webhook, vérifier la signature et gérer l’événement.

Consignes d’interrogation

La durée d’exécution d’une génération dépend du modèle, de la résolution et, pour les vidéos, de la durée. Interrogez donc à un intervalle adapté à votre demande plutôt que dans une boucle fixe :

• Images : n’interrogez pas plus d’une fois toutes les 2 secondes. La plupart sont terminées en quelques secondes.
• Vidéo : n’interrogez pas plus d’une fois toutes les 10 secondes. Prévoyez des minutes, non des secondes, et adaptez l’intervalle en fonction de duration_secs et de resolution.

Deux règles s’appliquent aux deux cas. Augmentez le délai lorsqu’une génération est longue : doubler l’intervalle jusqu’à environ une minute évite qu’une génération lente ne se transforme en centaines de requêtes. Fixez également une limite à la boucle, afin qu’une génération bloquée se termine par un délai d’expiration dans votre propre code plutôt que par une boucle illimitée.

Interroger plus fréquemment ne vous apporte rien : le statut d’une génération ne change pas plus tôt parce que vous l’avez demandé deux fois. Une interrogation agressive et prolongée peut renvoyer des réponses 429, que vous devez traiter avec un backoff exponentiel.

Cycle de vie d’une génération

Une génération passe par quatre statuts. Les deux statuts finaux contiennent des champs différents ; vérifiez donc status avant de lire le reste de la réponse.

Gérer les échecs

Une génération en échec indique une catégorie failure_reason accompagnée d’un error_message lisible par un humain :

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

Les générations en échec ne sont pas facturées. Les problèmes de paramètres détectables en amont, comme un champ non pris en charge, une valeur hors de la plage autorisée d’un modèle ou une combinaison non valide d’entrées de référence, sont plutôt rejetés par la requête de création, avant le début de toute génération.

Tarification

Les générations sont facturées en crédits. Le coût dépend du modèle, des paramètres que vous choisissez, tels que la résolution et la durée, ainsi que des entrées que vous fournissez. Une génération coûte le même prix via l’API que dans l’application ElevenLabs, où son coût est affiché avant la soumission. Consultez Image & Vidéo dans le playground pour savoir comment est présenté le coût d’une combinaison donnée de modèle et de paramètres.

Lister vos générations

Chaque point de terminaison liste les générations créées par son intermédiaire, de la plus récente à la plus ancienne. Les résultats sont limités à votre Workspace et à cette API ; les générations créées dans l’application ElevenLabs n’apparaissent donc pas.

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 accepte les valeurs de 1 à 100 et vaut 30 par défaut. Transmettez status pour ne renvoyer que les générations dans un état donné du cycle de vie, et model_id pour ne renvoyer que les générations d’un seul modèle. Traitez next_cursor comme opaque : retransmettez exactement la valeur reçue et arrêtez-vous lorsque has_more est false.

Modèles disponibles

L’API expose un sous-ensemble des modèles disponibles dans l’application ElevenLabs. Chaque modèle accepte uniquement les paramètres qui lui sont attribués. L’envoi d’un champ pris en charge par un autre modèle renvoie une erreur de validation.

Modèles d’image

Les modèles GPT Image 2.5 acceptent les valeurs low, medium, high, xhigh et max pour quality, et utilisent high par défaut. GPT Image 2 s’arrête à high et utilise medium par défaut.

Modèles vidéo

Pour connaître les capacités, la disponibilité et les tarifs des modèles, consultez la présentation d’Image & Vidéo.

Étapes suivantes