팀의 템플릿 실행 | ElevenLabs Documentation

방법 가이드 · 템플릿 빠른 시작을 완료했다고 가정합니다.

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

시작하기 전에

템플릿이 워크스페이스와 공유되어 있어야 합니다. 작성자는 템플릿 공유 옵션의 Workspace에서 이를 설정합니다. Just me로 공유된 템플릿은 작성자만 실행할 수 있습니다.
워크스페이스에 템플릿 실행을 구독하는 webhook이 있어야 합니다. 이미지 & 비디오 webhook 가이드의 시작하기 전에에서 설정 방법을 확인하세요.
워크스페이스가 프로 플랜 이상이어야 하며, API 키에 이미지 & 비디오 권한이 있어야 합니다.

템플릿 코드 복사

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

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

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

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에는 템플릿 출력별로 하나의 항목이 있으며, 출력 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입니다.

재시도 및 중복 이벤트에 대해서는 전달 동작을 참조하세요.