REST API verwenden

Erste Anfrage authentifizieren

Die geplante Adresse ist https://api.captionbolt.com. Senden Sie nach Freigabe den Schlüssel nur im Bearer-Header Authorization. Cookies und Schlüssel in URL-Parametern werden nicht akzeptiert. Rufen Sie vom Server aus auf, ohne den Schlüssel im Browser offenzulegen oder bei Weiterleitungen mitzuschicken.

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

Aktuelle Limits stehen unter /v1/account, Stile und eigene Vorlagen unter GET /v1/styles und GET /v1/presets. Listen akzeptieren search, limit (1–100, Standard 50) und offset.

Dienststatus prüfen

GET /health/integrations ist öffentlich und benötigt keinen API-Key. Der Endpunkt gibt HTTP 200 zurück, wenn REST API, MCP und Webhook-Zustellung betriebsbereit sind, andernfalls HTTP 503. Dies ist eine passive Bereitschaftsprüfung, keine authentifizierte Ende-zu-Ende-Anfrage.

Video hochladen

Lokales MCP übernimmt den Upload am Computer. Für eine eigene Integration:

Senden Sie POST /v1/uploads mit Idempotency-Key und echten Dateimetadaten. Die Beispielwerte sind Platzhalter, keine wiederverwendbare Dateiidentität.
Fragen Sie die Operation bis completed ab; die endgültige resourceId ist die Upload-ID.
Lesen Sie GET /v1/uploads/{uploadId} für partSize, partCount und completedPartNumbers.
Signieren Sie fehlende Teile mit POST /v1/uploads/{uploadId}/parts und {"partNumbers":[1]}, höchstens 32 pro Anfrage. Senden Sie jeden Teil per PUT mit exakter Länge an seine URL. Senden Sie niemals den API Key an den Speicher.
Senden Sie nach allen Teilen ein leeres JSON-Objekt an POST /v1/uploads/{uploadId}/complete. Erstellen Sie erst dann das Projekt.

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

Gib die gemessene Dauer in Sekunden als durationSec an. Ohne diesen Wert reserviert der Server die maximale Videodauer deines Tarifs. Deshalb kann auch ein kurzes Video abgelehnt werden, wenn weniger Minuten übrig sind. Vor der Verarbeitung prüft der Server die tatsächliche Dauer.

Berechnen Sie den Fingerabdruck aus Originalname, Größe, Änderungszeit, MIME und den ersten/letzten 64 KiB ohne Überschneidung. Das Node.js-Beispiel nutzt die gewählte File mit Originalmetadaten:

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");

Wählen Sie zum Fortsetzen dieselbe Datei, vergleichen Sie Metadaten und Fingerabdruck mit GET /v1/uploads/{uploadId} und rufen Sie ausdrücklich POST /v1/uploads/{uploadId}/resume auf. DELETE /v1/uploads/{uploadId} bricht einen noch nicht verbrauchten Upload ab, kein erstelltes Projekt.

Projekt erstellen und verfolgen

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

Ersetzen Sie die Upload-UUID. Optional sind language sowie styleId oder presetId, niemals beide. Ohne beide gilt der Standardstil. Standardmodus ist review; auto-export benötigt zusätzlich exports:write.

Erstellen, Export, Wiederholen und Abbrechen liefern HTTP 202 mit einer Operation:

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

Fragen Sie GET /v1/operations/{id} gemäß pollAfterSeconds ab. Eine Operation mit completed bedeutet nicht, dass das Video fertig ist. Lesen Sie anschließend GET /v1/projects/{projectId} oder /status: processing, ready, exporting, completed, failed oder cancelled.

Verwenden Sie nach einem Timeout für denselben Befehl den ursprünglichen Idempotency-Key. Neue Absichten erhalten neue Schlüssel. Erlaubt sind 1–128 druckbare ASCII-Zeichen ohne Leerzeichen; derselbe Schlüssel mit anderen Daten ergibt 409.

Gespeichertes Ergebnis exportieren

Prüfen und speichern Sie im review-Modus im Editor. Setzen Sie PROJECT_ID auf die Projekt-ID:

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

Der Export nutzt das zuletzt gespeicherte Dokument ohne ungespeicherte Änderungen. outputFormats akzeptiert je nach Tarif mp4, srt, vtt, ass und txt; MP4 ist Standard. Bleibt Auto-Export bei ready, prüfen Sie den Fehler der autoExport-Operation des Projekts.

Bei completed rufen Sie GET /v1/projects/{projectId}/result ab. Links gelten höchstens zehn Minuten und verlängern den Projektzugriff nicht. Prüfen Sie expiresAt und sichern Sie rechtzeitig. Für Änderungen an fertigen Exporten erstellen Sie eine bearbeitbare Kopie in CaptionBolt.

Fehler beheben

400: Eingaben und Idempotenz-Header prüfen.
401 / 403: Ablauf, Widerruf und Rechte prüfen; Schreibrechte allein erlauben keine Fortschrittsabfrage.
404: ID, Konto und Zugriffszeit prüfen. Gelöschte oder abgelaufene Ressourcen sind nicht verfügbar.
409: Zustand und zum Schlüssel gehörende Daten prüfen.
429: Retry-After abwarten; alle Schlüssel des Kontos teilen 120 Anfragen pro Minute.
503 oder Timeout: warten, Operation abfragen oder mit ursprünglichem Schlüssel wiederholen. Eine verlorene Antwort beweist keinen Fehlschlag.

Verwenden Sie POST /v1/projects/{projectId}/retry oder /cancel für ausdrückliche Aktionen mit jeweils eigenem Schlüssel. Vollständige Schemas stehen nach Freigabe unter /openapi.json und /docs der API-Domain.