快速开始

本指南会走完整 API 流程：创建上传、上传媒体文件、完成上传、创建转录任务，并轮询任务结果。

访问 Video To Text 管理账号、创建 API 密钥，并返回产品工作区。

先设置 API 地址和密钥：

export VTT_API_BASE_URL="https://api.videototext.dev"
export VTT_API_KEY="vtt_xxxxx"

1. 创建上传

为媒体文件创建签名上传地址。

curl -X POST "https://api.videototext.dev/v1/uploads" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "meeting.mp4",
    "mimetype": "video/mp4"
  }'

响应会返回后续步骤需要的字段：

{
  "data": {
    "uploadUrl": "https://storage.example.com/signed-upload-url",
    "fileKey": "uploads/example.mp4",
    "fileUrl": "https://static.example.com/uploads/example.mp4",
    "uploadId": "00000000-0000-0000-0000-000000000000",
    "expiresAt": "2026-06-06T10:00:00.000Z"
  },
  "meta": {}
}

2. 上传文件

把二进制文件直接上传到 uploadUrl。Content-Type 需要和创建上传时传入的 mimetype 保持一致。

curl -X PUT "https://storage.example.com/signed-upload-url" \
  -H "Content-Type: video/mp4" \
  --data-binary "@meeting.mp4"

3. 完成上传

完成上传会让 Video To Text 校验对象，并创建可用于转录任务的 asset。

curl -X POST "https://api.videototext.dev/v1/uploads/$UPLOAD_ID/operations/complete" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "uploads/example.mp4",
    "fileUrl": "https://static.example.com/uploads/example.mp4",
    "filename": "meeting.mp4",
    "mimetype": "video/mp4",
    "fileSize": 10485760
  }'

响应会返回创建转录任务需要的 assetId。

{
  "data": {
    "assetId": "00000000-0000-0000-0000-000000000000"
  },
  "meta": {}
}

4. 创建转录任务

基于已上传的 asset 创建转录任务。默认模式是 balanced。

curl -X POST "https://api.videototext.dev/v1/tasks" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "00000000-0000-0000-0000-000000000000",
    "language": "Auto",
    "timestampMode": "CHUNK",
    "transcriptionMode": "balanced"
  }'

如果工作流更看重精度，可以使用 precision。

响应会返回 data.task.transcriptId；轮询时将这个值作为 TASK_ID 使用。

模式	适用场景
balanced	适合大多数生产流程的快速、经济转录。
precision	适合更看重识别质量的高精度转录。

5. 轮询任务

持续轮询任务接口，直到 status 变为 SUCCEEDED、FAILED 或 CANCELED。

curl "https://api.videototext.dev/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $VTT_API_KEY"

成功任务会返回全文、公开分段时间字段、逐词时间戳、源文件信息和实际计费 credits。