Integrace API

Video Translation API pro operace vydávání ve více regionech

Lokalizujte jedno source video do více výstupů připravených pro trh s automatizací řízenou stavy, izolací selhání na úrovni locale a řízenými rollout pracovními postupy.

Problém

Globální spuštění často selhávají na synchronizaci, nikoli na kvalitě překladu: hlavní jazyk se publikuje jako první, zatímco regionální varianty zaostávají a časování kampaně se rozpadá.

Výsledek se Ssemble

Ssemble umožňuje operace source-once, localize-many se sledováním stavu specifickým pro locale, takže týmy mohou vydávat v řízených vlnách a rychle obnovit částečná selhání.

Základy implementace

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

Architektura integrace (ingest → zpracování → poll/webhook → publikování)

1) Ingest

Vytvořte překladový manifest: source, seznam locale, rollout politiku a chování fallbacku.

2) Zpracování

Odešlete create requesty specifické pro locale a zachovejte parent release id pro dohledatelnost od začátku do konce.

3) Poll / Webhook

Sledujte stav každé locale nezávisle, abyste rychle identifikovali scénáře částečného úspěchu a částečného selhání.

4) Publikování

Vydejte locales, které projdou QA/politickými branami, a znovu zařaďte selhané locales s omezenou retry strategií.

Příklady endpointů

POST /shorts/create— Vytvoření úloh zpracování specifických pro locale
GET /shorts/:id/status— Sledování stavu životního cyklu každé locale
GET /shorts/:id— Získání dokončeného lokalizovaného výstupu pro vydání

Pokyny k autentizaci

Udržujte API keys a rollout controls pouze v backend službách. Segmentujte klíče podle prostředí a přísně omezte přístup k produkčnímu rolloutu.

Rate limity a opakování (retries)

Zařazujte odesílání locale v řízených dávkách, nikoli jako plné fan-out nárazy. Používejte exponenciální backoff při 429/5xx a omezte retries.

Příklad požadavku

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

Příklad odpovědi

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

Příklad chybového scénáře

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

Verzování

Zaznamenávejte metadata schema/version pro každý požadavek locale, aby byly regrese napříč locales diagnostikovatelné po změnách API.

Podpora

Zachovejte parent release id + locale + requestId u každého přechodu stavu pro rychlou obnovu po incidentech částečného spuštění.

Rychlý start

Definujte matici locale a rollout strategii v backend konfiguraci.
Vytvořte jeden požadavek zpracování na locale pomocí polí language/captionLanguage.
Pollujte stav a aktualizujte release board, dokud každá locale nedosáhne terminálního stavu.
Získejte dokončené výstupy a spusťte QA kontroly specifické pro locale.
Okamžitě publikujte vyhovující locales a směrujte selhané locales do omezené retry fronty.

Otevřít dokumentaci pracovního postupu překladu

Zahájit integraci

1) Autentizace

Vzory API key pouze pro server

2) Životní cyklus stavů

Model queued/processing/completed/failed

3) Strategie rate-limitu

Headers, reset okna a disciplína pollingu

4) Taxonomie chyb

Programové zpracování podle error.code

Třífázový pracovní postup

Proveďte ingest jednoho source assetu s maticí cílových locale a rollout politikou.
Zpracovávejte úlohy locale asynchronně s nezávislým sledováním stavu pro každou locale.
Publikujte dokončené locales přes regionální fronty, zatímco selhané locales se směrují do řízených retries.

Proč si týmy volí Ssemble

Navrženo pro týmy regionálních kanálů, kde je koordinace vydání stejně kritická jako kvalita obsahu.
Izoluje selhání na úrovni locale, takže jeden problém neblokuje spuštění celých kampaní.
Funguje s automatizací publikování pro pracovní postupy distribuce follow-the-sun.

Další krok

Otevřít rychlý start translation API Zobrazit ceny Dokumentace pro vývojáře

Časté dotazy

Jak zabráníme tomu, aby jedna locale blokovala všechny regiony?

Používejte stavové automaty na úrovni locale a release brány, aby každou locale bylo možné publikovat nezávisle, pokud politika nevyžaduje synchronizaci všech locales.

Máme odeslat všechny locales najednou?

Obvykle ne. Řízené dávkování chrání rate rozpočty a zjednodušuje triáž incidentů, když se cesta jedné locale zhorší.

Jaký je minimální observability payload?

Sledujte parent release id, kód locale, requestId, přechody stavů, error code a retry count pro každou úlohu.

Které chyby by se měly opakovat automaticky?

Opakujte přechodné transportní chyby, 429 a 5xx s backoffem. Selhávejte rychle při validačních chybách a směrujte je k opravě config/dat.

Lze překlad a publikování oddělit?

Ano. Mnoho týmů udržuje dokončení překladu a publikování na kanály v oddělených frontách pro lepší kontrolu a bezpečnost rollbacku.

Zaručuje to stejné výsledky napříč všemi locales?

Neměla by se předpokládat žádná záruka. Měřte dobu dokončení, míru selhání a míru úspěšnosti QA podle locale a podle toho upravujte rollout politiku.