Usar la API REST

Autenticar una solicitud

La URL prevista es https://api.captionbolt.com. Cuando se abra el acceso, envíe la clave únicamente en la cabecera Bearer Authorization. No se aceptan cookies ni claves en parámetros de URL. Haga las solicitudes desde su servidor, sin exponer la clave en el navegador ni reenviarla en redirecciones.

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

Consulte límites actuales en /v1/account y estilos o ajustes propios con GET /v1/styles y GET /v1/presets. Las listas aceptan search, limit (1–100, 50 por defecto) y offset.

Comprobar el estado del servicio

GET /health/integrations es público y no requiere una clave de API. Devuelve HTTP 200 cuando la API REST, MCP y la entrega de Webhooks están operativos, o HTTP 503 cuando no están disponibles. Es una comprobación pasiva de disponibilidad, no una solicitud autenticada de extremo a extremo.

Subir el vídeo

MCP local gestiona la subida desde el ordenador. Para una integración propia:

Envíe POST /v1/uploads con Idempotency-Key y los metadatos reales del archivo. Los valores del ejemplo son marcadores, no una identidad de archivo reutilizable.
Consulte la operación hasta completed y use su resourceId final como ID de subida.
Lea GET /v1/uploads/{uploadId} para obtener partSize, partCount y completedPartNumbers.
Firme las partes pendientes con POST /v1/uploads/{uploadId}/parts y {"partNumbers":[1]}, hasta 32 por solicitud. Envíe cada parte mediante PUT a su URL, con la longitud exacta. Nunca envíe la API Key al almacenamiento.
Tras subir todas las partes, envíe un objeto JSON vacío a POST /v1/uploads/{uploadId}/complete. Después cree el proyecto.

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

Incluye la duración medida en segundos en durationSec. Si la omites, el servidor reserva la duración máxima de vídeo de tu plan, por lo que puede rechazar un vídeo corto si quedan menos minutos. El servidor verifica la duración real antes de procesarlo.

Calcule la huella con el nombre, tamaño, fecha de modificación, MIME y los primeros y últimos 64 KiB sin solapamiento. Este ejemplo Node.js usa el File seleccionado con sus metadatos 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");

Para reanudar, seleccione el mismo archivo, compare metadatos y huella con GET /v1/uploads/{uploadId} y llame explícitamente a POST /v1/uploads/{uploadId}/resume. DELETE /v1/uploads/{uploadId} aborta una subida no consumida; no cancela un proyecto creado.

Crear y seguir el proyecto

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

Sustituya el UUID de subida. Puede incluir language y un styleId o presetId, nunca ambos. Sin ellos se usa el estilo predeterminado. review es el modo inicial; auto-export también requiere exports:write.

Crear, exportar, reintentar o cancelar devuelve HTTP 202 y una operación:

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

Consulte GET /v1/operations/{id} según pollAfterSeconds. Una operación completed no significa que el vídeo haya terminado. Consulte después GET /v1/projects/{projectId} o /status: processing, ready, exporting, completed, failed o cancelled.

Repita una solicitud idéntica con su Idempotency-Key original tras un timeout. Use otra clave para una intención nueva. Admite 1–128 caracteres ASCII imprimibles sin espacios; la misma clave con otros datos devuelve 409.

Exportar lo guardado

En modo review, revise y guarde en el editor. Asigne el ID del proyecto a 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"]}'

La exportación usa el último documento guardado, sin cambios pendientes. outputFormats acepta mp4, srt, vtt, ass y txt según el plan; MP4 es el predeterminado. Si auto-export queda en ready, revise el error de la operación autoExport del proyecto.

Cuando el proyecto esté completed, obtenga GET /v1/projects/{projectId}/result. Los enlaces duran como máximo diez minutos y no amplían el acceso al proyecto. Compruebe expiresAt y guarde los resultados a tiempo. Para cambiar una exportación terminada, cree una copia editable en CaptionBolt.

Resolver errores

400: compruebe datos y cabecera de idempotencia.
401 / 403: compruebe caducidad, revocación y permisos; escribir no permite consultar el progreso.
404: verifique ID, cuenta y plazo de acceso. Los recursos borrados o caducados no están disponibles.
409: revise el estado y los datos asociados a la clave.
429: espere Retry-After; todas las claves de la cuenta comparten 120 solicitudes por minuto.
503 o timeout: espere, consulte la operación o repita con la clave original. Una respuesta perdida no demuestra un fallo.

Use POST /v1/projects/{projectId}/retry o /cancel para acciones explícitas, cada una con su clave. Los esquemas completos estarán en /openapi.json y /docs del dominio API cuando se abra.