Usar a API REST

Autentique a primeira solicitação

O endereço previsto é https://api.captionbolt.com. Após a abertura, envie a chave apenas pelo cabeçalho Bearer Authorization. Cookies e chaves em parâmetros de URL não são aceitos. Faça as chamadas no servidor, sem expor a chave no navegador nem encaminhá-la em redirecionamentos.

# 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 limites em /v1/account e estilos ou predefinições próprias com GET /v1/styles e GET /v1/presets. As listas aceitam search, limit (1–100, padrão 50) e offset.

Verifique o status do serviço

GET /health/integrations é público e não exige chave de API. Ele retorna HTTP 200 quando a API REST, o MCP e a entrega de Webhooks estão operacionais, ou HTTP 503 quando estão indisponíveis. Essa é uma verificação passiva de prontidão, não uma solicitação autenticada de ponta a ponta.

Envie seu vídeo

O MCP local cuida do envio no computador. Para uma integração própria:

Envie POST /v1/uploads com Idempotency-Key e os metadados reais do arquivo. Os valores abaixo são exemplos, não uma identidade reutilizável.
Consulte a operação até completed e use o resourceId final como ID de envio.
Leia GET /v1/uploads/{uploadId} para obter partSize, partCount e completedPartNumbers.
Assine partes pendentes com POST /v1/uploads/{uploadId}/parts e {"partNumbers":[1]}, até 32 por chamada. Faça PUT de cada parte na URL recebida, com o tamanho exato. Nunca envie a API Key ao endereço de armazenamento.
Após todas as partes, envie um objeto JSON vazio para POST /v1/uploads/{uploadId}/complete. Só então crie o projeto.

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

Informe a duração medida em segundos em durationSec. Se ela for omitida, o servidor reserva a duração máxima de vídeo permitida pelo seu plano; por isso, um vídeo curto pode ser recusado se restarem menos minutos. O servidor verifica a duração real antes do processamento.

Calcule a impressão digital com nome original, tamanho, data de modificação, MIME e os primeiros e últimos 64 KiB sem sobreposição. O exemplo Node.js usa o File selecionado, preservando seus metadados:

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 retomar, selecione o mesmo arquivo, compare os metadados e a impressão digital com GET /v1/uploads/{uploadId} e chame POST /v1/uploads/{uploadId}/resume explicitamente. DELETE /v1/uploads/{uploadId} aborta um envio não consumido; não cancela um projeto já criado.

Crie e acompanhe o projeto

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

Substitua o UUID do envio. Você pode informar language e styleId ou presetId, nunca ambos. Sem os dois, vale o estilo padrão. O modo é review; auto-export também exige exports:write.

Criação, exportação, nova tentativa e cancelamento retornam HTTP 202 e uma operação:

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

Consulte GET /v1/operations/{id} conforme pollAfterSeconds. Uma operação completed não significa que o vídeo terminou. Depois consulte GET /v1/projects/{projectId} ou /status: processing, ready, exporting, completed, failed ou cancelled.

Após um timeout, repita o mesmo comando com a Idempotency-Key original. Use outra chave para uma nova intenção. Ela aceita 1–128 caracteres ASCII imprimíveis sem espaços; a mesma chave com dados diferentes retorna 409.

Exporte o resultado salvo

No modo review, revise e salve no editor. Defina PROJECT_ID com o ID do projeto:

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

A exportação usa o documento salvo mais recente, sem alterações não salvas. outputFormats aceita mp4, srt, vtt, ass e txt conforme o plano; MP4 é o padrão. Se auto-export ficar em ready, verifique o erro na operação autoExport do projeto.

Quando o projeto estiver completed, consulte GET /v1/projects/{projectId}/result. Os links duram no máximo dez minutos, sem ampliar o acesso ao projeto. Confira expiresAt e salve os resultados a tempo. Para alterar uma exportação concluída, crie uma cópia editável no CaptionBolt.

Resolva erros

400: confira os dados e o cabeçalho de idempotência.
401 / 403: confira validade, revogação e permissões; escrita não permite consultar progresso.
404: verifique ID, conta e prazo de acesso. Recursos excluídos ou expirados ficam indisponíveis.
409: confira o estado e os dados usados com a chave.
429: aguarde Retry-After; as chaves da conta compartilham 120 solicitações por minuto.
503 ou timeout: aguarde, consulte a operação ou repita com a chave original. Uma resposta perdida não comprova falha.

Use POST /v1/projects/{projectId}/retry ou /cancel para ações explícitas, cada uma com sua chave. Os esquemas completos estarão em /openapi.json e /docs do domínio API quando o acesso abrir.