Uruchom szablon swojego zespołu

Ten poradnik opisuje uruchamianie szablonu stworzonego przez twój zespół: kopiowanie jego kodu, przekazywanie każdego rodzaju danych wejściowych, wybór webhooków odbierających wynik, przypinanie wersji i odczytywanie danych wyjściowych.

Zanim zaczniesz

• Szablon jest udostępniony twojemu obszarowi roboczemu. Jego autor ustawia to w sekcji Workspace w opcjach udostępniania szablonu; szablon udostępniony jako Just me może uruchomić tylko jego autor.
• Twój obszar roboczy ma webhook subskrybujący uruchomienia szablonów. W sekcji Zanim zaczniesz poradnika o webhookach Image & Video dowiesz się, jak go skonfigurować.
• Twój obszar roboczy korzysta z planu Pro lub wyższego, a klucz API ma uprawnienie Image & Video.

Skopiuj kod szablonu

Otwórz szablon w aplikacji ElevenLabs i wybierz kartę API. W Flows autor szablonu może otworzyć ten sam kod przyciskiem API na pasku bocznym szablonu.

Karta tworzy fragmenty kodu na podstawie opublikowanych danych wejściowych i wyjściowych szablonu. W sekcji Choose how to get the result wybierz Webhook, a następnie nad kodem wybierz Python lub TypeScript. Karta pokaże fragment Start a run i fragment Handle the result. Skopiuj Start a run tam, gdzie aplikacja rozpoczyna procesy, a Handle the result do obsługi webhooka. Każdy placeholder w Start a run odpowiada jednemu wejściu, a Handle the result odczytuje każde wyjście według jego identyfikatora.

Przekaż każde wejście

Każde wejście uruchamianej wersji musi otrzymać wartość oznaczoną identyfikatorem wejścia. Format wartości zależy od typu wejścia:

Wejść typu object nie można jeszcze przekazywać przez API — karta API o tym ostrzega.

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

Identyfikatory wejść zachowują pisownię nadaną im przez szablon w obu SDK; tylko pola odwołania, takie jak assetId, są w TypeScripcie w camelCase.

Dane base64 są ograniczone do 25 MB po zdekodowaniu i nie są zachowywane po zakończeniu procesu. Aby przekazywać ten sam plik do wielu procesów, prześlij go raz i przekazuj jego identyfikator zasobu zgodnie z opisem w Odwołaniach i zasobach.

Odbierz wynik

Webhook odbiera zakończony proces jako zdarzenie flows_template_run. Fragmenty Webhook na karcie API przekazują {"type": "all"}, co wysyła zakończony proces do każdego webhooka w obszarze roboczym subskrybującego uruchomienia szablonów. Aby wysłać go do konkretnych webhooków, podaj ich identyfikatory:

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

Każdy wymieniony webhook musi subskrybować uruchomienia szablonów. Proces żądający webhooka, gdy żaden go nie subskrybuje, zostanie odrzucony — wynik procesu nigdy nie zostanie więc bez miejsca dostarczenia.

W przypadku jednorazowego skryptu lub zadania wsadowego create_and_wait, używany w szybkim starcie z szablonami, czeka na zakończenie procesu.

Przypnij wersję

Fragmenty przekazują version_id najnowszej opublikowanej wersji, którą może uruchomić API. Zachowaj jej przypięcie: gdy autor opublikuje ponownie, przypięty proces nadal uruchamia testowaną wersję, podczas gdy latest przełącza się na nową, która może zmienić nazwę wejść lub dodać nowe.

Aby przejść na nową wersję, otwórz ponownie kartę API, porównaj jej wejścia z tymi przekazywanymi przez kod i zaktualizuj version_id. Aby sprawdzić to w kodzie, flows.templates.get zwraca opublikowane wersje szablonu, które może uruchomić API — od najnowszej — wraz z ich wejściami i wyjściami.

Odczytaj dane wyjściowe

outputs zakończonego procesu zawiera po jednym wpisie dla każdego wyjścia szablonu, oznaczonym identyfikatorem wyjścia. Każde wyjście ma własny status, więc jedno może zakończyć się błędem, gdy pozostałe się powiodą. Wyjście z błędem zawiera failure_reason i error_message. Ukończone wyjście multimedialne zawiera content_url i content_mime_type, a ukończone wyjście string zawiera 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)

constructEvent w SDK TypeScript zwraca JSON zdarzenia w przesłanej postaci, więc jego pola są w snake_case.

Informacje o ponownych próbach i zduplikowanych zdarzeniach znajdziesz w sekcji Zachowanie dostarczania.