Integrace API

Video Caption API pro automatizaci titulků ve velkém objemu s bezpečným QA

Automatizujte generování captions s explicitními stavy úloh, řízením jazyka a retries bezpečnými pro produkci pro týmy dodávající velké objemy short-form obsahu.

Problém

Ve větším měřítku operace s titulky často selhávají na QA a konzistenci: manuální kontroly časování, jazykové neshody a opakované revize se stávají skrytým produkčním úzkým hrdlem.

Výsledek se Ssemble

Ssemble umožňuje deterministické zpracování captions s jasnými kontrakty status/error, takže inženýrské týmy mohou automatizovat rutinní QA a eskalovat pouze skutečné okrajové případy.

Základy implementace

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

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

1) Ingest

Uložte source URL/file URL plus konfigurační pole captions (language, captionLanguage, templateId, preferredLength).

2) Zpracování

Zavolejte POST /shorts/create s parametry captions a zachovejte requestId + correlation id.

3) Poll / Webhook

Kontrolujte GET /shorts/:id/status (nebo list endpoint) v řízené kadenci až do terminálního stavu.

4) Publikování

Získejte dokončené assety, spusťte automatizované QA kontroly titulků a předejte je do fronty publikování.

Příklady endpointů

POST /shorts/create— Vytvoření short s captions a možnostmi jazyka/šablony
GET /shorts/:id/status— Sledování fáze zpracování a failureReason
GET /shorts— Hromadné sledování úloh bez režie jednoho volání na úlohu

Pokyny k autentizaci

Používejte X-API-Key pouze na straně serveru. Udržujte samostatné klíče pro staging a produkci, abyste snížili riziko rotace a vazbu mezi prostředími.

Rate limity a opakování (retries)

Vyhněte se těsným polling smyčkám. Používejte dávkové status checks, cachujte stabilní výsledky a při 429 se řiďte reset/retryAfter před backoff retries.

Příklad požadavku

POST /shorts/create
{
  "url": "https://www.youtube.com/watch?v=abc123",
  "start": 0,
  "end": 540,
  "language": "en",
  "captionLanguage": "en",
  "templateId": "660b8531aedb346bbe26eb43",
  "preferredLength": "under60sec",
  "layout": "auto"
}

Příklad odpovědi

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

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

400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid captionLanguage code",
    "details": { "captionLanguage": "xx" }
  }
}

Verzování

Připněte verze endpointů a validujte schémata požadavků v CI, abyste zachytili integrační drift před vydáním do produkce.

Podpora

U selhaných úloh uchovávejte request payload hash + requestId + error.details, aby týmy mohly oddělit špatné vstupy od incidentů pipeline.

Rychlý start

Vytvořte SSEMBLE_API_KEY v dashboardu a uložte jej do backend runtime.
Odešlete minimální payload POST /shorts/create se source + timing + jazykem.
Pollujte GET /shorts/:id/status každých 10 sekund až do completed/failed/cancelled.
Získejte výstup z GET /shorts/:id a spusťte QA aserce titulků.
Přidejte omezené retries pro přechodné 429/5xx a směrujte vyčerpané úlohy do DLQ.

Začněte s dokumentací caption endpointu

Zahájit integraci

1) Nastavení autentizace

Bezpečná práce s klíči a chyby autentizace

2) Create endpoint

Pole těla požadavku a validace

3) Chybové kódy

Taxonomie chyb s možností retry a terminálních

4) Příklady

Integrační snippety v cURL/JavaScript/Python

Třífázový pracovní postup

Zachyťte zdrojová média a nastavení captions (jazyk/šablona/preferovaná délka) ve svém modelu fronty.
Odešlete create requesty, sledujte přechody stavů a automaticky směrujte terminální stavy.
Publikujte dokončené výstupy po automatizovaných kontrolách čitelnosti titulků a politiky.

Proč si týmy volí Ssemble

Navrženo pro týmy, kde konzistence titulků ovlivňuje kvalitu značky a udržení diváků.
Podporuje směrování QA řízené stavem místo manuální triáže inboxu.
Škáluje napříč více značkami tím, že vyčleňuje politiku stylu/jazyka do vaší integrační vrstvy.

Další krok

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

Časté dotazy

Co obvykle způsobuje selhání pipeline captions?

Běžné příčiny jsou neplatná okna časování, nedostupné source URLs a neplatné hodnoty jazyka/šablony. Validujte je před zařazením do fronty.

Máme ve velkém měřítku pollovat každou úlohu jednotlivě?

Pouze při nízkém objemu. Při vyšším objemu agregované sledování stavů snižuje zátěž API a zvyšuje spolehlivost.

Jak zajistíme bezpečnost retries?

Opakujte pouze přechodné stavy (429/5xx/timeouty) a používejte request fingerprints k zamezení duplicitního zpracování.

Jsou doby dokončení pevné?

Ne. Dokončení se může lišit podle délky zdroje, stavu fronty a možností. Zacházejte s ETA jako s orientačním.

Můžeme vynutit styly titulků pro jednotlivé klienty?

Ano. Uchovávejte mapování stylů/šablon ve své konfigurační vrstvě a vkládejte je pro každého tenanta při vytváření požadavku.

Které produkční výstrahy jsou nejdůležitější?

Sledujte míru selhání podle error code, stáří fronty a počty stuck-processing pro včasnou detekci incidentů.