チームのテンプレートを実行 | ElevenLabs Documentation

ハウツーガイド · テンプレートクイックスタートを完了していることを前提としています。

このガイドでは、チームで作成したテンプレートを実行する方法を説明します。コードのコピー、各入力タイプの指定、結果を受け取るwebhookの選択、バージョンの固定、出力の読み取りを扱います。

始める前に

テンプレートがワークスペースと共有されています。作成者はテンプレートの共有オプションでワークスペースを選択して設定します。自分のみとして共有されたテンプレートを実行できるのは作成者だけです。
ワークスペースには、テンプレート実行を購読するwebhookがあります。画像＆ビデオwebhookガイドの始める前にで設定できます。
ワークスペースがプロ以上のプランであり、APIキーに画像＆ビデオ権限があります。

テンプレートのコードをコピー

ElevenLabsアプリでテンプレートを開き、APIタブを選択します。Flowsでは、テンプレートの作成者がテンプレートのサイドバーにあるAPIボタンから同じコードを開けます。

このタブは、テンプレートで公開された入力と出力からスニペットを生成します。結果の取得方法を選択でWebhookを選択し、コードの上にあるPythonまたはTypeScriptを選択します。タブには実行を開始スニペットと結果を処理スニペットが表示されます。アプリケーションが実行を開始する場所に実行を開始をコピーし、webhookハンドラーに結果を処理をコピーします。実行を開始の各プレースホルダーは1つの入力を表し、結果を処理では各出力をIDで読み取ります。

テンプレートでAPIが提供していないモデルを使用している場合、タブに警告が表示されます。APIで実行できる公開バージョンがない場合はスニペットが表示されません。最新バージョンだけが実行できない場合、スニペットは実行可能な最新バージョンを実行します。Flowsでは、作成者が警告内のキャンバスに表示を選択して該当ノードをハイライトし、各ノードを利用可能なモデルに切り替え、再度公開します。

各入力を渡す

実行するバージョンのすべての入力には、入力IDをキーとして値を指定する必要があります。値の形式は入力タイプによって異なります。

入力タイプ	値
`string`	テキスト自体。
`number`、`integer`、`boolean`	そのタイプのJSON値。
`image`、`video`、`audio`	アップロード済みアセット、以前の生成結果、またはbase64データへの参照。
`voice`	ワークスペース内の音声への参照。
`array`	要素ごとに1つの値を持つリスト。各値はその要素タイプに対応した形式です。

objectタイプの入力は、まだAPI経由で渡せません。APIタブに警告が表示されます。

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

入力IDはどちらのSDKでもテンプレートで指定されたスペルのままです。assetIdなどの参照フィールドだけは、TypeScriptではキャメルケースになります。

base64データはデコード後25MBまでに制限され、実行後は保持されません。同じファイルを複数の実行に渡すには、一度アップロードしてアセットIDを渡します。詳しくは参照とアセットを参照してください。

結果を取得

webhookは、完了した実行をflows_template_runイベントとして受け取ります。APIタブのWebhookスニペットでは{"type": "all"}を渡します。これにより、テンプレート実行を購読しているワークスペース内のすべてのwebhookに完了した実行が送信されます。特定のwebhookに送信するには、そのIDをリストします。

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

リスト内の各webhookは、テンプレート実行を購読している必要があります。購読しているwebhookがないのにwebhookを要求する実行は拒否されるため、結果を配信する先がない状態で実行が完了することはありません。

単発スクリプトやバッチジョブには、テンプレートクイックスタートで使用したcreate_and_waitを使うと、代わりに実行の完了を待機できます。

バージョンを固定

スニペットは、APIで実行できる最新の公開バージョンのversion_idを渡します。固定したままにしてください。作成者が再度公開した場合、固定された実行ではテスト済みのバージョンが引き続き実行されます。一方、latestは新しいバージョンに切り替わるため、入力の名前変更や追加が行われる可能性があります。

新しいバージョンに移行するには、もう一度APIタブを開き、コードで渡している入力と比較して、version_idを更新します。コードから確認する場合は、flows.templates.getがAPIで実行できるテンプレートの公開バージョンを新しい順に返し、それぞれの入力と出力も含まれます。

出力を読み取る

完了した実行のoutputsには、テンプレートの出力ごとに1つのエントリがあり、出力IDをキーとしています。各出力にはそれぞれstatusがあるため、他の出力が完了していても1つの出力だけ失敗することがあります。失敗した出力にはfailure_reasonとerror_messageが含まれます。完了したメディア出力にはcontent_urlとcontent_mime_typeが含まれ、完了したstring出力には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)

TypeScript SDKのconstructEventは、送信されたイベントのJSONをそのまま返すため、フィールドはsnake_caseです。

再試行と重複イベントについては、配信の動作を参照してください。