Template Ihres Teams ausführen

Dieser Leitfaden behandelt das Ausführen eines von Ihrem Team erstellten Templates: Code kopieren, jede Art von Eingabe übergeben, Webhooks für den Ergebnisempfang auswählen, eine Version fixieren und Ausgaben lesen.

Bevor Sie beginnen

• Das Template ist für Ihren Workspace freigegeben. Der Autor legt dies unter Workspace in den Freigabeoptionen des Templates fest. Ein als Just me freigegebenes Template kann nur von seinem Autor ausgeführt werden.
• Ihr Workspace hat einen Webhook, der Template-Läufe abonniert hat. Bevor Sie beginnen im Leitfaden zu Image-&-Video-Webhooks erklärt die Einrichtung.
• Ihr Workspace hat einen Pro-Tarif oder höher und Ihr API-Schlüssel besitzt die Berechtigung Image & Video.

Code des Templates kopieren

Öffnen Sie das Template in der ElevenLabs-App und wählen Sie seinen Tab API. In Flows kann der Autor des Templates denselben Code über die Schaltfläche API in der Seitenleiste des Templates öffnen.

Der Tab erstellt seine Snippets aus den veröffentlichten Eingaben und Ausgaben des Templates. Wählen Sie unter Choose how to get the result die Option Webhook und dann über dem Code Python oder TypeScript. Der Tab zeigt ein Snippet Start a run und ein Snippet Handle the result. Kopieren Sie Start a run an die Stelle, an der Ihre Anwendung Läufe startet, und Handle the result in Ihren Webhook-Handler. Jeder Platzhalter in Start a run steht für eine Eingabe, und Handle the result liest jede Ausgabe anhand ihrer ID.

Jede Eingabe übergeben

Jede Eingabe der von Ihnen ausgeführten Version muss einen Wert erhalten, wobei der Schlüssel die ID der Eingabe ist. Wie der Wert aussieht, hängt vom Typ der Eingabe ab:

Eingaben des Typs object können noch nicht über die API übergeben werden. Der API-Tab warnt davor.

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

Eingabe-IDs behalten in beiden SDKs die Schreibweise des Templates. Nur die Felder einer Referenz, etwa assetId, sind in TypeScript in CamelCase geschrieben.

Base64-Daten sind nach dem Dekodieren auf 25 MB begrenzt und werden nach dem Lauf nicht gespeichert. Um dieselbe Datei an viele Läufe zu übergeben, laden Sie sie einmal hoch und übergeben ihre Asset-ID, wie unter Referenzen und Assets beschrieben.

Ergebnis abrufen

Ein Webhook empfängt den abgeschlossenen Lauf als Ereignis flows_template_run. Die Webhook-Snippets des API-Tabs übergeben {"type": "all"}, wodurch der abgeschlossene Lauf an jeden Webhook im Workspace gesendet wird, der Template-Läufe abonniert hat. Um ihn an bestimmte Webhooks zu senden, listen Sie deren IDs auf:

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

Jeder aufgeführte Webhook muss Template-Läufe abonniert haben. Ein Lauf, der einen Webhook anfordert, obwohl keiner abonniert ist, wird abgelehnt. So endet ein Lauf nie ohne Ziel für sein Ergebnis.

Für ein einmaliges Skript oder einen Batch-Job wartet create_and_wait, das im Schnellstart für Templates verwendet wird, stattdessen auf den Abschluss des Laufs.

Version fixieren

Die Snippets übergeben die version_id der neuesten veröffentlichten Version, die über die API ausgeführt werden kann. Lassen Sie sie fixiert: Wenn der Autor erneut veröffentlicht, führt ein fixierter Lauf weiterhin die von Ihnen getestete Version aus, während latest auf die neue Version wechselt, die Eingaben umbenennen oder hinzufügen kann.

Um zu einer neuen Version zu wechseln, öffnen Sie den API-Tab erneut, vergleichen Sie dessen Eingaben mit den Werten, die Ihr Code übergibt, und aktualisieren Sie version_id. Um dies stattdessen per Code zu prüfen, gibt flows.templates.get die veröffentlichten Versionen des Templates zurück, die über die API ausgeführt werden können: die neueste zuerst, jeweils mit Eingaben und Ausgaben.

Ausgaben lesen

outputs des abgeschlossenen Laufs enthält einen Eintrag pro Ausgabe des Templates, wobei der Schlüssel die ID der Ausgabe ist. Jede Ausgabe hat ihren eigenen status, sodass eine Ausgabe fehlschlagen kann, während die anderen abgeschlossen werden. Eine fehlgeschlagene Ausgabe enthält failure_reason und error_message. Eine abgeschlossene Medienausgabe enthält content_url und content_mime_type, und eine abgeschlossene string-Ausgabe enthält 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 im TypeScript-SDK gibt das JSON des Ereignisses wie gesendet zurück. Seine Felder sind daher in snake_case.

Informationen zu Wiederholungen und doppelten Ereignissen finden Sie unter Zustellverhalten.