Integrare API

API de subtitrare video pentru automatizare de subtitrări sigură la QA și de volum mare

Automatizează generarea de subtitrări cu stări de job explicite, controale de limbă și retry-uri sigure pentru producție, pentru echipe care livrează volume mari de conținut short-form.

Problemă

La scară, operațiunile de subtitrare eșuează adesea la QA și consistență: verificările manuale de sincronizare, nepotrivirea de limbă și reviziile repetate devin un blocaj ascuns în producție.

Rezultat cu Ssemble

Ssemble permite o procesare deterministă a subtitrărilor, cu contracte clare de status/eroare, astfel încât echipele de inginerie să poată automatiza QA-ul de rutină și să escaladeze doar cazurile-limită reale.

Elemente esențiale de implementare

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

Arhitectură de integrare (ingerare → procesare → poll/webhook → publicare)

1) Ingerare

Stochează source URL/file URL plus câmpurile de configurare a subtitrărilor (language, captionLanguage, templateId, preferredLength).

2) Procesare

Apelează POST /shorts/create cu parametrii de subtitrare și persistă requestId + correlation id.

3) Poll / Webhook

Verifică GET /shorts/:id/status (sau endpointul list) la o cadență controlată, până la starea terminală.

4) Publicare

Obține materialele finalizate, rulează verificări automate de QA pe subtitrări și predă-le către coada de publicare.

Exemple de endpoint

POST /shorts/create— Creează un short cu subtitrare cu opțiuni de limbă/șablon
GET /shorts/:id/status— Urmărește etapa de procesare și failureReason
GET /shorts— Monitorizează joburile în lot fără costul unui apel per job

Îndrumări de autentificare

Folosește doar X-API-Key pe partea de server. Păstrează chei separate pentru staging și producție, pentru a reduce riscul de rotire și cuplarea între medii.

Rate limit și retry

Evită buclele de polling strânse. Folosește verificări de status în lot, memorează rezultatele stabile în cache și, la 429, respectă reset/retryAfter înainte de retry-uri cu backoff.

Exemplu de cerere

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

Exemplu de răspuns

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

Exemplu de scenariu de eroare

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

Versionare

Fixează versiunile de endpoint și validează schemele de cerere în CI pentru a detecta abaterile de integrare înainte de lansarea în producție.

Asistență

Pentru joburile eșuate, păstrează hash-ul payload-ului cererii + requestId + error.details, astfel încât echipele să poată separa inputurile greșite de incidentele de pipeline.

Ghid de pornire rapidă

Creează SSEMBLE_API_KEY în dashboard și stochează-o în runtime-ul backend.
Trimite un payload minimal POST /shorts/create cu sursă + timing + limbă.
Interoghează GET /shorts/:id/status la fiecare 10 secunde până la completed/failed/cancelled.
Obține rezultatul din GET /shorts/:id și rulează aserțiuni de QA pentru subtitrări.
Adaugă retry-uri limitate pentru 429/5xx tranzitorii și direcționează joburile epuizate către DLQ.

Începe cu documentația endpointului de subtitrare

Începe integrarea

1) Configurare autentificare

Gestionarea sigură a cheilor și erorile de autentificare

2) Endpoint create

Câmpurile din corpul cererii și validarea

3) Coduri de eroare

Taxonomia erorilor retryable și terminale

4) Exemple

Fragmente de integrare cURL/JavaScript/Python

Flux de lucru în 3 pași

Capturează media sursă și setările de subtitrare (limbă/șablon/lungime preferată) în modelul cozii tale.
Trimite cereri de create, monitorizează tranzițiile de status și direcționează automat stările terminale.
Publică rezultatele finalizate după verificări automate de lizibilitate a subtitrărilor și de conformitate cu politicile.

De ce echipele aleg Ssemble

Conceput pentru echipe unde consistența subtitrărilor influențează calitatea brandului și retenția spectatorilor.
Susține direcționarea QA în funcție de stare, în locul triajului manual din inbox.
Se scalează pe mai multe branduri prin externalizarea politicii de stil/limbă în stratul tău de integrare.

Pasul următor

Deschide ghidul de pornire rapidă pentru API-ul de subtitrare Vezi prețurile Documentație pentru dezvoltatori

Întrebări frecvente

Ce provoacă de obicei eșecurile în pipeline-ul de subtitrare?

Cauzele frecvente sunt ferestrele de timing invalide, URL-urile sursă indisponibile și valorile invalide de limbă/șablon. Validează-le înainte de a le pune în coadă.

Ar trebui să interogăm fiecare job individual la scară?

Doar la volum mic. La volum mai mare, monitorizarea agregată a statusului reduce încărcarea API-ului și îmbunătățește fiabilitatea.

Cum facem retry-urile sigure?

Fă retry doar la condițiile tranzitorii (429/5xx/timeout-uri) și folosește amprente ale cererii pentru a preveni procesarea duplicată.

Sunt fixe timpii de finalizare?

Nu. Finalizarea poate varia în funcție de lungimea sursei, condițiile cozii și opțiuni. Tratează ETA ca fiind orientativ.

Putem impune stiluri de subtitrare per client?

Da. Păstrează maparea de stil/șablon în stratul tău de configurare și injecteaz-o per tenant la crearea cererii.

Ce alerte de producție contează cel mai mult?

Monitorizează rata de eșec pe cod de eroare, vechimea cozii și numărul de joburi blocate în procesare pentru a detecta incidentele din timp.