API-integratie

Video Caption API voor grootschalige, QA-veilige ondertitelautomatisering

Automatiseer ondertitelgeneratie met expliciete jobstatussen, taalcontroles en productieveilige retries voor teams die grote volumes short-form content leveren.

Probleem

Op schaal lopen ondertitelbewerkingen vaak vast bij QA en consistentie: handmatige timingcontroles, taalmismatches en herhaalde revisies worden een verborgen productieknelpunt.

Resultaat met Ssemble

Ssemble maakt deterministische ondertitelverwerking mogelijk met duidelijke status-/foutcontracten, zodat engineeringteams routinematige QA kunnen automatiseren en alleen echte randgevallen escaleren.

Implementatie-essentials

Basis-URL: https://aiclipping.ssemble.com/api/v1

Integratiearchitectuur (ingest → verwerking → polling/webhook → publiceren)

1) Ingest

Sla de source URL/file URL plus de ondertitelconfiguratievelden op (language, captionLanguage, templateId, preferredLength).

2) Verwerking

Roep POST /shorts/create aan met de ondertitelparameters en persisteer de requestId + correlation id.

3) Poll / Webhook

Controleer GET /shorts/:id/status (of het list-endpoint) op een gecontroleerde cadans tot de terminale status.

4) Publiceren

Haal de voltooide assets op, voer geautomatiseerde QA-controles van de ondertitels uit en geef door aan de publicatiewachtrij.

Endpoint-voorbeelden

POST /shorts/create— Maak een short met ondertitels met taal-/template-opties
GET /shorts/:id/status— Volg de verwerkingsfase en de failureReason
GET /shorts— Monitor jobs in batch zonder de overhead van één call per job

Authenticatierichtlijnen

Gebruik uitsluitend de X-API-Key server-side. Houd aparte sleutels aan voor staging en productie om het rotatierisico en de koppeling tussen omgevingen te beperken.

Rate limits en retries

Vermijd strakke pollingloops. Gebruik statuscontroles in batch, cache stabiele resultaten en volg bij een 429 reset/retryAfter vóór retries met backoff.

Voorbeeld van een request

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

Voorbeeld van een response

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

Voorbeeld van een foutscenario

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

Versiebeheer

Pin de endpointversies en valideer de request-schema's in CI om integratiedrift op te vangen vóór de productierelease.

Support

Bewaar bij mislukte jobs de hash van de request-payload + requestId + error.details, zodat teams ongeldige invoer kunnen onderscheiden van pipeline-incidenten.

Quickstart

Maak een SSEMBLE_API_KEY aan in het dashboard en sla deze op in de backend-runtime.
Verstuur een minimale POST /shorts/create-payload met source + timing + language.
Poll GET /shorts/:id/status elke 10 seconden tot completed/failed/cancelled.
Haal de output op via GET /shorts/:id en voer de QA-asserties van de ondertitels uit.
Voeg begrensde retries toe voor tijdelijke 429/5xx en route uitgeputte jobs naar de DLQ.

Begin met de documentatie van het caption-endpoint

Integratie starten

1) Authenticatie-opzet

Veilige sleutelverwerking en authenticatiefouten

2) Create-endpoint

Velden van de request-body en validatie

3) Foutcodes

Taxonomie van retryable en terminale fouten

4) Voorbeelden

Integratiesnippets in cURL/JavaScript/Python

Workflow in 3 stappen

Leg de bronmedia en ondertitelinstellingen (taal/template/gewenste lengte) vast in je wachtrijmodel.
Verstuur create-requests, monitor de statustransities en route terminale statussen automatisch.
Publiceer voltooide outputs na geautomatiseerde controles op leesbaarheid en beleid van de ondertitels.

Waarom teams voor Ssemble kiezen

Ontworpen voor teams waar ondertitelconsistentie de merkkwaliteit en kijkersretentie beïnvloedt.
Ondersteunt statusgestuurde QA-routing in plaats van handmatige inbox-triage.
Schaalt over meerdere merken door het stijl-/taalbeleid te externaliseren in je integratielaag.

Volgende stap

Quickstart van de Caption API openen Prijzen bekijken Ontwikkelaarsdocumentatie

FAQ

Wat veroorzaakt doorgaans storingen in de ondertitelpipeline?

Veelvoorkomende oorzaken zijn ongeldige timingvensters, onbereikbare source URLs en ongeldige taal-/templatewaarden. Valideer deze vóór het in de wachtrij plaatsen.

Moeten we elke job afzonderlijk pollen op schaal?

Alleen bij een laag volume. Bij een hoger volume vermindert geaggregeerde statusmonitoring de API-belasting en verbetert het de betrouwbaarheid.

Hoe maken we retries veilig?

Doe alleen een retry bij tijdelijke condities (429/5xx/timeouts) en gebruik request-fingerprints om dubbele verwerking te voorkomen.

Zijn de voltooiingstijden vast?

Nee. De voltooiing kan variëren op basis van de bronlengte, de wachtrijcondities en de opties. Behandel de ETA als indicatief.

Kunnen we ondertitelstijlen per klant afdwingen?

Ja. Houd de stijl-/template-mappings in je configuratielaag en injecteer ze per tenant bij het aanmaken van de request.

Welke productie-alerts zijn het belangrijkst?

Monitor de foutratio per error code, de wachtrijleeftijd en het aantal vastgelopen verwerkingen om incidenten vroeg te detecteren.