> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 运行团队的模板

> **Note**
>
> **操作指南** · 假设你已完成[模板 快速入门](/docs/zh/eleven-api/guides/cookbooks/templates)。

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

## 开始前

* 模板已共享到工作区。作者可在模板共享选项的 **Workspace** 下设置；共享为 **Just me** 的模板仅作者可以运行。
* 工作区有一个已订阅模板运行事件的 webhook。[Image & Video webhook 指南中的开始前准备](/docs/zh/eleven-api/guides/how-to/image-and-video/webhooks#before-you-begin)介绍了如何设置。
* 工作区使用 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 读取每项输出。

> **Note**
>
> 当模板使用 API 未提供的模型时，该标签会发出警告。如果没有任何已发布版本能通过 API 运行，则不会显示代码片段；如果只有最新版本无法运行，代码片段将运行最新的可用版本。在 Flows 中，作者可在警告中选择 **Show on canvas** 以高亮这些节点，将每个节点切换为[可用 模型](/docs/zh/eleven-api/guides/cookbooks/image-and-video#available-models)，然后再次发布。

## 传入每项输入

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

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

`object` 类型的输入暂时无法通过 API 传入，API 标签会对此发出警告。

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

```typescript
const run = await client.flows.templates.runs.create("Yz4DETxRv4uXyIo5PnEy", {
  versionId: "Kqs4nRrpndEjQ54BhbwE",
  inputs: {
    headline: "Autumn collection, 20% off",
    duration_secs: 8,
    product_photo: { type: "asset", assetId: "Rk3pQm8vTzL1yWcN0bJd" },
    previous_shot: { type: "generation", generationId: "JWr5N6X9ZTqf8jD2LmQb" },
    phone_photo: {
      type: "inline_base64",
      contentBase64: photo.toString("base64"),
      mimeType: "image/jpeg",
    },
    narrator: { type: "voice", voiceId: "JBFqnCBsd6RMkjVDRZzb" },
  },
  webhook: { type: "all" },
});
```

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

解码后的 base64 数据上限为 25 MB，且不会在运行后保留。如需将同一文件传给多次运行，请先上传一次并传入其资源 ID，详见[引用和资源](/docs/zh/eleven-api/guides/how-to/image-and-video/references)。

## 获取结果

[webhook](/docs/zh/eleven-api/resources/webhooks) 会以 `flows_template_run` 事件接收已完成的运行。API 标签的 **Webhook** 代码片段会传入 `{"type": "all"}`，将完成的运行发送到工作区中所有已订阅模板运行事件的 webhook。若要发送至指定 webhook，请列出其 ID：

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

```typescript
webhook: { type: "ids", ids: ["Q8mVr2LpXcT4nB6yJdKw"] }
```

列出的每个 webhook 都必须订阅模板运行事件。如果运行请求 webhook 但没有任何 webhook 订阅，运行会被拒绝，因此不会出现完成后无处交付结果的情况。

对于一次性脚本或批处理任务，可改用[模板快速入门](/docs/zh/eleven-api/guides/cookbooks/templates)中的 `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`。

```python
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
const run = event.data;

for (const [outputId, output] of Object.entries(run.outputs)) {
  if (output.status === "failed") {
    console.error(outputId, "failed:", output.failure_reason, output.error_message);
  } else if (output.type === "image" || output.type === "video" || output.type === "audio") {
    console.log(outputId, output.content_url, output.content_mime_type);
  } else if (output.type === "string") {
    console.log(outputId, output.content);
  }
}
```

TypeScript SDK 中的 `constructEvent` 会返回收到的原始事件 JSON，因此其字段使用 snake_case。

有关重试和重复事件，请参阅[交付行为](/docs/zh/eleven-api/guides/how-to/image-and-video/webhooks#delivery-behavior)。