zj1123581321/videotranscriptapi/skill

VideoTranscriptAPI Skill

把视频/播客链接丢给自部署的 VideoTranscriptAPI 服务，拿回 AI 校对过的文字稿和 LLM 总结。

什么时候用这个 skill

触发场景：用户给了一个视频/播客链接（或音视频直链 URL），想要文字化内容或总结。

• 「帮我转录这个视频」「这期播客讲了什么」「给我这个 B 站视频的文字版」
• 「总结一下这个小宇宙节目」「提取这个 YouTube 的要点」
• 「我上次那个转录好了没」（查询历史任务）
• 「我最近转过哪些 YouTube 视频」（按平台过滤历史）

输入形态：

• 平台链接 —— YouTube、Bilibili（含 b23.tv 短链）、抖音、小红书、小宇宙播客，自动识别
• 音视频直链 —— .mp3 / .mp4 / .m4a / .wav 等公网可直接 GET 的 URL，走 submit 默认参数或 --download-url

不支持的场景：

• 上传本地文件 —— 服务端没有 multipart 上传端点。若用户拿着一个本地会议录音要转写，需先把文件放到可公网访问的 URL（OSS/S3/Dropbox 直链等）再调 submit。
• 视频画面理解 —— 本 skill 只做音轨转录+总结，不分析画面内容。

关键约束

任务是异步的，但 agent 应主动轮询交付结果。 正确姿势：

1. 调 submit，脚本输出中会包含 view_token 和一条 [url](url) 格式的查看链接
2. 第一步永远是发查看链接：把脚本输出的查看链接原样复制，单独一条消息发给用户。无论后续是否立即拿到结果，这一步都不能跳过——链接是用户日后回看的永久入口
3. 立即调 result <view_token> --type summary（可能命中缓存秒返回）
4. 如果返回 202（还在处理），每隔 1 分钟轮询一次，最多轮询 10 次（覆盖 0–10 分钟）
5. 返回 200 = 完成，把结果贴给用户；10 次仍未完成则告诉用户「还在处理中，可以点查看链接关注进度」

查看链接必须从脚本输出中原样复制，严禁自己拼接 URL。 脚本输出的「查看链接」已经是正确的 [url](url) markdown 格式，直接复制发给用户即可。不要凭记忆重写域名或路径——LLM 重构 URL 极易拼错字母（如把 zlxlabs 写成 zxlabs），导致链接失效。

API 错误响应

应用生成的 API 错误响应形如 {"detail": "<localized string>", "error_code": "<snake_case>"}。客户端应按稳定的 error_code 分支处理，detail 只用于展示，且会随服务端 language 配置变化；FastAPI 请求校验的 422 保持默认形状，不含 error_code。完整清单见 `references/api.md`。

环境变量

skill 在调用时从环境读取，不要在对话里要求用户粘贴 token。

为啥分两个地址：服务端常跑在内网/tailnet（BASE_URL 用这个，请求最快），但用户拿 /view/<token> 链接可能从公网打开。配 PUBLIC_URL 后，skill 返回给用户的查看页面 URL 用公网域名拼，无论用户在哪张网都点得开。没配 PUBLIC_URL 的场景（纯本机 / 都在一张网内）行为不变。

各平台配置方式：

• Claude Code：写入 ~/.claude/settings.json 的 "env" 字段（推荐，跨平台通用）；也可以写 shell profile 的 export，但 Windows 上 Git Bash 不一定会 source
• Hermes：写入 ~/.hermes/.env（KEY=VALUE 格式），或跑 hermes setup 交互式填入
• OpenClaw：编辑 ~/.openclaw/openclaw.json，在 skills.entries.videotranscript-api.env 下加这两三个

缺失必填变量时脚本会用 exit 3 和明确的 stderr 消息报错。

命令总览

所有命令通过 python3 <skill>/scripts/videotranscript.py <sub> ... 调用，输出默认是 markdown，加 --format json 拿结构化结果。

Windows 注意：Windows 上 python3 是系统占位程序（只会打开 Microsoft Store），实际的 Python 命令是 python。如果 python3 执行失败（exit code 非 0/1/2/3），改用 python 重试。

submit — 提交转录任务

python3 scripts/videotranscript.py submit <url> [options]

常用 options：

• --speaker：启用说话人识别（FunASR 引擎，结果会按说话人分段，但更慢）
• --webhook URL：完成后推送企业微信（覆盖服务端默认 webhook）
• --feishu-webhook URL：完成后推送飞书（覆盖服务端默认飞书 webhook）
• --title "...", --author "...", --description "..."：覆盖自动解析的元数据
• --download-url URL：绕过平台解析，用直链下载音视频

返回 view_token（和 task_id，可忽略）。只需要记住 `view_token`，后续查进度和拉结果都用它。

什么时候该加 --speaker

默认不加，走 CapsWriter 通用转录，更快。只有"谁说了什么"这件事对用户重要时才加。

判断时可以参考视频标题、平台、作者名。比如小宇宙"XX 对话 YY"、YouTube 的 interview with、标题含"对谈/圆桌/访谈"等就倾向加；一人名+"讲"、"教程"、"实录"、"vlog"倾向不加。

result — 查进度 & 拉结果

python3 scripts/videotranscript.py result <view_token> --type <summary|calibrated|transcript>

• summary（默认）：LLM 生成的要点总结 —— 绝大多数场景就用这个
• calibrated：LLM 校对过的完整文字稿（去除 ASR 错别字、加标点、分段）
• transcript：原始 ASR 输出（FunASR JSON 或 CapsWriter 纯文本，一般不用）

任务还没完成时会返回 exit 0 + 一行提示"仍在处理中"；拿不到结果时返回 exit 1。

history — 查历史任务

python3 scripts/videotranscript.py history [options]

Options：--platform youtube、--author 作者名、--q 关键词、--start 2026-01-01 --end 2026-01-31、--status success、--limit 20 --offset 0。

辅助命令

• status <task_id>：用 task_id 查详细进度（一般不需要，result 已经能判断是否完成）
• filter-options：列出服务端已有的平台/作者/webhook 列表（做下拉时用）
• profile：查当前 token 对应的用户信息
• health：无鉴权探活，用来排查连不上的问题

典型对话流

场景 A：用户想要一个 B 站视频的总结

1. 用户：「帮我看看这个视频 https://www.bilibili.com/video/BVxxx 讲了什么」
2. 调 submit https://www.bilibili.com/video/BVxxx，脚本输出查看链接和 view_token
3. 把脚本输出的查看链接原样复制，单独发一条消息给用户
4. 立即调 result <view_token> --type summary，如果命中缓存直接拿到结果
5. 返回 202 → 每隔 1 分钟重试，直到拿到结果（最多 10 次）
6. 拿到结果后把总结贴给用户

场景 B：查找最近转过的小宇宙节目

1. 用户：「我上周转过的那个小宇宙播客在哪」
2. 调 history --platform xiaoyuzhou --start 2026-04-16 --end 2026-04-23
3. 把结果列表贴给用户，附上 view_token 和查看页面链接

场景 C：想要带说话人分段的多人对话

1. 用户：「这个访谈有三个人，能帮我做成问答格式吗」
2. 调 submit <url> --speaker
3. 其他流程同场景 A；calibrated 结果里会带说话人标记

退出码语义（程序化调用时看这个）

遇到 exit 2 时别无脑重试 —— 先看 stderr，通常是 token 错或服务没起。遇到 503（队列满）可以隔 1–2 分钟退避重试。

Python 脚本跑不起来时的 HTTP Fallback

如果 python3 不可用或脚本执行报错（比如 Windows 环境兼容问题），直接用 curl 调 HTTP 端点。关键端点映射：

# 提交任务（需要 token）
curl -X POST "$BASE_URL/api/transcribe" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://..."}'
 
# 查任务状态（需要 token）
curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/task/$TASK_ID"
 
# 拉总结（不需要 token）
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=summary"
 
# 拉校对后全文（不需要 token）
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=calibrated"
 
# 拉原始转录（不需要 token）
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=transcript"
 
# 历史查询（需要 token）
curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/audit/history?platform=youtube&limit=20"

注意端点不要搞混：

• 拉结果文本用 /view/{view_token}?raw=<type>，不是 /api/result/...（不存在这个端点）
• /view/ 路径不需要鉴权，/api/ 路径需要

更深入的 API 细节

完整端点/字段/错误码对照参见 references/api.md。只有需要非标准字段、调试异常响应或自定义调用时才去读它。