> 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. # 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](/docs/fr/eleven-api/guides/how-to/image-and-video/webhooks) 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. > **Warning** > > L'API Image & Vidéo nécessite un forfait Pro ou supérieur. Les appels provenant d'un Workspace d'un niveau inférieur sont > rejetés avec l'erreur `402 paid_plan_required`. Votre clé API doit également disposer de l'autorisation Image & Vidéo ou > Flows pour le Workspace. ## Générer une image #### Créer une clé API [Créez une clé API dans le Dashboard ici](https://elevenlabs.io/app/api/api-keys), que vous utiliserez pour [accéder à l’API](/docs/fr/api-reference/authentication) en toute sécurité. Stockez la clé comme secret géré et transmettez-la aux SDK, soit sous forme de variable d’environnement via un fichier `.env`, soit directement dans la configuration de votre application, selon vos préférences. **`.env`** ```js title=".env" ELEVENLABS_API_KEY= ``` #### Installer le SDK #### SDK Nous utiliserons également la bibliothèque `dotenv` pour charger notre clé API depuis une variable d'environnement. ```python pip install elevenlabs pip install python-dotenv ``` ```typescript npm install @elevenlabs/elevenlabs-js npm install dotenv ``` #### CLI Installez la CLI ElevenLabs. Homebrew (macOS) et Scoop (Windows) sont recommandés. **`Homebrew (macOS)`** ```bash title="Homebrew (macOS)" brew install elevenlabs/tap/elevenlabs ``` **`Scoop (Windows)`** ```powershell title="Scoop (Windows)" scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket scoop install elevenlabs ``` **`npm`** ```bash title="npm" npm install -g @elevenlabs/cli ``` **`curl`** ```bash title="curl" curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh ``` > **Tip** > > Vous travaillez avec un assistant de programmation IA ? Exécutez `elevenlabs generate-skills` dans votre projet pour créer un > fichier `SKILL.md` pour chaque groupe de commandes dans `skills/`, afin que votre assistant connaisse toutes les fonctionnalités de la CLI > sans que vous ayez à copier la documentation. Utilisez `--output-dir` pour les placer ailleurs. Cette commande lit la propre > définition d'API intégrée à la CLI, elle ne nécessite donc aucune clé API et fonctionne hors ligne, tout en restant synchronisée avec > la version de la CLI que vous avez installée. Authentifiez-vous ensuite, votre navigateur s'ouvrira pour autoriser la CLI : ```bash elevenlabs auth login ``` #### Soumettre la génération Chaque modèle possède sa propre classe de requête, dont les champs correspondent aux paramètres qu'il accepte. Changer de modèle peut donc modifier les champs disponibles. Les champs inconnus sont rejetés plutôt qu'ignorés. `webhook` demande que le résultat final soit livré aux webhooks de votre Workspace, afin que l'appel renvoie une réponse dès que la génération est mise en file d'attente. Cela nécessite un webhook abonné aux événements de génération ; consultez [les webhooks Image & Vidéo](/docs/fr/eleven-api/guides/how-to/image-and-video/webhooks) pour en configurer un, ou omettez ce champ et utilisez l'interrogation. #### SDK ```python # 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) ``` ```typescript // example.mts import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; import "dotenv/config"; const elevenlabs = new ElevenLabsClient(); const generation = await elevenlabs.flows.image.create({ modelId: "gemini-3-pro-image", prompt: "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", aspectRatio: "16:9", resolution: "2K", webhook: { type: "all" }, }); console.log(generation.id, generation.status); ``` #### CLI La CLI soumet la même requête au format JSON, puis interroge l'API jusqu'à la fin de la génération et télécharge le résultat : ```bash # 1. Submit the generation (note the returned id) elevenlabs flows image create --json '{ "model_id": "gemini-3-pro-image", "prompt": "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic", "aspect_ratio": "16:9", "resolution": "2K" }' # 2. Poll until the status is "completed" elevenlabs flows image get --generation-id --query status # 3. Read the signed content URL, then download the image elevenlabs flows image get --generation-id --query content_url curl -o corgi.png "" ``` La réponse contient uniquement l'ID de la génération. Une génération nouvellement créée est toujours à l'état `pending` : ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "pending" } ``` #### Récupérer le résultat Comme la requête utilise `webhook`, ElevenLabs envoie un événement `flows_generation` à votre point de terminaison lorsque la génération atteint l'état `completed` ou `failed`. Les `data` de l'événement sont identiques à celles renvoyées par le point de terminaison GET, et [les webhooks Image & Vidéo](/docs/fr/eleven-api/guides/how-to/image-and-video/webhooks) expliquent comment créer le gestionnaire qui les reçoit. Si vous ne disposez pas d'un point de terminaison pour recevoir des rappels, retirez `webhook` de la requête ci-dessus et utilisez l'interrogation. Récupérez la génération jusqu'à ce que son statut soit `completed` ou `failed`, en laissant au moins deux secondes entre les requêtes pour une image. Consultez les [consignes d'interrogation](#polling-guidelines) pour connaître les intervalles à utiliser selon le type de média. ```python maxLines=0 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) ``` ```typescript maxLines=0 import { writeFile } from "fs/promises"; let result = await elevenlabs.flows.image.get(generation.id); while (result.status === "pending" || result.status === "generating") { await new Promise((resolve) => setTimeout(resolve, 2000)); result = await elevenlabs.flows.image.get(generation.id); } if (result.status === "failed") { throw new Error(`${result.failureReason}: ${result.errorMessage}`); } const response = await fetch(result.contentUrl); await writeFile("corgi.png", Buffer.from(await response.arrayBuffer())); ``` Dans les deux cas, une génération terminée contient les mêmes champs : ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "completed", "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb", "content_mime_type": "image/png" } ``` #### Exécuter le code ```python python example.py ``` ```typescript npx tsx example.mts ``` La génération est mise en file d'attente et son ID s'affiche. Avec la livraison par webhook, l'image arrive sur votre point de terminaison ; avec la variante par interrogation, elle est enregistrée dans `corgi.png`. ## 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. ```python 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) ``` ```typescript const generation = await elevenlabs.flows.video.create({ modelId: "veo-3.1-fast-generate-001", prompt: "A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic", durationSecs: 8, aspectRatio: "16:9", resolution: "1080p", generateAudio: true, webhook: { type: "all" }, }); console.log(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](/docs/fr/eleven-api/guides/how-to/image-and-video/webhooks) pour configurer un webhook et écrire le gestionnaire qui reçoit cet événement. > **Warning** > > `webhook` nécessite au moins un webhook de Workspace abonné aux événements de génération. Sans cela, > l'appel de création est rejeté au lieu de démarrer une génération dont le résultat ne peut être livré. Retirez > ce champ pour utiliser l'interrogation avec `flows.video.get`, et n'interrogez pas plus d'une fois toutes les 10 > secondes. ## 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. | | Livraison par webhook | Interrogation | | ----------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | Idéal pour | Par défaut pour les deux types de média et la production | Scripts et environnements sans point de terminaison public | | Nécessite | Un point de terminaison HTTPS abonné aux événements de génération | Rien | | Coût de l'attente | Aucun ; vous êtes appelé lorsque la génération se termine | Une requête par interrogation et par génération | 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 : ```python from elevenlabs import WebhookTarget_Ids webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"]) ``` ```typescript const webhook = { type: "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](/docs/fr/eleven-api/guides/how-to/image-and-video/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](/docs/fr/eleven-api/resources/errors#rate-limiting-and-concurrency), 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. | Statut | Signification | | ------------ | --------------------------------------------------------------------------------------- | | `pending` | La génération est mise en file d'attente. C'est le statut de toute nouvelle génération. | | `generating` | Le modèle est en cours d'exécution. | | `completed` | La sortie est prête. La réponse contient `content_url` et `content_mime_type`. | | `failed` | La génération n'a produit aucune sortie. La réponse contient les détails de l'échec. | > **Warning** > > `content_url` est une URL signée qui expire environ une heure après le renvoi de la réponse. Récupérez > à nouveau la génération pour obtenir une URL récente plutôt que de stocker l'URL signée elle-même. ## 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 : ```json { "id": "JWr5N6X9ZTqf8jD2LmQb", "status": "failed", "failure_reason": "moderated", "error_message": "The prompt was rejected by content moderation. You were not charged for this generation." } ``` | `failure_reason` | Cause | | -------------------- | --------------------------------------------------------------------------- | | `timeout` | Le modèle n'a pas renvoyé de résultat à temps. | | `model_error` | Le fournisseur du modèle a renvoyé une erreur ou n'a produit aucune sortie. | | `moderated` | L'invite ou une entrée a été rejetée par la modération de contenu. | | `invalid_parameters` | Les paramètres ont été rejetés une fois la génération arrivée au modèle. | | `dependency_failed` | Une génération référencée dont celle-ci dépend a échoué. | | `charging_failed` | Le Workspace n'a pas pu être facturé pour la génération. | | `internal_error` | Une erreur inattendue s'est produite. | 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](/docs/fr/eleven-creative/playground/image-video) 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. ```python 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) ``` ```typescript let page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed" }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } while (page.hasMore) { page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed", cursor: page.nextCursor, }); for (const item of page.generations) { console.log(item.id, item.contentUrl); } } ``` `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. > **Warning** > > Les modèles ByteDance sont désactivés par défaut et nécessitent une approbation explicite avant utilisation. Tant que l’accès n’est pas > accordé, toute requête désignant l’un de ces modèles est rejetée avec une erreur `model_access_denied`. Les clients Enterprise > peuvent contacter le support pour demander l’accès. ### Modèles d’image | `model_id` | Images de référence | Contrôles de sortie | | ----------------------------- | -------------------------- | ------------------------------------------------------------------------ | | `gpt-image-1` | Jusqu’à 5, plus un `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-1.5` | Jusqu’à 5, plus un `mask` | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background` | | `gpt-image-2` | Jusqu’à 10, plus un `mask` | 15 formats d’image, `resolution` (1K, 2K, 4K), `quality` | | `gpt-image-2.5-sunburst` | Jusqu’à 10, plus un `mask` | 15 formats d’image, `resolution` (1K, 2K, 4K), `quality` (jusqu’à `max`) | | `gpt-image-2.5-flare` | Jusqu’à 10, plus un `mask` | 15 formats d’image, `resolution` (1K, 2K, 4K), `quality` (jusqu’à `max`) | | `gemini-2.5-flash-image` | Jusqu’à 5 | `aspect_ratio` | | `gemini-3-pro-image` | Jusqu’à 10 | `aspect_ratio`, `resolution` (1K, 2K, 4K) | | `gemini-3.1-flash-image` | Jusqu’à 14 | `aspect_ratio` (dont 1:4, 4:1, 1:8, 8:1), `resolution` (512 à 4K) | | `gemini-3.1-flash-lite-image` | Jusqu’à 14 | `aspect_ratio`, `resolution` (1K) | | `bytedance-seedream-5-lite` | Jusqu’à 10 | `aspect_ratio`, `resolution` (2K, 3K), `seed` | | `bytedance-seedream-5-pro` | Jusqu’à 10 | `aspect_ratio`, `resolution` (1K, 2K), `seed` | 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 | `model_id` | Entrées média | Contrôles de sortie | | ---------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-001` | `start_frame`, `end_frame`, jusqu’à 3 `images` avec un `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `veo-3.1-fast-generate-001` | `start_frame`, `end_frame`, jusqu’à 3 `images` avec un `role` | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` | | `bytedance-seedance-v2` | `start_frame`, `end_frame`, jusqu’à 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 à 15), 7 formats d’image, `resolution` (480p à 4k), `generate_audio` | | `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, jusqu’à 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 à 15), 7 formats d’image, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, jusqu’à 9 `images`, 3 `videos`, 3 `audios` | `duration_secs` (4 à 15), 7 formats d’image, `resolution` (480p, 720p), `generate_audio` | | `bytedance-seedance-v2.5` | `start_frame`, `end_frame`, jusqu’à 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (4 à 30), 7 formats d’image, `resolution` (480p, 720p), `generate_audio` | | `creatify-aurora` | `image` et `audio`, tous deux requis | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale` | Pour connaître les capacités, la disponibilité et les tarifs des modèles, consultez la [présentation d’Image & Vidéo](/docs/fr/overview/capabilities/image-video). ## Étapes suivantes #### [Références et ressources](/docs/fr/eleven-api/guides/how-to/image-and-video/references) Guidez une génération avec une génération précédente, une ressource importée ou un média intégré. #### [Webhooks](/docs/fr/eleven-api/guides/how-to/image-and-video/webhooks) Recevez le résultat d’une génération au lieu de l’interroger. #### [Guide de l’API](/docs/fr/api-reference/flows/image/create) Explorez les points de terminaison d’image, de vidéo et de ressources.