Integracja API

API do napisów wideo dla wielkoskalowej, bezpiecznej dla QA automatyzacji napisów

Automatyzuj generowanie napisów z jawnymi stanami zadań, kontrolą języka i bezpiecznymi produkcyjnie retry dla zespołów wdrażających duże wolumeny materiałów short-form.

Problem

Przy dużej skali operacje na napisach często zawodzą na etapie QA i spójności: ręczne sprawdzanie synchronizacji, niedopasowanie języka i powtarzające się poprawki stają się ukrytym wąskim gardłem produkcji.

Rezultat z Ssemble

Ssemble umożliwia deterministyczne przetwarzanie napisów z jasnymi kontraktami status/error, dzięki czemu zespoły inżynierskie mogą zautomatyzować rutynowe QA i eskalować jedynie rzeczywiste przypadki brzegowe.

Podstawy wdrożenia

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

Architektura integracji (przyjęcie → przetwarzanie → poll/webhook → publikacja)

1) Przyjęcie

Zapisz source URL/file URL oraz pola konfiguracji napisów (language, captionLanguage, templateId, preferredLength).

2) Przetwarzanie

Wywołaj POST /shorts/create z parametrami napisów i utrwal requestId + correlation id.

3) Poll / Webhook

Sprawdzaj GET /shorts/:id/status (lub endpoint list) w kontrolowanym rytmie aż do stanu terminalnego.

4) Publikacja

Pobierz ukończone materiały, uruchom automatyczne kontrole QA napisów i przekaż do kolejki publikacji.

Przykłady endpointów

POST /shorts/create— Utwórz short z napisami z opcjami języka/szablonu
GET /shorts/:id/status— Śledź etap przetwarzania i failureReason
GET /shorts— Monitoruj zadania wsadowo bez narzutu jednego wywołania na zadanie

Wskazówki dotyczące uwierzytelniania

Używaj X-API-Key wyłącznie po stronie serwera. Utrzymuj oddzielne klucze dla środowiska staging i produkcyjnego, aby ograniczyć ryzyko rotacji i powiązanie środowisk.

Limity zapytań (rate limit) i ponowne próby (retry)

Unikaj ciasnych pętli pollingu. Stosuj wsadowe sprawdzanie statusu, buforuj stabilne wyniki, a przy 429 uwzględniaj reset/retryAfter przed retry z backoffem.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Przykład scenariusza błędu

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

Wersjonowanie

Przypinaj wersje endpointów i waliduj schematy żądań w CI, aby wychwycić dryf integracji przed wdrożeniem produkcyjnym.

Wsparcie

Dla nieudanych zadań przechowuj hash payloadu żądania + requestId + error.details, aby zespoły mogły oddzielić błędne dane wejściowe od incydentów pipeline.

Szybki start

Utwórz SSEMBLE_API_KEY w panelu i zapisz w środowisku uruchomieniowym backendu.
Wyślij minimalny payload POST /shorts/create ze źródłem + synchronizacją + językiem.
Wykonuj polling GET /shorts/:id/status co 10 sekund aż do completed/failed/cancelled.
Pobierz wynik z GET /shorts/:id i uruchom asercje QA napisów.
Dodaj ograniczone retry dla przejściowych 429/5xx i kieruj wyczerpane zadania do DLQ.

Zacznij od dokumentacji endpointu napisów

Rozpocznij integrację

1) Konfiguracja uwierzytelniania

Bezpieczna obsługa klucza i błędy uwierzytelniania

2) Endpoint create

Pola treści żądania i walidacja

3) Kody błędów

Taksonomia błędów podlegających retry i terminalnych

4) Przykłady

Fragmenty integracji cURL/JavaScript/Python

Proces w 3 krokach

Rejestruj materiał źródłowy i ustawienia napisów (język/szablon/preferowana długość) w modelu kolejki.
Wysyłaj żądania create, monitoruj przejścia statusów i automatycznie kieruj stany terminalne.
Publikuj ukończone wyniki po automatycznych kontrolach czytelności napisów i zgodności z zasadami.

Dlaczego zespoły wybierają Ssemble

Zaprojektowane dla zespołów, w których spójność napisów wpływa na jakość marki i utrzymanie widza.
Obsługuje kierowanie QA oparte na stanach zamiast ręcznego triażu skrzynki odbiorczej.
Skaluje się na wiele marek dzięki wyniesieniu polityki stylu/języka do warstwy integracji.

Następny krok

Otwórz szybki start API napisów Zobacz cennik Dokumentacja dla programistów

FAQ

Co zwykle powoduje awarie pipeline'u napisów?

Typowe przyczyny to nieprawidłowe okna synchronizacji, niedostępne source URLs oraz nieprawidłowe wartości języka/szablonu. Waliduj je przed dodaniem do kolejki.

Czy powinniśmy odpytywać każde zadanie osobno przy dużej skali?

Tylko przy małym wolumenie. Przy większym wolumenie zagregowane monitorowanie statusu zmniejsza obciążenie API i poprawia niezawodność.

Jak zapewnić bezpieczne retry?

Ponawiaj tylko warunki przejściowe (429/5xx/timeouty) i używaj odcisków palca żądania, aby zapobiec powielaniu przetwarzania.

Czy czasy zakończenia są stałe?

Nie. Zakończenie może się różnić w zależności od długości źródła, warunków kolejki i opcji. Traktuj ETA jako orientacyjne.

Czy możemy wymusić style napisów per klient?

Tak. Utrzymuj mapowania stylów/szablonów w warstwie konfiguracji i wstrzykuj je per najemca przy tworzeniu żądania.

Które alerty produkcyjne mają największe znaczenie?

Monitoruj wskaźnik awaryjności według kodu błędu, wiek kolejki i liczbę zablokowanych zadań w przetwarzaniu, aby wcześnie wykrywać incydenty.