运行团队的模板 | ElevenLabs Documentation

操作指南 · 假设你已完成模板快速入门。

本指南介绍如何运行团队构建的模板：复制其代码、传入各类输入、选择接收结果的 webhook、固定版本以及读取输出。

开始前

模板已共享到工作区。作者可在模板共享选项的 Workspace 下设置；共享为 Just me 的模板仅作者可以运行。
工作区有一个已订阅模板运行事件的 webhook。Image & Video webhook 指南中的开始前准备介绍了如何设置。
工作区使用 Pro 或更高套餐，且 API 密钥拥有 Image & Video 权限。

复制模板代码

在 ElevenLabs 应用中打开模板并选择其 API 标签。在 Flows 中，模板作者也可以通过模板侧边栏的 API 按钮打开相同的代码。

该标签会根据模板已发布的输入和输出生成代码片段。在 Choose how to get the result 下选择 Webhook，然后在代码上方选择 Python 或 TypeScript。该标签会显示 Start a run 和 Handle the result 两个代码片段。将 Start a run 复制到应用启动运行的位置，将 Handle the result 复制到 webhook 处理程序中。Start a run 中的每个占位符都对应一个输入，Handle the result 则通过 id 读取每项输出。

当模板使用 API 未提供的模型时，该标签会发出警告。如果没有任何已发布版本能通过 API 运行，则不会显示代码片段；如果只有最新版本无法运行，代码片段将运行最新的可用版本。在 Flows 中，作者可在警告中选择 Show on canvas 以高亮这些节点，将每个节点切换为可用模型，然后再次发布。

传入每项输入

必须为所运行版本的每项输入提供一个值，并以输入的 id 为键。值的格式取决于输入类型：

输入类型	值
`string`	文本本身。
`number`、`integer`、`boolean`	该类型的 JSON 值。
`image`、`video`、`audio`	对已上传资源、之前生成结果或 base64 数据的引用。
`voice`	对工作区中音色的引用。
`array`	列表，每个元素一个值，格式与其元素类型要求一致。

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

两种 SDK 中，输入 id 均保持模板中的拼写；仅引用中的字段（如 assetId）在 TypeScript 中使用驼峰命名。

解码后的 base64 数据上限为 25 MB，且不会在运行后保留。如需将同一文件传给多次运行，请先上传一次并传入其资源 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 中，每个模板输出都有一个条目，并以输出的 id 为键。每项输出都有自己的 status，因此某项输出可能失败，而其他输出成功完成。失败的输出会包含 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。

有关重试和重复事件，请参阅交付行为。