De REST API gebruiken

Authenticeer een aanvraag

Het geplande adres is https://api.captionbolt.com. Stuur na vrijgave de sleutel alleen in de Bearer-header Authorization. Cookies en sleutels in URL-parameters worden niet geaccepteerd. Doe aanvragen vanaf uw server; toon de sleutel niet in de browser en stuur hem niet door bij omleidingen.

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

Lees limieten via /v1/account, stijlen via GET /v1/styles en eigen voorinstellingen via GET /v1/presets. Lijsten accepteren search, limit (1–100, standaard 50) en offset.

Controleer de servicestatus

GET /health/integrations is openbaar en vereist geen API-sleutel. Het endpoint retourneert HTTP 200 wanneer de REST API, MCP en Webhook-bezorging operationeel zijn, of HTTP 503 wanneer ze niet beschikbaar zijn. Dit is een passieve gereedheidscontrole, geen geauthenticeerde end-to-endaanvraag.

Upload uw video

Lokale MCP regelt uploads vanaf de computer. Voor een eigen integratie:

Stuur POST /v1/uploads met Idempotency-Key en echte bestandsmetadata. Onderstaande waarden zijn voorbeelden, geen herbruikbare bestandsidentiteit.
Vraag de bewerking op tot completed; de uiteindelijke resourceId is de upload-ID.
Lees GET /v1/uploads/{uploadId} voor partSize, partCount en completedPartNumbers.
Onderteken ontbrekende delen met POST /v1/uploads/{uploadId}/parts en {"partNumbers":[1]}, maximaal 32 per aanvraag. PUT elk deel naar zijn URL met de exacte lengte. Stuur nooit de API Key naar opslag.
Stuur na alle delen een leeg JSON-object naar POST /v1/uploads/{uploadId}/complete. Maak daarna het project.

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

Geef de gemeten duur in seconden op als durationSec. Zonder deze waarde reserveert de server de maximale videoduur van je abonnement. Daardoor kan ook een korte video worden geweigerd als er minder minuten over zijn. De server controleert de werkelijke duur vóór de verwerking.

Bereken de vingerafdruk met oorspronkelijke naam, grootte, wijzigingstijd, MIME en de eerste/laatste 64 KiB zonder overlap. Dit Node.js-voorbeeld gebruikt het geselecteerde File met originele metadata:

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

Selecteer voor hervatten hetzelfde bestand, vergelijk metadata en vingerafdruk met GET /v1/uploads/{uploadId} en roep expliciet POST /v1/uploads/{uploadId}/resume aan. DELETE /v1/uploads/{uploadId} stopt een ongebruikte upload, niet een aangemaakt project.

Maak en volg een project

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

Vervang de upload-UUID. Optioneel zijn language en styleId of presetId, nooit beide. Zonder deze twee geldt de standaardstijl. De modus is standaard review; auto-export vereist ook exports:write.

Aanmaken, exporteren, opnieuw proberen en annuleren geven HTTP 202 met een bewerking:

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

Vraag GET /v1/operations/{id} op volgens pollAfterSeconds. Een bewerking met completed betekent niet dat de video klaar is. Lees daarna GET /v1/projects/{projectId} of /status: processing, ready, exporting, completed, failed of cancelled.

Herhaal na een timeout dezelfde opdracht met de oorspronkelijke Idempotency-Key. Gebruik voor een nieuwe bedoeling een nieuwe sleutel. Toegestaan zijn 1–128 afdrukbare ASCII-tekens zonder spaties; dezelfde sleutel met andere gegevens geeft 409.

Exporteer het opgeslagen resultaat

Controleer en bewaar in review-modus in de editor. Stel PROJECT_ID in op de project-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"]}'

Export gebruikt het laatst opgeslagen document zonder niet-opgeslagen wijzigingen. outputFormats accepteert volgens uw abonnement mp4, srt, vtt, ass en txt; MP4 is standaard. Blijft auto-export op ready, controleer de fout van de autoExport-bewerking van het project.

Bij completed haalt u GET /v1/projects/{projectId}/result op. Links gelden maximaal tien minuten en verlengen projecttoegang niet. Controleer expiresAt en bewaar op tijd. Maak voor wijzigingen aan voltooide exports een bewerkbare kopie in CaptionBolt.

Los fouten op

400: controleer invoer en idempotentieheader.
401 / 403: controleer vervaldatum, intrekking en rechten; alleen schrijven geeft geen toegang tot voortgang.
404: controleer ID, account en toegangstermijn. Verwijderde of verlopen bronnen zijn niet beschikbaar.
409: controleer status en gegevens bij de sleutel.
429: wacht Retry-After; alle accountsleutels delen 120 aanvragen per minuut.
503 of timeout: wacht, vraag de bewerking op of herhaal met de originele sleutel. Een verloren antwoord bewijst geen mislukking.

Gebruik POST /v1/projects/{projectId}/retry of /cancel voor expliciete acties, elk met een eigen sleutel. Volledige schema’s staan na vrijgave op /openapi.json en /docs van het API-domein.