拿到一个 YouTube 视频链接，想先读字幕、整理带时间戳的笔记，或导出 SRT？ytapi-youtube-transcript 给 Agent 提供取字幕的操作说明，实际请求由 YTAPI 服务处理。它读取已有的人工或自动字幕；不要把它当成对任意无字幕视频做音频转写的工具。
安装独立字幕 Skill
准备可以运行 npm/npx 的 Node.js 环境、Claude Code 或 Codex，以及能使用终端 curl 的 Agent。在项目终端运行：
npx skills add ytapi/youtube-skills --skill ytapi-youtube-transcript
按安装器提示选择你使用的 Agent 和项目安装范围，确认显示安装成功，再在该项目开启会话。不要把安装成功当作已经连接字幕服务。
到 YTAPI 控制台 登录并创建自己的 API key，通过客户端的密钥配置或启动环境提供 YTAPI_API_KEY。不要把真实 key 写进文章样例、Git 仓库或会被分享的聊天记录。Skill 的这个变量名与部分 API 文档示例中的 YT_API_KEY 不同；跟随本 Skill 时用前者。重新启动的 Agent 进程也需要能够读取它。
若在 macOS/Linux 的 Bash 终端操作，可以先输入 bash，再运行下面几行。它隐藏 key 的输入；随后在同一终端启动你的 Agent，让它继承环境变量。关闭终端后需要重新提供 key，或者按客户端的密钥配置持久保存。
read -r -s -p "YTAPI key: " YTAPI_API_KEY
printf "\n"
export YTAPI_API_KEY
如果你已经安装 YTAPI Claude 插件并通过 /mcp 登录，优先使用现有的 get_transcript 等工具，无需再叠加独立 key 路径。插件与这里的独立字幕 Skill 是不同入口。
第一次：一条视频，一份带时间戳的笔记
选择你能正常观看、已有字幕的公开视频。把下面示例中的链接换成自己的链接，在 Agent 会话输入：
使用 ytapi-youtube-transcript 处理这一个视频：<YouTube 视频链接>。
先查 basic-info，确认视频身份和 available_languages，再选原语言字幕。
将 segments JSON 保存为 transcript.json，不要把 key 输出到文件或聊天。
读完字幕后写 notes.md：列出三个主要观点，每条标注对应时间和回看链接。
区分字幕明确说到的内容与你的推断，不要根据字幕描述屏幕画面。
如果字幕不可用，请报告原因，不要编造摘要或自行购买额度。
先看标题和视频 ID 是否对应，再检查可用语言及 manual（作者字幕）或 asr（自动字幕）。长字幕应分段读完；使用 MCP 时，如果返回了后续 offset，继续读取后面的页，不能只总结第一页。
拿到文件后，核对 JSON 的 video_id、language、track_kind；抽看开头、中间和结尾的 segments，确认时间有序、末段不是意外截断。字幕轨长度不必与整段视频严格相等，例如片尾没有说话。任选笔记的一条时间链接回看视频，检查说法和时间是否匹配。自动字幕中的专有名词、数字和代码尤其值得人工复核。
想自己检查请求时
在已设置 YTAPI_API_KEY 的终端中使用下面的示例；VIDEO_ID 换成目标视频的 11 字符 ID。先确认所选文件名不会覆盖已有文件。
curl --fail-with-body --get 'https://api.ytapi.dev/v1/transcripts' --data-urlencode 'video_id=VIDEO_ID' --data-urlencode 'format=segments' --data-urlencode 'languages=*' -H "Authorization: Bearer $YTAPI_API_KEY" -o transcript.json
请求失败时，不要把保存下来的错误 JSON 当作字幕。若只要字幕文件，将格式换成 srt 并把输出文件名改成 transcript.srt。text、markdown、srt、vtt 返回的是文档正文，不需要再从 JSON 里找 text 字段；segments 则用于保留分段结构和秒数。
语言选择不是翻译
languages=* 选择视频原语言；en,* 表示先选已有英文轨，没有时回退原语言，并不会凭空生成英文翻译。默认 manual_first 在匹配语言里优先人工字幕；exact_only 要求语言代码精确匹配，en 不匹配 en-GB。先看可用轨道，再决定代码，不要不断重试一个不存在的语言。
做中文笔记可以先取原文，再让 Agent 翻译归纳。需要可播放的中文字幕文件时，还要单独翻译和校对时间轴；取到英文 SRT 不等于已经做出中文字幕。
费用和常见卡点
本说明按 Skill 1.2.0 整理。当前官方说明为注册赠送 200 credits，单次成功字幕请求 1 credit，basic-info 免费；免费 key 还有每秒 1 次、每日 100 次（UTC）限制。赠送额度不是无限免费，后续价格以控制台为准。
- 401： 检查 key 是否有效、当前 Agent 是否继承
YTAPI_API_KEY，以及是否误用了另一变量名。 - 402： 额度不足；停止请求，由你决定是否购买，不自动充值。
- 404 或字幕不可用： 核对视频是否公开、语言是否存在。可以回到原语言检查；没有字幕不代表应该假造转写。
- 429： 按
Retry-After等待；每日限额与余额是两件事，不应无限重试。 - 文件有内容但摘要不完整： 检查是否保存错误正文、只读到一页或遗漏后半段，再重新总结已有字幕。
视频地址和请求会交给 YTAPI；字幕用于笔记时仍要尊重原作者的内容权利。本文提供的是依官方合约设计的练习，没有展示真实提取结果。若你需要处理自己的本地无字幕音频，可以另看 Whisper 的本地转写指南。