API-integráció

Video Caption API a nagy volumenű, QA-biztos feliratozás automatizálásához

Automatizáld a feliratgenerálást explicit feladatállapotokkal, nyelvi vezérlőkkel és éles környezetben biztonságos újrapróbálkozásokkal, nagy volumenű, rövid formátumú tartalmakat szállító csapatok számára.

Probléma

Nagy léptékben a feliratozási műveletek gyakran a QA-nál és a konzisztenciánál buknak el: a manuális időzítés-ellenőrzés, a nyelvi eltérések és az ismételt átdolgozások rejtett éles szűk keresztmetszetté válnak.

Eredmény a Ssemble segítségével

A Ssemble determinisztikus feliratfeldolgozást tesz lehetővé egyértelmű status/error szerződésekkel, így a mérnökcsapatok automatizálhatják a rutin QA-t, és csak a valódi peremeseteket eszkalálják.

Megvalósítási alapok

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

Integrációs architektúra (betöltés → feldolgozás → poll/webhook → publikálás)

1) Betöltés

Tárold a forrás URL-t/fájl URL-t, valamint a feliratkonfigurációs mezőket (language, captionLanguage, templateId, preferredLength).

2) Feldolgozás

Hívd meg a POST /shorts/create-et feliratparaméterekkel, és tárold a requestId + correlation id értékeket.

3) Poll / Webhook

Ellenőrizd a GET /shorts/:id/status-t (vagy a list endpointot) kontrollált ütemben a végállapotig.

4) Publikálás

Kérd le a befejezett tartalmakat, futtass automatizált felirat-QA-ellenőrzéseket, és add át a közzétételi sornak.

Endpoint-példák

POST /shorts/create— Feliratozott short létrehozása nyelvi/sablon opciókkal
GET /shorts/:id/status— A feldolgozási szakasz és a failureReason követése
GET /shorts— Feladatok kötegelt figyelése feladatonkénti egyhívásos többletterhelés nélkül

Hitelesítési útmutató

Kizárólag szerveroldali X-API-Key-t használj. Tarts külön kulcsokat a staging és a production számára, hogy csökkentsd a rotációs kockázatot és a környezetek összefonódását.

Rate limit-ek és újrapróbálkozások

Kerüld a szoros polling-ciklusokat. Használj kötegelt állapot-ellenőrzéseket, cache-eld a stabil eredményeket, és 429 esetén kövesd a reset/retryAfter értéket a backoff-újrapróbálkozások előtt.

Kéréspélda

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"
}

Válaszpélda

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

Hibaforgatókönyv-példa

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

Verziókezelés

Rögzítsd az endpoint-verziókat, és validáld a kérési sémákat a CI-ban, hogy elkapd az integrációs eltéréseket az éles kiadás előtt.

Támogatás

Sikertelen feladatoknál tárold a kérés payload hash-ét + requestId-t + error.details-t, hogy a csapatok elkülöníthessék a rossz bemeneteket a pipeline-incidensektől.

Gyors kezdés

Hozz létre egy SSEMBLE_API_KEY-t a dashboardon, és tárold a backend futásidőben.
Küldj minimális POST /shorts/create payloadot forrással + időzítéssel + nyelvvel.
Poll-ozd a GET /shorts/:id/status-t 10 másodpercenként a completed/failed/cancelled állapotig.
Kérd le a kimenetet a GET /shorts/:id-ből, és futtass felirat-QA-ellenőrzéseket.
Adj hozzá korlátozott újrapróbálkozásokat az átmeneti 429/5xx esetekhez, és irányítsd a kimerült feladatokat a DLQ-ba.

Kezdd a feliratozási endpoint dokumentációval

Integráció indítása

1) Hitelesítés beállítása

Biztonságos kulcskezelés és hitelesítési hibák

2) Create endpoint

Kérés törzsmezői és validáció

3) Hibakódok

Újrapróbálható és végleges hibataxonómia

4) Példák

cURL/JavaScript/Python integrációs kódrészletek

3 lépéses munkafolyamat

Rögzítsd a forrásmédiát és a feliratbeállításokat (nyelv/sablon/preferált hossz) a sormodellben.
Küldj be create kéréseket, figyeld az állapotátmeneteket, és irányítsd a végállapotokat automatikusan.
Publikáld a befejezett kimeneteket automatizált feliratolvashatósági és szabályzati ellenőrzések után.

Miért a Ssemble-t választják a csapatok

Olyan csapatoknak tervezve, ahol a felirat konzisztenciája befolyásolja a márkaminőséget és a nézők megtartását.
Állapotvezérelt QA-irányítást támogat a manuális beérkező üzenetek osztályozása helyett.
Több márkára skálázódik azáltal, hogy a stílus-/nyelvi szabályzatot az integrációs rétegedbe externalizálja.

Következő lépés

Felirat API gyors kezdés megnyitása Árazás megtekintése Fejlesztői dokumentáció

GYIK

Mi okozza általában a felirat-pipeline hibáit?

Gyakori okok az érvénytelen időzítési ablakok, az elérhetetlen forrás URL-ek és az érvénytelen nyelvi/sablon értékek. Ezeket validáld a sorba helyezés előtt.

Poll-ozzunk minden feladatot külön-külön nagy léptékben?

Csak alacsony volumen esetén. Nagyobb volumennél az aggregált állapotfigyelés csökkenti az API-terhelést és javítja a megbízhatóságot.

Hogyan tegyük biztonságossá az újrapróbálkozásokat?

Csak az átmeneti feltételeket próbáld újra (429/5xx/időtúllépések), és használj kérés-ujjlenyomatokat a duplikált feldolgozás megelőzésére.

Fixek a befejezési idők?

Nem. A befejezés a forrás hosszától, a sor állapotától és az opcióktól függően változhat. Az ETA-t tájékoztató jellegűként kezeld.

Érvényesíthetünk ügyfelenkénti feliratstílusokat?

Igen. Tartsd a stílus-/sablon-hozzárendeléseket a konfigurációs rétegedben, és injektáld bérlőnként a kérés létrehozásakor.

Mely éles riasztások a legfontosabbak?

Figyeld a hibaarányt hibakódonként, a sor korát és a beragadt feldolgozások számát, hogy korán észleld az incidenseket.