API 文档

供外部程序 / AI Agent 调用。Base URL = 本页 origin。所有响应为 JSON(文本下载端点除外)。

🤖 Agent 快速接入(3 步)

POST /api/jobs 提交 URL → 拿到 id
轮询 GET /api/jobs/{id} 直到 status == "done" (每 3~5 秒查一次)
GET /api/jobs/{id}/bundle 一次拿全:原文 + 中文翻译 + 中文总结 + 元数据

若需媒体文件,先 GET /api/jobs/{id}/files 获取下载路径清单。

鉴权

当服务端设置了 VT_API_KEY 时,所有 POST 请求必须带 key(GET 免鉴权):

Authorization: Bearer <你的key>
# 或直接拼在 URL 上:
POST /api/jobs?key=<你的key>

缺 key 或 key 错误 → 401 {"error":"unauthorized..."}

任务接口

GET/api/health

健康检查。返回 {"ok":true,"ts":"..."},无需鉴权。

POST/api/jobs

提交转录任务。支持所有 yt-dlp 站点(YouTube/Bilibili/Twitter 等),也支持 local://https://直链 与 file:///本地路径。

请求体

字段	类型	必填	说明
url	string	✅	媒体链接
title	string	—	自定义标题(留空自动取视频标题)
language	string	—	语言代码,如 "en"/"zh"。留空=自动检测
model	string	—	whisper 模型:tiny / base / small / medium / large-v3(默认 base)

示例

curl -X POST $BASE_URL/api/jobs \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=xxx","model":"base"}'

→ 201 {"id":"cfb5ee47...","status":"queued",...}

GET/api/jobs?status=&limit=

任务列表(新→旧)。status 可选过滤:queued / downloading / transcribing / translating / done / failed / canceled。limit 默认 100。

GET/api/jobs/{id}

查单个任务。status=="done" 即完成。job 对象字段:

{
  "id": "cfb5ee47...",       // 任务 ID
  "url": "https://...",      // 原始链接
  "title": "Me at the zoo",  // 标题
  "status": "done",          // queued|downloading|transcribing|translating|done|failed|canceled
  "progress": 1.0,           // 0~1
  "error": "",               // 失败原因
  "duration_seconds": 19,
  "transcript": "Alright...",     // 原文
  "transcript_zh": "好的,我们…",  // 中文翻译(源为中文时为空)
  "summary_zh": "这段视频是…",     // 中文总结(AI 生成)
  "meta": {"detected_language":"en", "uploader":"...", ...}
}

GET/api/jobs/{id}/bundle

推荐外部程序用这个。一个 JSON 拿全部:原文 + 中文翻译 + 中文总结 + 元数据。

GET/api/jobs/{id}/files

该任务全部产物清单(下载路径),外部程序据此逐个取:

{"job_id":"...","files":{
  "transcript_txt":   "/api/jobs/{id}/transcript",     // 原文 .txt
  "transcript_zh_txt":"/api/jobs/{id}/transcript-zh",  // 中文翻译 .txt
  "summary_zh_txt":   "/api/jobs/{id}/summary-zh",     // 中文总结 .txt
  "media":            "/api/jobs/{id}/media",          // 下载的音视频 (mp3)
  "media_filename":   "cfb5ee47....mp3",
  "audio_wav":        "/api/jobs/{id}/audio"           // 16kHz wav
}}

POST/api/jobs/{id}/analyze

手动重跑 AI 翻译+总结(对已完成任务)。返回更新后的 job。

POST/api/jobs/{id}/cancel

取消排队/运行中任务。成功返回 204。

文本/媒体下载(纯文本或二进制)

GET /api/jobs/{id}/transcript      → 原文纯文本
GET /api/jobs/{id}/transcript-zh   → 中文翻译纯文本
GET /api/jobs/{id}/summary-zh      → 中文总结纯文本
GET /api/jobs/{id}/media           → 媒体文件 (mp3)
GET /api/jobs/{id}/audio           → 16kHz wav
GET /api/jobs/{id}/logs            → 运行日志 JSON

文件系统对应位置(外部程序也可直接读盘):<data>/transcripts/<id>.txt|.zh.txt|.summary.txt 与 <data>/downloads/<id>.mp3|.wave.wav

实时事件(可选)

WS/ws (或 GET /events SSE)

连接后实时收到任务事件,无需轮询:

{"type":"job.created","job":{...}}
{"type":"job.progress","job":{...},"ts":"..."}
{"type":"job.log","job":{...},"line":"[download] 100% ..."}
{"type":"job.done","job":{"status":"done","transcript":"...","transcript_zh":"...","summary_zh":"..."}}
{"type":"job.failed","job":{"status":"failed","error":"..."}}

典型调用序列(Agent 视角)

1. POST /api/jobs            {"url":"...","model":"base"}      → id
2. 循环: GET /api/jobs/{id}  (每 5s)                            → 直到 status=="done" 或 "failed"
3. GET  /api/jobs/{id}/bundle                                    → transcript / transcript_zh / summary_zh
4. (可选) GET /api/jobs/{id}/media                               → 下载 mp3