> 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/ko/eleven-api/guides/cookbooks/templates)을 완료했다고 가정합니다.

이 가이드에서는 팀에서 만든 템플릿을 실행하는 방법을 다룹니다. 코드 복사, 각 입력 유형 전달, 결과를 수신할 webhook 선택, 버전 고정, 출력 읽기가 포함됩니다.

## 시작하기 전에

* 템플릿이 워크스페이스와 공유되어 있어야 합니다. 작성자는 템플릿 공유 옵션의 **Workspace**에서 이를 설정합니다. **Just me**로 공유된 템플릿은 작성자만 실행할 수 있습니다.
* 워크스페이스에 템플릿 실행을 구독하는 webhook이 있어야 합니다. 이미지 & 비디오 webhook 가이드의 [시작하기 전에](/docs/ko/eleven-api/guides/how-to/image-and-video/webhooks#before-you-begin)에서 설정 방법을 확인하세요.
* 워크스페이스가 프로 플랜 이상이어야 하며, API 키에 **이미지 & 비디오** 권한이 있어야 합니다.

## 템플릿 코드 복사

ElevenLabs 앱에서 템플릿을 열고 **API** 탭을 선택합니다. Flows에서 템플릿 작성자는 템플릿 사이드바의 **API** 버튼으로 동일한 코드를 열 수 있습니다.

이 탭은 템플릿에 게시된 입력과 출력을 기반으로 스니펫을 생성합니다. **결과 수신 방법 선택**에서 **Webhook**을 선택한 다음, 코드 위에서 **Python** 또는 **TypeScript**를 선택합니다. 탭에는 **실행 시작** 스니펫과 **결과 처리** 스니펫이 표시됩니다. 애플리케이션에서 실행을 시작하는 위치에 **실행 시작**을 복사하고, webhook 핸들러에 **결과 처리**를 복사합니다. **실행 시작**의 각 플레이스홀더는 하나의 입력을 나타내며, **결과 처리**는 각 출력을 ID로 읽습니다.

> **Note**
>
> 템플릿이 API에서 제공하지 않는 모델을 사용하면 탭에 경고가 표시됩니다. 게시된 버전 중 API로
> 실행할 수 있는 버전이 없으면 스니펫이 표시되지 않습니다. 최신 버전만 실행할 수 없는 경우에는
> 실행 가능한 최신 버전으로 스니펫이 실행됩니다. Flows에서 작성자는 경고의 **Show on canvas**를 선택하여
> 해당 노드를 강조 표시하고, 각각을 [사용 가능한 모델](/docs/ko/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" },
});
```

입력 ID는 두 SDK 모두에서 템플릿에 지정된 표기를 유지합니다. `assetId`와 같은 참조 필드만 TypeScript에서 camelCase로 표기됩니다.

base64 데이터는 디코딩 후 25MB로 제한되며 실행 후 저장되지 않습니다. 동일한 파일을 여러 실행에 전달하려면 한 번 업로드한 후 [참조 및 에셋](/docs/ko/eleven-api/guides/how-to/image-and-video/references)에 설명된 대로 에셋 ID를 전달하세요.

## 결과 받기

[webhook](/docs/ko/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/ko/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/ko/eleven-api/guides/how-to/image-and-video/webhooks#delivery-behavior)을 참조하세요.