Transcript API

提交公开可访问的媒体 URL，跟踪异步任务状态，并通过统一 API 获取结构化转录、章节、翻译以及 SRT、VTT 字幕文件。

REST + JSON · UTF-8 · UTC / ISO 8601 · 支持 200+ 语言

快速开始

一个转录请求分为三个步骤。接口会立即返回，任务在后台异步处理。

1. 通过 POST /transcriptions 创建任务。
2. 轮询返回的 poll_url，并遵循 retry_after 指定的间隔。
3. 获取结构化结果和短期有效的字幕下载 URL。

身份验证

所有 OpenAPI 请求都通过 Bearer API Key 鉴权，不接受网站 Cookie 或登录 Token。

Authorization: Bearer $VT_API_KEY

幂等请求

每次逻辑创建操作都应使用稳定的 Idempotency-Key，避免网络重试产生重复计费任务。

来源与格式

请提供公开可访问的 HTTP 或 HTTPS URL。OpenAPI 不支持文件上传。

能力与计费

用量按照媒体时长向上取整计算：

billable_minutes = ceil(duration_seconds / 60)

任务生命周期

创建转录任务

通过公开媒体 URL 创建异步转录任务。

curl --request POST "https://videotranscriber.ai/openapi/v1/transcriptions" \
  --header "Authorization: Bearer $VT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: transcribe-order-0001" \
  --data '{
    "source_url": "https://example.com/media/demo.mp4",
    "language": "auto",
    "speaker_diarization": true,
    "features": {
      "chapters": true,
      "translation": {"target_language": "es"}
    }
  }'

{
  "request_id": "tr_01JEXAMPLE",
  "status": "queued",
  "poll_url": "/transcriptions/tr_01JEXAMPLE",
  "retry_after": 5
}

查询转录任务

查询任务状态、各能力状态、用量、错误和结果可用性。

curl --request GET \
  "https://videotranscriber.ai/openapi/v1/transcriptions/$REQUEST_ID" \
  --header "Authorization: Bearer $VT_API_KEY"

获取任务结果

获取成功能力的结构化结果，以及 SRT、VTT 文件的签名下载 URL。

curl --request GET \
  "https://videotranscriber.ai/openapi/v1/transcriptions/$REQUEST_ID/result" \
  --header "Authorization: Bearer $VT_API_KEY"

响应数据结构

JSON 使用 UTF-8 编码。时间轴字段统一使用秒并允许小数。客户端必须忽略未知响应字段。

未启用说话人识别，或供应商未返回可靠说话人标签时，speaker 字段为 null。

错误处理

请求级失败使用 HTTP 状态码和稳定的英文 error.code。不要根据 error.message 编写分支逻辑。

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "retryable": false
  },
  "request_id": "req_01JEXAMPLE"
}

限制与重试

请遵循 API 返回的速率限制和重试响应头：

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After

保留与安全