Execute o template da sua equipe

Este guia aborda como executar um template criado pela sua equipe: copiar seu código, passar cada tipo de entrada, escolher quais webhooks recebem o resultado, fixar uma versão e ler as saídas.

Antes de começar

• O template é compartilhado com seu espaço de trabalho. O autor configura isso em Workspace nas opções de compartilhamento do template; um template compartilhado como Just me só é executado pelo autor.
• Seu espaço de trabalho tem um webhook inscrito em execuções de template. A seção Antes de começar do guia de webhooks de Image & Video mostra como configurar um.
• Seu espaço de trabalho está em um plano Pro ou superior, e sua chave de API tem a permissão Image & Video.

Copie o código do template

Abra o template no app da ElevenLabs e selecione sua aba API. No Flows, o autor do template pode abrir o mesmo código pelo botão API na barra lateral do template.

A aba cria seus trechos com base nas entradas e saídas publicadas do template. Em Escolha como receber o resultado, selecione Webhook e depois selecione Python ou TypeScript acima do código. A aba mostra um trecho Inicie uma execução e um trecho Processe o resultado. Copie Inicie uma execução para onde seu aplicativo inicia execuções e Processe o resultado para o manipulador de webhook. Cada placeholder em Inicie uma execução representa uma entrada, e Processe o resultado lê cada saída pelo id.

Passe cada entrada

Todas as entradas da versão que você executar devem receber um valor, usando o id da entrada como chave. A forma do valor depende do tipo de entrada:

Entradas do tipo object ainda não podem ser passadas pela API; a aba API avisa sobre elas.

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

Os ids das entradas mantêm a grafia dada pelo template nos dois SDKs; apenas os campos de uma referência, como assetId, usam camelCase em TypeScript.

Dados base64 são limitados a 25 MB após a decodificação e não são mantidos depois da execução. Para passar o mesmo arquivo a várias execuções, envie-o uma vez e passe seu ID de recurso, conforme descrito em Referências e recursos.

Obtenha o resultado

Um webhook recebe a execução concluída como um evento flows_template_run. Os trechos Webhook da aba API passam {"type": "all"}, que envia a execução concluída a todos os webhooks do espaço de trabalho inscritos em execuções de template. Para enviá-la a webhooks específicos, liste seus IDs:

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

Cada webhook listado deve estar inscrito em execuções de template. Uma execução que solicita um webhook quando nenhum está inscrito é rejeitada, então uma execução nunca termina sem ter para onde entregar seu resultado.

Para um script pontual ou trabalho em lote, create_and_wait, usado no início rápido de templates, espera a execução terminar.

Fixe uma versão

Os trechos passam o version_id da versão publicada mais recente que a API pode executar. Mantenha-o fixado: quando o autor publicar novamente, uma execução fixada continuará executando a versão que você testou, enquanto latest mudará para a nova, que pode renomear ou adicionar entradas.

Para migrar para uma nova versão, abra a aba API novamente, compare suas entradas com as que seu código passa e atualize version_id. Para verificar pelo código, flows.templates.get retorna as versões publicadas do template que a API pode executar, da mais recente à mais antiga, cada uma com suas entradas e saídas.

Leia as saídas

As outputs da execução concluída têm uma entrada por saída do template, usando o id da saída como chave. Cada saída tem seu próprio status, então uma saída pode falhar enquanto as demais são concluídas. Uma saída com falha contém failure_reason e error_message. Uma saída de mídia concluída contém content_url e content_mime_type, e uma saída string concluída contém 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 no SDK TypeScript retorna o JSON do evento como enviado, portanto seus campos usam snake_case.

Consulte Comportamento de entrega para saber sobre novas tentativas e eventos duplicados.