使用 REST API

发送第一个请求

计划使用的服务地址是 https://api.captionbolt.com。开放后，仅通过 Authorization Bearer 请求头发送密钥；不接受登录 Cookie 或 URL 参数中的密钥。请从服务器发起请求，不要在公开的浏览器应用中暴露密钥，也不要在重定向时转发鉴权信息。

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

通过 /v1/account 获取当前账户限制。使用 GET /v1/styles 或 GET /v1/presets 查找样式及自己的预设。列表支持 search、limit（1–100，默认 50）和 offset。

检查服务状态

GET /health/integrations 是无需 API Key 的公开接口。REST API、MCP 和 Webhook 投递链路正常时返回 HTTP 200，不可用时返回 HTTP 503。它是被动 readiness 检查，不是带用户凭据的端到端请求。

上传视频

电脑上的自动化可以使用本地 MCP处理上传细节。自行接入时按以下步骤操作：

调用 POST /v1/uploads，传入 Idempotency-Key 请求头和实际文件元数据。下面的值仅用于说明结构，不能直接作为真实文件信息使用。
轮询返回的 operation，直到 completed，以最终的 resourceId 作为上传 ID。
调用 GET /v1/uploads/{uploadId}，读取 partSize、partCount 和 completedPartNumbers。
使用 POST /v1/uploads/{uploadId}/parts 和 {"partNumbers":[1]} 为缺失分片签名，每次最多 32 片。向返回的 URL 直接 PUT 对应字节，并使用准确的内容长度。不要向存储上传地址发送 API Key。
全部分片成功后，以空 JSON 对象调用 POST /v1/uploads/{uploadId}/complete。确认完成后再创建项目。

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

请用秒数提交测得的 durationSec。省略时，服务器会按套餐允许的单条视频最长时长预留额度，因此剩余分钟较少时，短视频也可能被拒绝。处理前，服务器仍会校验实际时长。

文件指纹取自原始名称、大小、修改时间、MIME 类型，以及首尾各 64 KiB（不重叠）。下面的 Node.js 示例使用已选择的 File，请保留其原始元数据：

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

续传时重新选择原文件，先与 GET /v1/uploads/{uploadId} 返回的元数据和指纹逐一核对，再明确调用 POST /v1/uploads/{uploadId}/resume。DELETE /v1/uploads/{uploadId} 只能中止尚未被项目使用的上传，不会取消已创建的项目。

创建并跟踪项目

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

替换上传 UUID。可以选填 language，以及从列表获得的 styleId 或 presetId，二者不能同时传入。都不填时使用默认样式。mode 默认为 review；auto-export 还需要 exports:write 权限。

创建、导出、重试和取消会返回 HTTP 202 及 operation：

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

按 pollAfterSeconds 轮询 GET /v1/operations/{id}。operation 显示 completed 不代表视频已经制作完成。 随后查询 GET /v1/projects/{projectId} 或其 /status 接口，跟踪 processing、ready、exporting、completed、failed、cancelled。

超时后重复同一个操作时，请保留原来的 Idempotency-Key；新的操作意图使用新键。键为 1–128 个可打印且不含空格的 ASCII 字符，同一个键配不同输入会返回 409。

导出已保存的结果

在 review 模式下，先到主站编辑器检查并保存。将 PROJECT_ID 设为项目 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"]}'

导出采用最新保存的内容，不包含未保存的修改。outputFormats 可选择 mp4、srt、vtt、ass、txt，实际可用格式以当前套餐为准，默认 MP4。自动导出若停在 ready，请查看项目的 autoExport operation 是否失败。

项目达到 completed 后，调用 GET /v1/projects/{projectId}/result。下载链接最多有效十分钟，且不会超出项目访问期限。读取 expiresAt，及时保存结果。已完成的成片保持不变；需要继续修改时，在 CaptionBolt 中创建可编辑副本。

处理错误

400：核对输入和必需的幂等请求头。
401 / 403：检查密钥是否过期、已撤销或缺少权限；只有写权限时不能读取进度。
404：核对 ID、所属账户和访问期限，已删除或过期的资源不可访问。
409：检查项目当前状态，或是否用同一个幂等键提交了不同内容。
429：按 Retry-After 等待；同一账户所有密钥合计每分钟最多 120 次请求。
503 或超时：等待后查询 operation，或用原幂等键重发相同意图。响应丢失不代表任务失败。

明确需要重试或取消时，调用 POST /v1/projects/{projectId}/retry 或 /cancel，各自使用对应的幂等键。服务开放后，API 域名下的 /openapi.json 和 /docs 将提供完整请求及响应结构。