youtube

YouTube

用于通过 YouTube Data API v3（https://www.googleapis.com/youtube/v3/）操作 YouTube 的脚本：搜索和读取视频、更新或删除视频、点赞或点踩视频、创建和管理播放列表及其条目、读取和发布评论、管理订阅，以及读取频道、类别和字幕元数据。共 22 个脚本，涵盖视频发现、视频和播放列表管理、社区互动，以及 Agent 解析 ID 所需的读取接口。

适用于 YouTube 的独立非官方连接器。与 YouTube 无关联、未获其认可，也未受其赞助。“YouTube”是其所有者的商标，仅用于标识此连接器所服务的平台。

适用场景

• Agent 需要查找或读取视频数据——搜索视频、获取视频的完整统计数据和详情、列出播放列表中的视频，或读取频道的个人资料和上传内容。
• Agent 需要管理视频——更新现有视频的元数据，同时保留未修改的字段；点赞或点踩；或删除其拥有的视频。
• Agent 需要整理播放列表——创建、更新或删除播放列表，以及添加或移除视频。
• Agent 需要参与社区互动——读取评论串、发布评论、回复评论串，或订阅／取消订阅频道。

设置

这是一个 agentskills.io 技能。

如果尚未将此连接器安装为技能，请先运行 npx skills add zapier/connectors --skill youtube（或使用你的运行环境自己的技能安装机制）进行安装，然后继续操作。安装技能只会复制这些文件，不会安装依赖项。运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令前，请在此处运行一次 npm install --omit=dev。如果你想在自己的项目中将已发布的软件包作为依赖项导入呢？此时，npm install 已会解析所有依赖项——请参阅 references/use-as-sdk.md。

如果你想获取实际的仓库源码，以浏览 references/、运行此连接器的测试或修改代码，请参阅 README.md，了解如何克隆指定范围的内容。

此连接器需要 Node.js 22.18+。选择与你的运行方式相符的参考文档，并在执行其他操作前先加载该文档：

你拥有……	加载
支持 MCP 的客户端——工具可能已加载（例如 mcp__youtube__<tool>），也可以自行注册本地服务（或指导用户注册）	references/use-as-mcp.md
终端／子进程访问权限（你可以运行 node）	references/use-as-cli.md
仅有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法访问工具或终端，也无法导入此软件包——你需要编写自己的代码，直接调用 YouTube API（例如，在代码执行沙盒中）	references/use-as-recipe.md

脚本

所有脚本都使用单个连接 youtube。

Script	Script 名称	连接	描述
scripts/searchVideos.ts	searchVideos	单个（youtube）	按关键词、频道、日期或时长搜索视频（仅返回 id 和 snippet；使用独立配额池）。
scripts/getVideo.ts	getVideo	单个（youtube）	按 id 获取一个或多个视频的完整详情 — snippet、statistics、contentDetails、status。
scripts/updateVideo.ts	updateVideo	单个（youtube）	更新视频的元数据（读取-修改-写入 — 仅更改传入的字段）。
scripts/deleteVideo.ts	deleteVideo	单个（youtube）	永久删除你拥有的视频。
scripts/rateVideo.ts	rateVideo	单个（youtube）	对视频点赞、点踩或清除评分。
scripts/listPlaylists.ts	listPlaylists	单个（youtube）	列出用户或频道拥有的播放列表，或按 id 获取播放列表。
scripts/createPlaylist.ts	createPlaylist	单个（youtube）	在用户的频道中创建新的播放列表。
scripts/updatePlaylist.ts	updatePlaylist	单个（youtube）	更新播放列表的标题、说明或隐私设置（替换而非合并）。
scripts/deletePlaylist.ts	deletePlaylist	单个（youtube）	永久删除你拥有的播放列表。
scripts/listPlaylistItems.ts	listPlaylistItems	单个（youtube）	按顺序列出播放列表中的视频（每个条目都包含其 playlistItem id）。
scripts/addVideoToPlaylist.ts	addVideoToPlaylist	单个（youtube）	将视频添加到你拥有的播放列表中。
scripts/removeVideoFromPlaylist.ts	removeVideoFromPlaylist	单个（youtube）	从播放列表中移除一个条目（按 playlistItem id，而非 video id）。
scripts/listComments.ts	listComments	单个（youtube）	列出视频的顶级评论主题，每条评论都包含首批回复。
scripts/postComment.ts	postComment	单个（youtube）	在视频下发布新的顶级评论（需要评论权限范围）。
scripts/replyToComment.ts	replyToComment	单个（youtube）	回复现有的顶级评论主题（需要评论权限范围）。
scripts/getChannel.ts	getChannel	单个（youtube）	获取频道的个人资料、统计数据和上传内容播放列表 id（通过 mine / id / @handle）。
scripts/listVideoCategories.ts	listVideoCategories	单个（youtube）	列出某个地区可分配的视频类别。
scripts/listSubscriptions.ts	listSubscriptions	单个（youtube）	列出用户的订阅，或检查是否订阅了某个频道。
scripts/subscribeToChannel.ts	subscribeToChannel	单个（youtube）	让用户订阅某个频道。
scripts/unsubscribeFromChannel.ts	unsubscribeFromChannel	单个（youtube）	让用户取消订阅某个频道（按 subscription id，而非 channel id）。
scripts/listCaptions.ts	listCaptions	单个（youtube）	列出某个视频可用的字幕轨道（需要评论/字幕权限范围）。
scripts/downloadCaption.ts	downloadCaption	单个（youtube）	以指定格式下载字幕轨道文本（srt/vtt/sbv/scc/ttml）。

消歧与拒绝

写入前先消歧。 如果要对通过名称查找的视频、播放列表或频道执行写入操作（例如，来自 searchVideos 的视频、来自 listPlaylists 的播放列表、来自 getChannel/searchVideos 的频道），先统计标题完全匹配且不区分大小写的结果数量：

• 恰好一个匹配项 — 对其执行操作。不要过度追问；只有一个明确匹配项时，它就是答案。
• 两个或更多匹配项并列 — 停止操作。列出这些候选项，并提供可用于区分的字段（频道标题、发布日期、观看次数或 id），询问用户指的是哪一个。YouTube 上的标题并非唯一——许多视频和频道都可能同名——所以绝不要随意选择，也不要对所有匹配项执行写入操作。

留意 id 陷阱。 removeVideoFromPlaylist 接收的是 listPlaylistItems 返回的 playlistItem id，而不是视频 id。unsubscribeFromChannel 接收的是 listSubscriptions 返回的 subscription id，而不是频道 id。传入错误的 id 是最常见的失败原因；请先通过列出的脚本查明正确 id。

不支持的操作——说明情况并停止；不要用其他脚本冒充支持。 本目录明确不支持：

• 报告分析数据（随时间变化的观看次数、观看时长、收入、人口统计信息）。这里没有分析脚本。不要用视频的生命周期 statistics 计数代替分析报告。
• 管理评论（编辑、删除、隐藏、标记为垃圾信息或设置审核状态）——仅支持读取、发布和回复。回复只能有一层：不能回复已有回复。
• 直播（创建或管理广播/直播流）或上传/替换字幕——这里只能读取字幕（列出 + 下载）。
• 上传视频或设置自定义缩略图——这里没有 uploadVideo 或 setVideoThumbnail 脚本。这些操作需要上传二进制媒体，而连接传输不支持此功能。
• 管理频道（编辑频道品牌、分区或设置）。

如果用户要求执行上述任何操作，请告知用户当前不支持并停止——不要调用无关脚本来近似实现。

身份验证

每种形态都会将一个连接选择器而非密钥传递给身份验证，格式为 [<resolver>:]<value> 字符串。每个连接器都接受 zapier:<connection-id>（Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层路由）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请查看此连接器自身的解析器，不要想当然。<resolver>: 前缀为可选项；不带前缀的值会交给第一个接受它的解析器——UUID 格式的不带前缀值始终会被 zapier: 接受。每个脚本都会声明所需的连接以及各自接受的解析器。传递连接的确切语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考资料。

想先检查已配置的内容？不要为了检查而输出环境变量值——env 或 env | grep <name> 会连同名称一起打印变量值；如果其中设有有效凭据，就会将其泄露到对话记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式，并按照对应参考资料中的流程获取连接；不要直接询问用户连接 id 或令牌，仿佛他们已经记住了：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 封装：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何检查脚本的确切形状，请参阅你上面加载的参考文档）。
• meta.outputDataValidation — 对 data 进行验证后的情况：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剔除：脚本从 API 返回了这些字段，但 outputSchema 未声明这些字段。如果需要这些字段，请跳过输出验证后重新运行。
  • { skipped: true } — 已绕过验证；data 是原始的、未经检查的脚本输出。

读取被剔除的字段／skipOutputDataValidation。 若要接收原始的、未经验证的结果，请选择退出输出验证（确切语法因形状而异；请参阅你上面加载的参考文档）。输入验证永远不会跳过。

缩减结果／filterOutputData。 若要将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（确切语法同样因形状而异）。jq 只会针对 data 运行，而不会针对 { data, meta } 封装运行，因此表达式应以 data 为根（运行脚本的 --help，或形状对应的命令，查看其输出架构）。转换后的值会替换 data，meta 会保留，且结果不会根据输出架构重新验证。

参考文档

在处理相关内容之前，先加载对应的参考文件：

参考文档	涵盖内容	何时加载
references/youtube-api-gotchas.md	part 模型、按类别划分的配额系统、错误封装及 reason→恢复方式映射、OAuth 范围要求（youtube、youtube.force-ssl）、以字符串表示的计数，以及视频、搜索、播放列表、评论、字幕、频道和订阅各资源的特定注意事项。	在依赖计数、配额、范围、分页、ID 或任何不明显的响应字段之前加载。