Korzystanie z REST API

Uwierzytelnij żądanie

Planowany adres to https://api.captionbolt.com. Po udostępnieniu wysyłaj klucz tylko w nagłówku Bearer Authorization. Ciasteczka i klucze w URL nie są akceptowane. Wysyłaj żądania z serwera, bez ujawniania klucza w przeglądarce i przekazywania go przy przekierowaniach.

# CAPTIONBOLT_API_KEY: injected by your secret manager
curl --fail-with-body https://api.captionbolt.com/v1/account \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY"

Odczytaj limity w /v1/account, style przez GET /v1/styles, a własne ustawienia przez GET /v1/presets. Listy obsługują search, limit (1–100, domyślnie 50) i offset.

Sprawdź stan usługi

GET /health/integrations jest publiczny i nie wymaga klucza API. Zwraca HTTP 200, gdy REST API, MCP i dostarczanie Webhooków działają prawidłowo, albo HTTP 503, gdy są niedostępne. Jest to pasywne sprawdzenie gotowości, a nie uwierzytelnione żądanie end-to-end.

Prześlij film

Lokalny MCP obsługuje przesyłanie z komputera. Dla własnej integracji:

Wyślij POST /v1/uploads z Idempotency-Key i rzeczywistymi metadanymi pliku. Wartości poniżej są przykładowe, nie stanowią tożsamości pliku do ponownego użycia.
Odpytuj operację do completed; końcowe resourceId jest identyfikatorem przesyłania.
Odczytaj GET /v1/uploads/{uploadId}: partSize, partCount, completedPartNumbers.
Podpisz brakujące części przez POST /v1/uploads/{uploadId}/parts i {"partNumbers":[1]}, do 32 na żądanie. Wyślij każdą część metodą PUT na jej URL z dokładną długością. Nigdy nie wysyłaj API Key do magazynu plików.
Po wszystkich częściach wyślij pusty obiekt JSON do POST /v1/uploads/{uploadId}/complete, a dopiero potem utwórz projekt.

{
  "fileName": "lesson.mp4",
  "fileSize": 10485760,
  "durationSec": 60,
  "lastModifiedMs": 1789000000000,
  "contentType": "video/mp4",
  "fingerprint": "<64-character-lowercase-sha256>"
}

Podaj zmierzoną długość w sekundach w polu durationSec. Bez tej wartości serwer rezerwuje maksymalną długość filmu dozwoloną w planie. Dlatego nawet krótki film może zostać odrzucony, jeśli zostało mniej minut. Serwer weryfikuje rzeczywistą długość przed przetwarzaniem.

Oblicz odcisk z oryginalnej nazwy, rozmiaru, czasu modyfikacji, MIME oraz pierwszych i ostatnich 64 KiB bez nakładania. Przykład Node.js używa wybranego File z oryginalnymi metadanymi:

import { createHash } from "node:crypto";

// file: the exact selected File, with its original name and lastModified
const prefix = `captionbolt-upload-v1\0${file.name}\0${file.size}\0${file.lastModified}\0${file.type}`;
const first = await file.slice(0, 65536).arrayBuffer();
const last = await file.slice(Math.max(65536, file.size - 65536)).arrayBuffer();
const fingerprint = createHash("sha256")
  .update(prefix, "utf8")
  .update(Buffer.from(first))
  .update(Buffer.from(last))
  .digest("hex");

Aby wznowić, wybierz ten sam plik, porównaj metadane i odcisk z GET /v1/uploads/{uploadId}, potem jawnie wywołaj POST /v1/uploads/{uploadId}/resume. DELETE /v1/uploads/{uploadId} przerywa niewykorzystane przesyłanie, nie utworzony projekt.

Utwórz i śledź projekt

curl --fail-with-body https://api.captionbolt.com/v1/projects \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-001-create' \
  --data '{"uploadSessionId":"<uploaded-session-uuid>","mode":"review"}'

Zastąp UUID przesyłania. Możesz podać language oraz styleId lub presetId, nigdy obu. Bez nich używany jest styl domyślny. Domyślny tryb to review; auto-export wymaga także exports:write.

Tworzenie, eksport, ponawianie i anulowanie zwracają HTTP 202 oraz operację:

{
  "id": "operation-uuid",
  "resourceId": "resource-uuid",
  "state": "pending",
  "error": null,
  "pollAfterSeconds": 2
}

Odpytuj GET /v1/operations/{id} według pollAfterSeconds. Operacja completed nie oznacza ukończenia filmu. Następnie odczytaj GET /v1/projects/{projectId} lub /status: processing, ready, exporting, completed, failed, cancelled.

Po przekroczeniu czasu powtórz to samo polecenie z pierwotnym Idempotency-Key. Nowy zamiar wymaga nowego klucza. Klucz zawiera 1–128 drukowalnych znaków ASCII bez spacji; ten sam klucz z innymi danymi zwraca 409.

Eksportuj zapisany wynik

W trybie review sprawdź i zapisz w edytorze. Ustaw PROJECT_ID na identyfikator projektu:

curl --fail-with-body "https://api.captionbolt.com/v1/projects/$PROJECT_ID/export" \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-001-export' \
  --data '{"outputFormats":["mp4"]}'

Eksport używa ostatnio zapisanego dokumentu, bez niezapisanych zmian. outputFormats obsługuje mp4, srt, vtt, ass i txt zgodnie z planem; domyślnie MP4. Jeśli auto-export pozostaje w ready, sprawdź błąd operacji autoExport projektu.

Przy completed pobierz GET /v1/projects/{projectId}/result. Linki działają najwyżej dziesięć minut i nie wydłużają dostępu do projektu. Sprawdź expiresAt i zapisz wyniki na czas. Aby zmienić gotowy eksport, utwórz edytowalną kopię w CaptionBolt.

Rozwiąż błędy

400: sprawdź dane i nagłówek idempotencji.
401 / 403: sprawdź wygaśnięcie, unieważnienie i uprawnienia; sam zapis nie pozwala odczytać postępu.
404: sprawdź ID, konto i termin dostępu. Usunięte lub wygasłe zasoby są niedostępne.
409: sprawdź stan i dane przypisane do klucza.
429: odczekaj Retry-After; wszystkie klucze konta współdzielą 120 żądań na minutę.
503 lub timeout: poczekaj, odczytaj operację albo ponów z pierwotnym kluczem. Utrata odpowiedzi nie dowodzi błędu zadania.

Używaj POST /v1/projects/{projectId}/retry lub /cancel do jawnych działań, z osobnym kluczem dla każdego. Pełne schematy będą dostępne po otwarciu w /openapi.json i /docs domeny API.