Ejecuta la plantilla de tu equipo

Esta guía explica cómo ejecutar una plantilla creada por tu equipo: copiar su código, pasar cada tipo de entrada, elegir qué webhooks reciben el resultado, fijar una versión y leer las salidas.

Antes de empezar

• La plantilla está compartida con tu espacio de trabajo. Su autor lo configura en Espacio de trabajo dentro de las opciones de uso compartido de la plantilla; una plantilla compartida como Solo yo solo la puede ejecutar su autor.
• Tu espacio de trabajo tiene un webhook suscrito a las ejecuciones de plantillas. Antes de empezar en la guía de webhooks de Imagen y vídeo explica cómo configurar uno.
• Tu espacio de trabajo tiene un plan Pro o superior, y tu clave de API dispone del permiso Imagen y vídeo.

Copia el código de la plantilla

Abre la plantilla en la app de ElevenLabs y selecciona su pestaña API. En Flows, el autor de la plantilla puede abrir el mismo código desde el botón API de la barra lateral de la plantilla.

La pestaña genera sus fragmentos a partir de las entradas y salidas publicadas de la plantilla. En Elige cómo obtener el resultado, selecciona Webhook y, después, Python o TypeScript encima del código. La pestaña muestra un fragmento de Iniciar una ejecución y otro de Gestionar el resultado. Copia Iniciar una ejecución donde tu aplicación inicia ejecuciones, y Gestionar el resultado en tu controlador de webhook. Cada marcador de posición de Iniciar una ejecución representa una entrada, y Gestionar el resultado lee cada salida por su id.

Pasa cada entrada

Todas las entradas de la versión que ejecutes deben recibir un valor, usando como clave el id de la entrada. La forma del valor depende del tipo de entrada:

Las entradas de tipo object todavía no se pueden pasar mediante la API; la pestaña API avisa sobre ellas.

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(),
)

Los id de entrada mantienen la misma grafía que les da la plantilla en ambos SDK; solo los campos de una referencia, como assetId, usan camelCase en TypeScript.

Los datos base64 están limitados a 25 MB una vez decodificados y no se conservan después de la ejecución. Para pasar el mismo archivo a muchas ejecuciones, súbelo una vez y pasa su ID de recurso, como se describe en Referencias y recursos.

Obtén el resultado

Un webhook recibe la ejecución terminada como un evento flows_template_run. Los fragmentos de Webhook de la pestaña API pasan {"type": "all"}, que envía la ejecución terminada a todos los webhooks del espacio de trabajo suscritos a ejecuciones de plantillas. Para enviarla a webhooks específicos, indica sus ID:

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

Cada webhook indicado debe estar suscrito a ejecuciones de plantillas. Se rechaza una ejecución que solicita un webhook cuando no hay ninguno suscrito, por lo que una ejecución nunca termina sin un destino al que entregar su resultado.

Para un script puntual o un trabajo por lotes, create_and_wait, usado en el inicio rápido de plantillas, espera a que termine la ejecución en su lugar.

Fija una versión

Los fragmentos pasan el version_id de la versión publicada más reciente que puede ejecutar la API. Mantenlo fijado: cuando el autor vuelva a publicar, una ejecución fijada seguirá ejecutando la versión que probaste, mientras que latest cambia a la nueva, que puede cambiar el nombre de las entradas o añadir otras.

Para pasar a una versión nueva, abre otra vez la pestaña API, compara sus entradas con las que pasa tu código y actualiza version_id. Para comprobarlo desde código, flows.templates.get devuelve las versiones publicadas de la plantilla que puede ejecutar la API, de más reciente a más antigua, cada una con sus entradas y salidas.

Lee las salidas

Las outputs de la ejecución terminada tienen una entrada por cada salida de la plantilla, usando como clave el id de la salida. Cada salida tiene su propio status, por lo que una salida puede fallar mientras las demás se completan. Una salida fallida incluye failure_reason y error_message. Una salida multimedia completada incluye content_url y content_mime_type, y una salida string completada incluye 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 en el SDK de TypeScript devuelve el JSON del evento tal como se envió, por lo que sus campos están en snake_case.

Consulta Comportamiento de entrega para obtener información sobre reintentos y eventos duplicados.