API 参考

Base URL:

https://api.videototext.dev

响应结构

成功响应统一使用：

{
  "data": {},
  "meta": {}
}

错误响应使用 Problem Details：

{
  "type": "VALIDATION_ERROR",
  "title": "Validation failed",
  "status": 400,
  "detail": "Invalid request",
  "errorCode": "VALIDATION_ERROR"
}

转录模式

模式	费用	说明
balanced	每分钟 1 credit	默认模式
precision	每分钟 2 credits	更高精度选项

任务状态

状态	含义
QUEUED	任务正在等待处理资源。
PROCESSING	任务正在转录。
SUCCEEDED	转录结果已生成。
FAILED	任务失败，可能包含 showError。
CANCELED	任务已取消。

POST /v1/uploads

创建签名上传地址。

请求：

{
  "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": {}
}

POST /v1/uploads/{uploadId}/operations/complete

校验已上传对象、读取媒体时长，并创建 asset。

路径参数：

名称	类型	说明
uploadId	UUID	POST /v1/uploads 返回的上传会话 ID。

请求：

{
  "fileKey": "uploads/example.mp4",
  "fileUrl": "https://static.example.com/uploads/example.mp4",
  "filename": "meeting.mp4",
  "mimetype": "video/mp4",
  "fileSize": 10485760
}

响应：

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

常见错误包括 UPLOAD_SESSION_NOT_FOUND、UPLOAD_SESSION_EXPIRED、UPLOAD_SIZE_MISMATCH、UPLOAD_MIMETYPE_MISMATCH 和 UPLOAD_DURATION_UNREADABLE。

POST /v1/tasks

基于已上传 asset 创建转录任务。

如果需要安全重试创建任务，请阅读幂等性说明。

请求：

{
  "assetId": "00000000-0000-0000-0000-000000000000",
  "language": "Auto",
  "timestampMode": "CHUNK",
  "transcriptionMode": "balanced"
}

字段：

字段	类型	必填	说明
assetId	UUID	是	完成上传后返回的 asset。
language	string	否	默认 Auto。支持的语言使用小写名称，例如 english、spanish、chinese。
timestampMode	string	否	CHUNK 或 WORD，默认 CHUNK。
transcriptionMode	string	否	对外模式 key：balanced 或 precision，默认 balanced。

响应：

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "QUEUED",
      "language": "Auto",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000"
    }
  },
  "meta": {
    "pollAfterMs": 1500
  }
}

任务创建和任务详情响应始终包含 transcriptionMode，该字段返回用于计费和结果处理的公开模式 key。

GET /v1/tasks/{taskId}

返回客户端需要的任务状态和转录结果字段。

路径参数：

名称	类型	说明
taskId	UUID	POST /v1/tasks 返回的 data.task.transcriptId。

响应：

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "SUCCEEDED",
      "showError": null,
      "fullText": "Welcome to the meeting.",
      "chunks": [
        {
          "seq": 0,
          "startMs": 0,
          "endMs": 2200,
          "text": "Welcome to the meeting.",
          "speakerKey": null,
          "speakerName": null,
          "wordStartIndex": 0,
          "wordEndIndex": 1
        }
      ],
      "words": [
        {
          "text": "Welcome",
          "startMs": 0,
          "endMs": 600
        }
      ],
      "sourceDurationMs": 90400,
      "language": "Auto",
      "resultLanguage": "english",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000",
      "createdAt": "2026-06-06T09:00:00.000Z"
    }
  },
  "meta": {}
}