Exécuter le template de votre équipe

Ce guide explique comment exécuter un template conçu par votre équipe : copier son code, transmettre chaque type d’entrée, choisir les webhooks qui recevront le résultat, figer une version et lire les sorties.

Avant de commencer

• Le template est partagé avec votre Workspace. Son auteur définit ce paramètre sous Workspace dans les options de partage du template ; un template partagé en mode Just me ne peut être exécuté que par son auteur.
• Votre Workspace dispose d’un webhook abonné aux exécutions de templates. La section Avant de commencer du guide sur les webhooks Image & Vidéo explique comment en configurer un.
• Votre Workspace dispose d’un forfait Pro ou supérieur, et votre clé API possède l’autorisation Image & Vidéo.

Copier le code du template

Ouvrez le template dans l’application ElevenLabs et sélectionnez son onglet API. Dans Flows, l’auteur du template peut ouvrir le même code à partir du bouton API dans la barre latérale du template.

L’onglet génère ses extraits à partir des entrées et sorties publiées du template. Sous Choisir comment obtenir le résultat, sélectionnez Webhook, puis sélectionnez Python ou TypeScript au-dessus du code. L’onglet affiche un extrait Démarrer une exécution et un extrait Gérer le résultat. Copiez Démarrer une exécution à l’endroit où votre application démarre les exécutions, et Gérer le résultat dans votre gestionnaire de webhook. Chaque espace réservé dans Démarrer une exécution correspond à une entrée, et Gérer le résultat lit chaque sortie à l’aide de son id.

Transmettre chaque entrée

Chaque entrée de la version exécutée doit recevoir une valeur, identifiée par l’id de l’entrée. Le format de la valeur dépend du type d’entrée :

Les entrées de type object ne peuvent pas encore être transmises via l’API ; l’onglet API en avertit.

run = client.flows.templates.runs.create(
    template_id="Yz4DETxRv4uXyIo5PnEy",
    version_id="Kqs4nRrpndEjQ54BhbwE",
    inputs={
        "headline": "Autumn collection, 20% off",
        "duration_secs": 8,
        "product_photo": TemplateInputReference_Asset(asset_id="Rk3pQm8vTzL1yWcN0bJd"),
        "previous_shot": TemplateInputReference_Generation(generation_id="JWr5N6X9ZTqf8jD2LmQb"),
        "phone_photo": TemplateInputReference_InlineBase64(
            content_base_64=photo,
            mime_type="image/jpeg",
        ),
        "narrator": TemplateInputReference_Voice(voice_id="JBFqnCBsd6RMkjVDRZzb"),
    },
    webhook=WebhookTarget_All(),
)

Les id d’entrée conservent l’orthographe donnée par le template dans les deux SDK ; seuls les champs d’une référence, tels que assetId, utilisent la notation camelCase en TypeScript.

Les données base64 sont limitées à 25 Mo une fois décodées et ne sont pas conservées après l’exécution. Pour transmettre le même fichier à de nombreuses exécutions, importez-le une fois et transmettez son id de ressource, comme expliqué dans Références et ressources.

Obtenir le résultat

Un webhook reçoit l’exécution terminée en tant qu’événement flows_template_run. Les extraits Webhook de l’onglet API transmettent {"type": "all"}, ce qui envoie l’exécution terminée à chaque webhook du Workspace abonné aux exécutions de templates. Pour l’envoyer à des webhooks spécifiques, indiquez leurs ID :

webhook=WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

Chaque webhook indiqué doit être abonné aux exécutions de templates. Une exécution qui demande un webhook lorsqu’aucun n’est abonné est rejetée : une exécution ne se termine donc jamais sans destination pour transmettre son résultat.

Pour un script ponctuel ou une tâche par lots, create_and_wait, utilisé dans le guide de démarrage rapide des templates, attend plutôt la fin de l’exécution.

Figer une version

Les extraits transmettent le version_id de la version publiée la plus récente que l’API peut exécuter. Conservez-le figé : lorsque l’auteur publie à nouveau, une exécution figée continue d’utiliser la version que vous avez testée, tandis que latest bascule vers la nouvelle, qui peut renommer ou ajouter des entrées.

Pour passer à une nouvelle version, ouvrez à nouveau l’onglet API, comparez ses entrées avec celles transmises par votre code et mettez à jour version_id. Pour le vérifier depuis le code, flows.templates.get renvoie les versions publiées du template que l’API peut exécuter, de la plus récente à la plus ancienne, avec leurs entrées et sorties.

Lire les sorties

Le champ outputs de l’exécution terminée contient une entrée par sortie du template, identifiée par l’id de la sortie. Chaque sortie possède son propre status, de sorte qu’une sortie peut échouer alors que les autres aboutissent. Une sortie ayant échoué contient failure_reason et error_message. Une sortie média terminée contient content_url et content_mime_type, tandis qu’une sortie string terminée contient content.

run = TemplateRunResponse.model_validate(event["data"])
for output_id, output in run.outputs.items():
    if output.status == "failed":
        print(output_id, "failed:", output.failure_reason, output.error_message)
    elif output.type == "image" or output.type == "video" or output.type == "audio":
        print(output_id, output.content_url, output.content_mime_type)
    elif output.type == "string":
        print(output_id, output.content)

constructEvent dans le SDK TypeScript renvoie le JSON de l’événement tel qu’il a été envoyé, ses champs sont donc en snake_case.

Consultez Comportement de livraison pour en savoir plus sur les nouvelles tentatives et les événements dupliqués.