| name | videotranscript-api |
| description | 通过自部署的 VideoTranscriptAPI 服务，把 YouTube、Bilibili、抖音、小红书、小宇宙播客等平台链接（或直接可访问的音视频直链 URL）转成 AI 校对过的文字稿与总结。当用户分享视频/播客链接并希望拿到文字版、总结、要点、逐字稿时必须使用，即使只是说"这个视频讲了啥"、"帮我听一下这期播客"、"给我这个节目的文字版"、"总结一下这个 B 站视频"、"小宇宙这期在聊什么"也要触发。同样用于查询过去提交过的转录任务历史（按平台、作者、关键词、日期过滤）。注意：服务只接受 URL（平台链接或直链），不支持上传本地文件；若用户想转本地录音，需先把文件放到可访问的 URL 后再提交。 |
| metadata | {"openclaw":{"requires":{"bins":["python3","python"]},"env":[{"name":"VIDEO_TRANSCRIPT_API_BASE_URL","description":"API 请求地址。通常填内网/tailnet/局域网地址，图的是低延迟。例：http://localhost:8000","required":true},{"name":"VIDEO_TRANSCRIPT_API_TOKEN","description":"Bearer token，对应 config.jsonc 的 api.auth_token 或 users.json 中的 api_key","required":true},{"name":"VIDEO_TRANSCRIPT_API_PUBLIC_URL","description":"给用户点的公网地址（可选）。不设时用 BASE_URL。例：https://vt.example.com","required":false},{"name":"VIDEO_TRANSCRIPT_API_WECHAT_WEBHOOK","description":"企业微信 webhook 默认值（可选）。--webhook 传参时覆盖","required":false},{"name":"VIDEO_TRANSCRIPT_API_FEISHU_WEBHOOK","description":"飞书 webhook 默认值（可选）。--feishu-webhook 传参时覆盖","required":false}]},"hermes":{"required_environment_variables":[{"name":"VIDEO_TRANSCRIPT_API_BASE_URL","prompt":"API 请求地址（内网优先），如 http://localhost:8000","help":"服务端监听地址，通常是内网/tailnet/局域网 IP，图的是低延迟"},{"name":"VIDEO_TRANSCRIPT_API_TOKEN","prompt":"Bearer token","help":"对应 config.jsonc 的 api.auth_token 或 users.json 中的 api_key"},{"name":"VIDEO_TRANSCRIPT_API_PUBLIC_URL","prompt":"给用户点的公网地址（可选，回车跳过）","help":"不设时用 BASE_URL。服务端在内网但用户从公网看 /view/ 页面时需要","optional":true},{"name":"VIDEO_TRANSCRIPT_API_WECHAT_WEBHOOK","prompt":"企业微信 webhook（可选，回车跳过）","help":"设置后 submit 自动推送企微通知，--webhook 传参时覆盖","optional":true,"required":false},{"name":"VIDEO_TRANSCRIPT_API_FEISHU_WEBHOOK","prompt":"飞书 webhook（可选，回车跳过）","help":"设置后 submit 自动推送飞书通知，--feishu-webhook 传参时覆盖","optional":true,"required":false}]}} |
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 应主动轮询交付结果。 正确姿势：
- 调
submit，脚本输出中会包含 view_token 和一条 [url](url) 格式的查看链接
- 第一步永远是发查看链接：把脚本输出的查看链接原样复制，单独一条消息发给用户。无论后续是否立即拿到结果，这一步都不能跳过——链接是用户日后回看的永久入口
- 立即调
result <view_token> --type summary（可能命中缓存秒返回）
- 如果返回 202（还在处理），每隔 1 分钟轮询一次，最多轮询 10 次（覆盖 0–10 分钟）
- 返回 200 = 完成，把结果贴给用户；10 次仍未完成则告诉用户「还在处理中，可以点查看链接关注进度」
查看链接必须从脚本输出中原样复制，严禁自己拼接 URL。 脚本输出的「查看链接」已经是正确的 [url](url) markdown 格式，直接复制发给用户即可。不要凭记忆重写域名或路径——LLM 重构 URL 极易拼错字母（如把 lexgogo 写成 lexgugo），导致链接失效。
环境变量
skill 在调用时从环境读取，不要在对话里要求用户粘贴 token。
| 变量 | 必填 | 用途 | 示例 |
|---|
VIDEO_TRANSCRIPT_API_BASE_URL | ✅ | 脚本发 API 请求用的地址 | http://localhost:8000 / http://100.68.21.80:8200（tailnet） |
VIDEO_TRANSCRIPT_API_TOKEN | ✅ | Bearer token | config.jsonc 里 api.auth_token 或 users.json 的某个 key |
VIDEO_TRANSCRIPT_API_PUBLIC_URL | — | 给用户点的公网地址，不设时用 BASE_URL | https://vt.example.com |
VIDEO_TRANSCRIPT_API_WECHAT_WEBHOOK | — | 企业微信 webhook 默认值，--webhook 传参时覆盖 | https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx |
VIDEO_TRANSCRIPT_API_FEISHU_WEBHOOK | — | 飞书 webhook 默认值，--feishu-webhook 传参时覆盖 | https://open.feishu.cn/open-apis/bot/v2/hook/xxx |
为啥分两个地址：服务端常跑在内网/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 通用转录，更快。只有"谁说了什么"这件事对用户重要时才加。
| 内容类型 | 是否加 --speaker | 理由 |
|---|
| 多人访谈/对谈播客（如多人小宇宙节目、圆桌讨论） | ✅ 加 | 分段后才看得出谁的观点 |
| 会议录音、座谈、辩论 | ✅ 加 | 同上 |
| 用户明确说"分人物"、"分段"、"谁说的"、"区分讲话人"、"问答格式"、"按人物"、"每个人说了什么" | ✅ 加 | 用户意图明确——这些关键词都是要求在转写阶段启用说话人识别，不是后处理 |
| 单人讲解、教程、vlog、单人脱口秀 | ❌ 不加 | 只有一个人，分段没意义 |
| 单 UP 主口播视频、课程录播、单人解读 | ❌ 不加 | 同上 |
| 用户只要"总结"或"要点" | ❌ 不加 | summary 不需要分段，省时间 |
| 拿不准（比如不知道是单人还是多人） | ❌ 不加 | 更快；如果结果发现是多人再让用户重新提交 |
判断时可以参考视频标题、平台、作者名。比如小宇宙"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 站视频的总结
- 用户：「帮我看看这个视频 https://www.bilibili.com/video/BVxxx 讲了什么」
- 调
submit https://www.bilibili.com/video/BVxxx，脚本输出查看链接和 view_token
- 把脚本输出的查看链接原样复制，单独发一条消息给用户
- 立即调
result <view_token> --type summary，如果命中缓存直接拿到结果
- 返回 202 → 每隔 1 分钟重试，直到拿到结果（最多 10 次）
- 拿到结果后把总结贴给用户
场景 B：查找最近转过的小宇宙节目
- 用户：「我上周转过的那个小宇宙播客在哪」
- 调
history --platform xiaoyuzhou --start 2026-04-16 --end 2026-04-23
- 把结果列表贴给用户，附上
view_token 和查看页面链接
场景 C：想要带说话人分段的多人对话
- 用户：「这个访谈有三个人，能帮我做成问答格式吗」
- 调
submit <url> --speaker
- 其他流程同场景 A；
calibrated 结果里会带说话人标记
退出码语义（程序化调用时看这个）
| Exit | 含义 |
|---|
| 0 | 成功 |
| 1 | 业务失败（任务 failed、view_token 无效、结果为空） |
| 2 | 传输/基础设施问题（网络、5xx、401/403 鉴权失败） |
| 3 | 配置问题（缺 env、参数非法） |
遇到 exit 2 时别无脑重试 —— 先看 stderr，通常是 token 错或服务没起。遇到 503（队列满）可以隔 1–2 分钟退避重试。
Python 脚本跑不起来时的 HTTP Fallback
如果 python3 不可用或脚本执行报错（比如 Windows 环境兼容问题），直接用 curl 调 HTTP 端点。关键端点映射：
curl -X POST "$BASE_URL/api/transcribe" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://..."}'
curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/task/$TASK_ID"
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=summary"
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=calibrated"
curl -s "$BASE_URL/view/$VIEW_TOKEN?raw=transcript"
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。只有需要非标准字段、调试异常响应或自定义调用时才去读它。
