文档

Videosays API 和 CLI 文档

面向接入和自动化的技术文档：API Key、CLI 命令、异步转写任务、响应结构和错误处理。

概览

Videosays 可以把支持平台的公开视频链接或分享文本转成纯文本、带时间轴文本、SRT 字幕或 VTT 字幕。手动使用可以进入控制台，本地自动化和 Agent Runtime 可用 CLI，产品集成可用 REST API。

认证

CLI 和 API 请求都使用 Videosays API Key。CLI 可以通过浏览器授权自动创建并保存 API Key。

export VIDEOSAYS_API_KEY="vs_xxxxx"

CLI

命令	说明
`npx videosays login`	浏览器授权并保存 API Key
`npx videosays whoami`	检查当前 CLI 是否已登录
`npx videosays transcribe "<video-link>"`	立即提交并返回 Task ID
`npx videosays status "<task-id>" --format srt`	短请求查询任务并返回 SRT 结果
`npx videosays batch links.txt`	立即创建最多 100 条的批次并返回 Batch ID
`npx videosays batch status "<batch-id>"`	短请求查看批次整体进度
`npx videosays batch continue "<batch-id>"`	充值后继续尚未处理的批次项目
`npx videosays balance`	查询账号可用分钟数
`npx videosays history`	查看最近任务历史

REST API

下载 OpenAPI 规范下载 Postman Collection

创建转写任务

POST https://api.videosays.com/api/v1/transcribe

{
  "input": "https://www.tiktok.com/@creator/video/123456"
}

创建可恢复批次（最多 100 条）

POST https://api.videosays.com/api/v1/batches

{
  "items": [
    "https://www.douyin.com/video/123",
    "https://www.youtube.com/watch?v=abc"
  ]
}

创建批次时会原子创建全部普通 Task，并与单任务共用同一队列。每个 Task 在提交供应商前原子预扣额度；某个 Task 额度不足时，尚未开始的 Task 会被跳过，充值后可继续同一批次。

查询任务状态和结果

GET https://api.videosays.com/api/v1/transcribe/:taskId

查询批次状态

GET https://api.videosays.com/api/v1/batches/:batchId

充值后继续批次

POST https://api.videosays.com/api/v1/batches/:batchId/continue

查询余额

GET https://api.videosays.com/api/v1/credits

查询历史任务

GET https://api.videosays.com/api/v1/history

响应格式

每次被接受的提交都会创建新的 Task ID（或 Batch ID）并立即返回。请用返回的 ID 轮询状态直到终态；再次提交相同输入会创建另一个资源。

text：纯文本，默认格式
timeline：带时间轴分段
srt：SRT 字幕内容
vtt：VTT 字幕内容

{
  "taskId": "uuid",
  "status": "completed",
  "video": {
    "platform": "tiktok",
    "durationSeconds": 72
  },
  "billing": {
    "creditMinutes": 1.2
  },
  "result": {
    "text": "Transcript text...",
    "segments": null
  },
  "error": null
}

错误处理

`401`	API Key 缺失或无效。
`402`	余额不足，需要先购买分钟数。
`400`	请求参数错误或输入不支持。
`404`	任务不存在，或不属于当前账号。
`429`	请求过于频繁，请稍后重试。
`500`	服务或供应商错误。如果源链接仍有效，可以稍后重试。