Esegui il template del tuo team

Questa guida spiega come eseguire un template creato dal tuo team: copiarne il codice, passare ogni tipo di input, scegliere quali webhook ricevono il risultato, fissare una versione e leggere gli output.

Prima di iniziare

• Il template è condiviso con il tuo workspace. Il suo autore lo imposta in Workspace nelle opzioni di condivisione del template; un template condiviso come Solo io può essere eseguito solo dal suo autore.
• Il tuo workspace ha un webhook iscritto alle esecuzioni dei template. Prima di iniziare nella guida ai webhook di Immagini e Video spiega come configurarne uno.
• Il tuo workspace ha un piano Pro o superiore e la tua chiave API dispone dell’autorizzazione Immagini e Video.

Copia il codice del template

Apri il template nell’app ElevenLabs e seleziona la relativa scheda API. In Flows, l’autore del template può aprire lo stesso codice dal pulsante API nella barra laterale del template.

La scheda genera gli snippet dagli input e output pubblicati del template. In Scegli come ricevere il risultato, seleziona Webhook, quindi seleziona Python o TypeScript sopra il codice. La scheda mostra uno snippet Avvia un’esecuzione e uno snippet Gestisci il risultato. Copia Avvia un’esecuzione nel punto in cui l’applicazione avvia le esecuzioni e Gestisci il risultato nel gestore del webhook. Ogni placeholder in Avvia un’esecuzione corrisponde a un input, mentre Gestisci il risultato legge ogni output tramite il suo id.

Passa ogni input

A ogni input della versione che esegui deve essere assegnato un valore, identificato dall’id dell’input. La forma del valore dipende dal tipo di input:

Gli input di tipo object non possono ancora essere passati tramite l’API; la scheda API mostra un avviso a riguardo.

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

Gli id degli input mantengono la grafia assegnata dal template in entrambi gli SDK; in TypeScript sono in camelCase solo i campi di un riferimento, come assetId.

I dati base64 sono limitati a 25 MB dopo la decodifica e non vengono conservati dopo l’esecuzione. Per passare lo stesso file a molte esecuzioni, caricalo una volta e passa il suo ID risorsa, come descritto in Riferimenti e risorse.

Ottieni il risultato

Un webhook riceve l’esecuzione completata come evento flows_template_run. Gli snippet Webhook della scheda API passano {"type": "all"}, che invia l’esecuzione completata a ogni webhook del workspace iscritto alle esecuzioni dei template. Per inviarla a webhook specifici, elencane gli ID:

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

Ogni webhook elencato deve essere iscritto alle esecuzioni dei template. Un’esecuzione che richiede un webhook quando nessuno è iscritto viene rifiutata, quindi un’esecuzione non termina mai senza un luogo a cui consegnare il risultato.

Per uno script una tantum o un batch job, create_and_wait, usato nella guida rapida ai template, attende invece il completamento dell’esecuzione.

Fissa una versione

Gli snippet passano il version_id della versione pubblicata più recente che l’API può eseguire. Mantienilo fisso: quando l’autore pubblica di nuovo, un’esecuzione con versione fissata continua a eseguire la versione che hai testato, mentre latest passa alla nuova, che può rinominare o aggiungere input.

Per passare a una nuova versione, riapri la scheda API, confronta i suoi input con quelli passati dal tuo codice e aggiorna version_id. Per verificarlo dal codice, invece, flows.templates.get restituisce le versioni pubblicate del template che l’API può eseguire, dalla più recente alla meno recente, ciascuna con i propri input e output.

Leggi gli output

Gli outputs dell’esecuzione completata contengono una voce per ogni output del template, identificata dall’id dell’output. Ogni output ha il proprio status, quindi un output può non riuscire mentre gli altri vengono completati. Un output non riuscito contiene failure_reason e error_message. Un output multimediale completato contiene content_url e content_mime_type, mentre un output string completato contiene 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 nell’SDK TypeScript restituisce il JSON dell’evento così come inviato, quindi i suoi campi sono in snake_case.

Consulta Comportamento di consegna per i tentativi e gli eventi duplicati.