Integrare API

API de traducere video pentru operațiuni de lansare multi-regiune

Localizează un singur videoclip sursă în mai multe rezultate pregătite pentru piață, cu automatizare bazată pe status, izolarea eșecurilor la nivel de locale și fluxuri de rollout controlate.

Problemă

Lansările globale eșuează adesea la sincronizare, nu la calitatea traducerii: limba principală se publică prima, în timp ce variantele regionale rămân în urmă și programarea campaniei se strică.

Rezultat cu Ssemble

Ssemble permite operațiuni de tip source-once, localize-many cu urmărire de stare specifică per locale, astfel încât echipele să poată lansa în valuri controlate și să recupereze rapid eșecurile parțiale.

Elemente esențiale de implementare

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

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

1) Ingerare

Creează manifestul de traducere: sursa, lista de locale, politica de rollout și comportamentul de fallback.

2) Procesare

Trimite cereri de create specifice per locale și persistă un release id părinte pentru trasabilitate end-to-end.

3) Poll / Webhook

Urmărește starea fiecărui locale în mod independent pentru a identifica rapid scenariile de succes parțial și de eșec parțial.

4) Publicare

Lansează localele care trec de porțile de QA/politici și repune în coadă localele eșuate cu o strategie de retry limitată.

Exemple de endpoint

POST /shorts/create— Creează joburi de procesare specifice per locale
GET /shorts/:id/status— Urmărește starea ciclului de viață al fiecărui locale
GET /shorts/:id— Obține rezultatul localizat finalizat pentru lansare

Îndrumări de autentificare

Păstrează cheile API și controalele de rollout doar în serviciile backend. Segmentează cheile per mediu și restrânge strict accesul de rollout în producție.

Rate limit și retry

Pune trimiterile de locale în cozi, în loturi controlate, nu în rafale de fan-out complet. Folosește backoff exponențial la 429/5xx și limitează retry-urile.

Exemplu de cerere

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

Exemplu de răspuns

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

Exemplu de scenariu de eroare

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

Versionare

Înregistrează metadatele de schemă/versiune pentru fiecare cerere de locale, astfel încât regresiile între locale să poată fi diagnosticate după schimbări de API.

Asistență

Persistă release id-ul părinte + locale + requestId la fiecare tranziție de stare pentru o recuperare rapidă a incidentelor de lansare parțială.

Ghid de pornire rapidă

Definește matricea de locale și strategia de rollout în configurația backend.
Creează câte o cerere de procesare per locale folosind câmpurile language/captionLanguage.
Interoghează statusul și actualizează tabloul de lansare până când fiecare locale este terminal.
Obține rezultatele finalizate și rulează verificări de QA specifice per locale.
Publică imediat localele care trec și direcționează localele eșuate către o coadă de retry limitată.

Deschide documentația fluxului de traducere

Începe integrarea

1) Autentificare

Tipare de chei API doar pe partea de server

2) Ciclul de viață al statusului

Model queued/processing/completed/failed

3) Strategie de rate limit

Headere, ferestre de reset și disciplina de polling

4) Taxonomia erorilor

Gestionare programatică după error.code

Flux de lucru în 3 pași

Ingerează un singur material sursă cu matricea de locale țintă și politica de rollout.
Procesează joburile per locale asincron, cu urmărire independentă a statusului pentru fiecare locale.
Publică localele finalizate prin cozi regionale, în timp ce localele eșuate sunt direcționate către retry-uri controlate.

De ce echipele aleg Ssemble

Conceput pentru echipe de canale regionale, unde coordonarea lansării este la fel de critică precum calitatea conținutului.
Izolează eșecurile per locale, astfel încât o singură problemă să nu blocheze întreaga lansare a campaniei.
Funcționează cu automatizarea publicării pentru fluxuri de distribuție de tip follow-the-sun.

Pasul următor

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

Întrebări frecvente

Cum împiedicăm un locale să blocheze toate regiunile?

Folosește mașini de stare per locale și porți de lansare, astfel încât fiecare locale să poată fi publicat independent, cu excepția cazului în care politica impune sincronizarea tuturor localelor.

Ar trebui să trimitem toate localele deodată?

De obicei, nu. Loturile controlate protejează bugetele de rate limit și simplifică triajul incidentelor atunci când calea unui locale se degradează.

Care este payload-ul minim de observabilitate?

Urmărește release id-ul părinte, codul de locale, requestId, tranzițiile de stare, codul de eroare și numărul de retry pentru fiecare job.

Ce erori ar trebui să facă retry automat?

Fă retry la erorile tranzitorii de transport, 429 și 5xx cu backoff. Eșuează rapid la erorile de validare și direcționează-le pentru corecție de configurare/date.

Pot fi separate traducerea și publicarea?

Da. Multe echipe păstrează finalizarea traducerii și publicarea pe canale în cozi separate, pentru un control mai bun și siguranță la rollback.

Garantează acest lucru rezultate egale pe toate localele?

Nu ar trebui presupusă nicio garanție. Măsoară timpul de finalizare, rata de eșec și rata de trecere a QA per locale și ajustează politica de rollout în consecință.