Integracja API

API do tłumaczenia wideo dla operacji wydawniczych w wielu regionach

Lokalizuj jedno wideo źródłowe na wiele gotowych na rynek wyników z automatyzacją opartą na statusach, izolacją awarii na poziomie lokalizacji i kontrolowanymi procesami wdrożenia.

Problem

Globalne premiery często zawodzą na synchronizacji, a nie na jakości tłumaczenia: język główny publikuje się pierwszy, podczas gdy warianty regionalne opóźniają się i harmonogram kampanii się rozjeżdża.

Rezultat z Ssemble

Ssemble umożliwia operacje typu source-once, localize-many z śledzeniem stanu specyficznym dla lokalizacji, dzięki czemu zespoły mogą wydawać w kontrolowanych falach i szybko odzyskiwać po częściowych awariach.

Podstawy wdrożenia

Base URL: https://aiclipping.ssemble.com/api/v1

Architektura integracji (przyjęcie → przetwarzanie → poll/webhook → publikacja)

1) Przyjęcie

Utwórz manifest tłumaczenia: źródło, lista lokalizacji, polityka wdrożenia i zachowanie awaryjne (fallback).

2) Przetwarzanie

Wysyłaj żądania create specyficzne dla lokalizacji i utrwalaj nadrzędny release id dla śledzenia end-to-end.

3) Poll / Webhook

Śledź stan każdej lokalizacji niezależnie, aby szybko zidentyfikować scenariusze częściowego sukcesu i częściowej awarii.

4) Publikacja

Wydawaj lokalizacje, które przechodzą bramki QA/zgodności, i ponownie kolejkuj nieudane lokalizacje z ograniczoną strategią retry.

Przykłady endpointów

POST /shorts/create— Utwórz zadania przetwarzania specyficzne dla lokalizacji
GET /shorts/:id/status— Śledź stan cyklu życia każdej lokalizacji
GET /shorts/:id— Pobierz ukończony zlokalizowany wynik do wydania

Wskazówki dotyczące uwierzytelniania

Przechowuj klucze API i kontrole wdrożenia wyłącznie w usługach backendowych. Segmentuj klucze per środowisko i ściśle ograniczaj dostęp do wdrożeń produkcyjnych.

Limity zapytań (rate limit) i ponowne próby (retry)

Kolejkuj wysyłanie lokalizacji w kontrolowanych partiach, a nie w pełnych skokach fan-out. Stosuj wykładniczy backoff przy 429/5xx i ograniczaj liczbę retry.

Przykładowe żądanie

POST /shorts/create
{
  "fileUrl": "https://cdn.example.com/master-campaign.mp4",
  "start": 30,
  "end": 420,
  "language": "ko",
  "captionLanguage": "ja",
  "preferredLength": "under60sec",
  "layout": "auto"
}

Przykładowa odpowiedź

200 OK
{
  "data": {
    "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "processing",
    "creditsUsed": 1,
    "estimatedCompletionTime": "2026-03-10T07:00:00.000Z"
  }
}

Przykład scenariusza błędu

500 Internal Server Error
{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred. Please try again.",
    "details": null
  }
}

Wersjonowanie

Rejestruj metadane schematu/wersji dla każdego żądania lokalizacji, aby regresje międzylokalizacyjne były diagnozowalne po zmianach API.

Wsparcie

Utrwalaj nadrzędny release id + lokalizację + requestId przy każdym przejściu statusu dla szybkiego odzyskiwania po incydentach częściowej premiery.

Szybki start

Zdefiniuj macierz lokalizacji i strategię wdrożenia w konfiguracji backendu.
Utwórz jedno żądanie przetwarzania na lokalizację, używając pól language/captionLanguage.
Odpytuj status i aktualizuj tablicę wydań, aż każda lokalizacja osiągnie stan terminalny.
Pobierz ukończone wyniki i uruchom kontrole QA specyficzne dla lokalizacji.
Publikuj lokalizacje, które przeszły kontrole, natychmiast i kieruj nieudane lokalizacje do kolejki z ograniczonymi retry.

Otwórz dokumentację procesu tłumaczenia

Rozpocznij integrację

1) Uwierzytelnianie

Wzorce klucza API wyłącznie po stronie serwera

2) Cykl życia statusu

Model queued/processing/completed/failed

3) Strategia rate limit

Nagłówki, okna resetu i dyscyplina pollingu

4) Taksonomia błędów

Programowa obsługa według error.code

Proces w 3 krokach

Przyjmij jeden materiał źródłowy z macierzą docelowych lokalizacji i polityką wdrożenia.
Przetwarzaj zadania lokalizacji asynchronicznie z niezależnym śledzeniem statusu dla każdej lokalizacji.
Publikuj ukończone lokalizacje przez kolejki regionalne, a nieudane lokalizacje kieruj do kontrolowanych retry.

Dlaczego zespoły wybierają Ssemble

Zaprojektowane dla regionalnych zespołów kanałowych, w których koordynacja wydania jest równie krytyczna jak jakość treści.
Izoluje awarie per lokalizacja, dzięki czemu jeden problem nie blokuje całej premiery kampanii.
Współpracuje z automatyzacją publikacji dla procesów dystrybucji w modelu follow-the-sun.

Następny krok

Otwórz szybki start API tłumaczenia Zobacz cennik Dokumentacja dla programistów

FAQ

Jak zapobiec sytuacji, w której jedna lokalizacja blokuje wszystkie regiony?

Stosuj maszyny stanów per lokalizacja i bramki wydania, aby każda lokalizacja mogła być publikowana niezależnie, chyba że polityka wymaga synchronizacji wszystkich lokalizacji.

Czy powinniśmy wysyłać wszystkie lokalizacje naraz?

Zwykle nie. Kontrolowane partie chronią budżety rate i upraszczają triaż incydentów, gdy ścieżka lokalizacji ulega degradacji.

Jaki jest minimalny payload obserwowalności?

Śledź nadrzędny release id, kod lokalizacji, requestId, przejścia statusów, kod błędu i liczbę retry dla każdego zadania.

Które błędy powinny być ponawiane automatycznie?

Ponawiaj przejściowe błędy transportu, 429 i 5xx z backoffem. Kończ szybko przy błędach walidacji i kieruj je do korekty konfiguracji/danych.

Czy tłumaczenie i publikację można rozdzielić?

Tak. Wiele zespołów trzyma zakończenie tłumaczenia i publikację na kanałach w oddzielnych kolejkach dla lepszej kontroli i bezpieczeństwa rollbacku.

Czy to gwarantuje jednakowe wyniki we wszystkich lokalizacjach?

Nie należy zakładać żadnej gwarancji. Mierz czas zakończenia, wskaźnik awaryjności i wskaźnik zdawalności QA per lokalizacja i odpowiednio dostosowuj politykę wdrożenia.