Usare l’API REST

Autenticare una richiesta

L’indirizzo previsto è https://api.captionbolt.com. Dopo l’apertura, invia la chiave solo nell’header Bearer Authorization. Cookie e chiavi nell’URL non sono accettati. Effettua le chiamate dal server senza esporre la chiave nel browser o inoltrarla nei reindirizzamenti.

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

Leggi i limiti in /v1/account, gli stili in GET /v1/styles e le tue preimpostazioni in GET /v1/presets. Le liste accettano search, limit (1–100, valore predefinito 50) e offset.

Verificare lo stato del servizio

GET /health/integrations è pubblico e non richiede una chiave API. Restituisce HTTP 200 quando API REST, MCP e consegna Webhook sono operativi, oppure HTTP 503 quando non sono disponibili. È un controllo passivo di disponibilità, non una richiesta autenticata end-to-end.

Caricare il video

MCP locale gestisce il caricamento dal computer. Per un’integrazione propria:

Invia POST /v1/uploads con Idempotency-Key e metadati reali. I valori sotto sono esempi, non un’identità di file riutilizzabile.
Interroga l’operazione fino a completed e usa il resourceId finale come ID del caricamento.
Leggi GET /v1/uploads/{uploadId} per partSize, partCount e completedPartNumbers.
Firma le parti mancanti con POST /v1/uploads/{uploadId}/parts e {"partNumbers":[1]}, massimo 32 per richiesta. Invia ogni parte tramite PUT al suo URL con lunghezza esatta. Non inviare mai l’API Key allo storage.
Dopo tutte le parti, invia un oggetto JSON vuoto a POST /v1/uploads/{uploadId}/complete, poi crea il progetto.

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

Indica la durata misurata in secondi in durationSec. Se la ometti, il server riserva la durata massima consentita dal piano: anche un video breve può essere rifiutato se restano meno minuti. Il server verifica la durata effettiva prima dell’elaborazione.

Calcola l’impronta da nome originale, dimensione, modifica, MIME e primi/ultimi 64 KiB senza sovrapposizione. L’esempio Node.js usa il File selezionato con i suoi metadati originali:

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

Per riprendere, seleziona lo stesso file, confronta metadati e impronta con GET /v1/uploads/{uploadId}, poi chiama esplicitamente POST /v1/uploads/{uploadId}/resume. DELETE /v1/uploads/{uploadId} interrompe un caricamento non consumato, non un progetto creato.

Creare e seguire il progetto

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

Sostituisci l’UUID del caricamento. Puoi aggiungere language e styleId oppure presetId, mai entrambi. Senza i due identificatori vale lo stile predefinito. Il modo iniziale è review; auto-export richiede anche exports:write.

Creazione, esportazione, tentativi e annullamento restituiscono HTTP 202 e un’operazione:

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

Interroga GET /v1/operations/{id} secondo pollAfterSeconds. Un’operazione completed non significa che il video sia finito. Leggi poi GET /v1/projects/{projectId} o /status: processing, ready, exporting, completed, failed o cancelled.

Dopo un timeout, ripeti lo stesso comando con l’Idempotency-Key originale. Usa una nuova chiave per una nuova intenzione. Sono ammessi 1–128 caratteri ASCII stampabili senza spazi; stessa chiave con altri dati restituisce 409.

Esportare il documento salvato

In review, verifica e salva nell’editor. Imposta PROJECT_ID con l’ID del progetto:

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’esportazione usa l’ultimo documento salvato, senza modifiche non salvate. outputFormats ammette mp4, srt, vtt, ass e txt secondo il piano; MP4 è predefinito. Se auto-export resta in ready, controlla l’errore dell’operazione autoExport del progetto.

A completed, richiedi GET /v1/projects/{projectId}/result. I link durano al massimo dieci minuti e non estendono l’accesso al progetto. Controlla expiresAt e salva in tempo. Per modificare esportazioni finite, crea una copia modificabile in CaptionBolt.

Risolvere gli errori

400: controlla input e header di idempotenza.
401 / 403: controlla scadenza, revoca e permessi; la sola scrittura non legge i progressi.
404: controlla ID, account e accesso. Risorse eliminate o scadute non sono disponibili.
409: controlla stato e dati associati alla chiave.
429: attendi Retry-After; tutte le chiavi dell’account condividono 120 richieste al minuto.
503 o timeout: attendi, consulta l’operazione o ripeti con la chiave originale. Una risposta persa non dimostra un fallimento.

Usa POST /v1/projects/{projectId}/retry o /cancel per azioni esplicite, ognuna con la propria chiave. Gli schemi completi saranno in /openapi.json e /docs del dominio API dopo l’apertura.