Utiliser l’API REST

Authentifier une requête

L’adresse prévue est https://api.captionbolt.com. Après ouverture, envoyez la clé uniquement dans l’en-tête Bearer Authorization. Les cookies et clés dans l’URL ne sont pas acceptés. Appelez l’API depuis votre serveur, sans exposer la clé au navigateur ni la transmettre lors de redirections.

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

Lisez les limites sur /v1/account, les styles sur GET /v1/styles et vos préréglages sur GET /v1/presets. Les listes acceptent search, limit (1–100, 50 par défaut) et offset.

Vérifier l’état du service

GET /health/integrations est public et ne nécessite aucune clé API. Il renvoie HTTP 200 lorsque l’API REST, MCP et la livraison des Webhooks sont opérationnels, ou HTTP 503 lorsqu’ils sont indisponibles. Il s’agit d’un contrôle passif de disponibilité, pas d’une requête authentifiée de bout en bout.

Envoyer la vidéo

MCP local gère l’envoi depuis votre ordinateur. Pour votre propre intégration :

Envoyez POST /v1/uploads avec Idempotency-Key et les métadonnées réelles du fichier. Les valeurs ci-dessous illustrent la structure, pas une identité de fichier réutilisable.
Interrogez l’opération jusqu’à completed ; son resourceId final est l’identifiant d’envoi.
Lisez GET /v1/uploads/{uploadId} pour partSize, partCount et completedPartNumbers.
Signez les parties manquantes avec POST /v1/uploads/{uploadId}/parts et {"partNumbers":[1]}, jusqu’à 32 par requête. Envoyez chaque partie par PUT à son URL avec sa longueur exacte. N’envoyez jamais l’API Key au stockage.
Après toutes les parties, envoyez un objet JSON vide à POST /v1/uploads/{uploadId}/complete. Créez ensuite le projet.

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

Indiquez la durée mesurée en secondes dans durationSec. Sans cette valeur, le serveur réserve la durée maximale autorisée par votre forfait. Une vidéo courte peut donc être refusée si votre solde est inférieur. Le serveur vérifie la durée réelle avant le traitement.

Calculez l’empreinte avec le nom d’origine, la taille, la date de modification, le MIME et les premiers et derniers 64 KiB sans chevauchement. Cet exemple Node.js utilise le File choisi et ses métadonnées originales :

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

Pour reprendre, sélectionnez le même fichier, comparez métadonnées et empreinte avec GET /v1/uploads/{uploadId}, puis appelez explicitement POST /v1/uploads/{uploadId}/resume. DELETE /v1/uploads/{uploadId} interrompt un envoi non consommé, sans annuler un projet créé.

Créer et suivre le projet

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

Remplacez l’UUID d’envoi. Vous pouvez ajouter language et soit styleId, soit presetId, jamais les deux. Sans eux, le style par défaut s’applique. review est le mode initial ; auto-export exige aussi exports:write.

Création, export, nouvelle tentative et annulation renvoient HTTP 202 et une opération :

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

Interrogez GET /v1/operations/{id} selon pollAfterSeconds. Une opération completed ne signifie pas que la vidéo est terminée. Consultez ensuite GET /v1/projects/{projectId} ou /status : processing, ready, exporting, completed, failed ou cancelled.

Après un timeout, répétez un même ordre avec son Idempotency-Key d’origine. Une nouvelle intention utilise une autre clé. Elle contient 1–128 caractères ASCII imprimables sans espaces ; une clé réutilisée avec d’autres données renvoie 409.

Exporter le document enregistré

En mode review, vérifiez et enregistrez dans l’éditeur. Affectez l’ID du projet à 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"]}'

L’export reprend le dernier document enregistré, sans modifications non sauvegardées. outputFormats accepte mp4, srt, vtt, ass et txt selon votre forfait ; MP4 est le défaut. Si auto-export reste à ready, consultez l’erreur de l’opération autoExport du projet.

À l’état completed, demandez GET /v1/projects/{projectId}/result. Les liens durent au maximum dix minutes et ne prolongent pas l’accès au projet. Vérifiez expiresAt et sauvegardez à temps. Pour modifier un export terminé, créez une copie modifiable dans CaptionBolt.

Résoudre les erreurs

400 : vérifiez les données et l’en-tête d’idempotence.
401 / 403 : vérifiez expiration, révocation et permissions ; l’écriture seule ne permet pas de lire la progression.
404 : vérifiez ID, compte et durée d’accès. Les ressources supprimées ou expirées sont indisponibles.
409 : vérifiez l’état et les données associées à la clé.
429 : attendez Retry-After ; les clés du compte partagent 120 requêtes par minute.
503 ou timeout : attendez, interrogez l’opération ou répétez avec la clé d’origine. Une réponse perdue ne prouve pas un échec.

Utilisez POST /v1/projects/{projectId}/retry ou /cancel pour une action explicite, avec sa propre clé. Les schémas complets seront sur /openapi.json et /docs du domaine API après ouverture.