Références et ressources

Présentation

La plupart des modèles Image & Vidéo acceptent des médias avec le prompt : une première image pour une vidéo, des images à modifier, de l’audio pour la synchronisation labiale. Chaque champ média de l’API accepte un objet de référence plutôt que des octets bruts dans un format fixe, et chaque référence porte un type indiquant l’origine du média.

Les trois types sont interchangeables partout où une référence est acceptée. Un même champ peut donc recevoir une génération dans une requête, puis une ressource importée dans la suivante.

Enchaîner les générations

Une référence generation n’a pas besoin de pointer vers une génération terminée. Envoyez l’image, récupérez l’ID dans la réponse et transmettez-le directement dans la requête vidéo sans attendre : l’API place la vidéo après l’image dans la file et la démarre dès que l’image est terminée. Aucun fichier n’est importé entre les deux appels.

Définissez webhook sur la dernière génération de la chaîne pour ne plus avoir à attendre du tout. Les deux appels renvoient une réponse dès que leur génération est mise en file, l’ensemble du graphe s’exécute côté serveur et votre point de terminaison est appelé lorsque la génération finale atteint un état terminal.

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)

Seule la dernière génération nécessite webhook. Le définir aussi sur l’image fournit également un événement pour le résultat intermédiaire, ce qui est utile pour signaler la progression, mais n’est pas nécessaire pour exécuter la chaîne. Comme ailleurs, ce champ requiert un webhook abonné aux événements de génération. Consultez les webhooks Image & Vidéo pour en configurer un.

Sans point de terminaison pour recevoir les rappels, retirez webhook et interrogez plutôt la fin de la chaîne. L’image intermédiaire ne nécessite toujours pas d’interrogation propre. Attendez une seule fois, sur la dernière génération, selon l’intervalle de sa modalité, qui pour la vidéo ne doit pas dépasser une fois toutes les 10 secondes. Consultez les consignes d’interrogation .

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

Une génération qui référence un travail non terminé est créée immédiatement et reste en pending jusqu’à ce que tout ce qu’elle référence soit terminé, sans action supplémentaire de votre part pour la démarrer. Les chaînes peuvent avoir n’importe quelle profondeur et largeur : une génération peut attendre plusieurs références, elles-mêmes encore en attente. Vous pouvez donc envoyer un graphe entier en une seule fois et ne récupérer les résultats qu’à ses extrémités. Le temps passé en file d’attente ne compte pas dans le délai d’expiration de la génération.

Si une génération référencée échoue, la génération dépendante ne s’exécute jamais : elle échoue avec le motif dependency_failed et entraîne avec elle tout élément placé après elle dans la file. Aucun élément de la chaîne interrompue n’est facturé : une génération déjà payée est remboursée, et une génération dont le prix dépend d’une sortie référencée qui n’existe pas encore, comme une synchronisation labiale tarifée selon la durée d’une génération audio en attente, n’est facturée qu’à son démarrage. Un generation_id qui n’existe pas dans votre Workspace est rejeté dès l’appel de création. Une faute de frappe apparaît donc immédiatement, plutôt que comme une génération échouée.

Importer un média comme ressource

Importez un fichier dans l’API des ressources lorsque le média provient de l’extérieur d’ElevenLabs et que vous souhaitez le réutiliser entre plusieurs générations. Les ressources appartiennent au Workspace et sont conservées jusqu’à leur suppression.

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 réponse d’importation décrit la ressource stockée :

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

content_url est une URL signée valide pendant environ une heure et vaut null tant que l’importation est encore en cours de traitement. Récupérez à nouveau la ressource pour obtenir une URL actualisée.

Limites de stockage

Les ressources importées sont comptabilisées dans la limite totale de stockage du Workspace, qui dépend de votre forfait :

Seuls les fichiers que vous importez comptent dans cette limite, pas les sorties générées. Toute importation qui ferait dépasser la limite du Workspace est rejetée avec une erreur asset_storage_limit_exceeded avant que le fichier ne soit lu. Supprimez les ressources dont vous n’avez plus besoin pour libérer de l’espace, ou contactez le support pour augmenter cette limite.

Gérer les ressources

Listez les ressources en commençant par les plus récentes, filtrez-les éventuellement par nom, et parcourez les résultats avec le curseur de la réponse précédente. page_size accepte de 1 à 100 et utilise 30 par défaut.

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)

Récupérez ou supprimez une ressource individuelle par son ID. La suppression d’une ressource n’affecte pas les générations qui l’ont déjà utilisée.

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

Transmettre un média intégré

Une référence inline_base64 contient le média dans le corps de la requête, ce qui évite une importation distincte pour les entrées ponctuelles. Encodez le fichier avec l’alphabet base64 standard et déclarez son type 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",
            )
        ],
    )
)

Le contenu intégré est limité à 25 Mo par référence après décodage. Les fichiers plus volumineux doivent être envoyés vers l’API des ressources, qui accepte des importations beaucoup plus grandes et ne subit pas la surcharge de taille de base64. Chaque modalité accepte un ensemble fixe de types MIME :

Champs de référence par modèle

Les champs de référence sont nommés selon le rôle joué par le média. start_frame et end_frame sont des images uniques qui délimitent une vidéo, image et audio sont les entrées requises d’un modèle de synchronisation labiale, et les pluriels simples images, videos et audios sont des ressources de référence libres dont le modèle s’inspire.

Les champs qu’un modèle accepte, ainsi que les combinaisons valides, diffèrent selon les modèles. Un end_frame requiert toujours un start_frame. Toute violation d’une contrainte renvoie une erreur de validation indiquant le champ en cause. La génération ne démarre donc jamais et n’est jamais facturée.

Veo 3.1

Les deux modèles Veo acceptent start_frame, end_frame et jusqu’à trois entrées dans images. Contrairement aux autres modèles, chaque entrée de images encapsule la référence et le rôle qu’elle joue :

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

Une référence subject place le sujet de l’image ou les éléments de la scène dans la vidéo. Une référence style transfère son style visuel. Les images de référence ne peuvent pas être combinées avec start_frame ou end_frame, et nécessitent une durée de huit secondes.

Seedance

Les trois niveaux de Seedance 2.0 acceptent start_frame, end_frame, jusqu’à 9 images, jusqu’à 3 videos, et jusqu’à 3 audios, sous réserve des contraintes suivantes :

• Les références ne peuvent pas être combinées avec start_frame ou end_frame.
• L’audio de référence nécessite au moins une image ou une vidéo de référence, par exemple pour piloter la synchronisation labiale.
• Le nombre total de fichiers de référence ne doit pas dépasser 12.

Seedance 2.5 porte les plafonds à 30 images, 10 videos et 10 audios, sans total combiné, et supprime la règle selon laquelle l’audio de référence nécessite une image ou une vidéo associée. Les entrées audio seules sont donc acceptées. Les références ne peuvent toujours pas être combinées avec start_frame ou end_frame.

GPT Image

Les modèles GPT Image acceptent un mask avec images. Les zones entièrement transparentes du masque indiquent les emplacements où la première image de référence peut être modifiée. Un masque sans images de référence est rejeté.

Étapes suivantes