YouTube 频道分析
scripts/channel_profile.py 通过 YouTube Data API v3 读取频道公开数据，并以 Markdown 报告形式输出，使用 --json 可输出 JSON。它仅使用官方 API，从不加载 YouTube 网页，也不向磁盘写入任何内容。
运行前准备
- 用户需要有一个启用了 YouTube Data API v3 的 Google Cloud 项目，并获取一个仅限该 API 的 API 密钥。
- 该密钥存放在
YOUTUBE_API_KEY环境变量中。切勿将其放入提示词、文件、聊天中，也切勿打印出来。如果此环境变量未设置，请停止并请用户设置。不要在其他地方查找密钥。 - 安装唯一依赖项：
pip install -r scripts/requirements.txt（即 requests）。
运行
python3 scripts/channel_profile.py @handle
python3 scripts/channel_profile.py https://www.youtube.com/@handle --videos 100
python3 scripts/channel_profile.py UCxxxxxxxxxxxxxxxxxxxxxx --json
选项：--videos N（要读取的近期上传数量，默认 50，最多 500），--json，--no-search，--cpm-low 和 --cpm-high（默认 0.25 和 4.00）。
如何查找频道
- 频道 ID 或
/channel/UC...形式的 URL：使用channels.list的id参数。 @handle或/@handle形式的 URL：使用channels.list的forHandle参数。/user/形式的 URL：使用forUsername参数。/c/形式的 URL 会尝试作为 handle 处理。- 如果以上都不匹配，则回退到
search.list查找最佳匹配，并在报告中说明。在依赖结果前请检查标题和 ID。--no-search可关闭此回退。 - 视频链接、播放列表链接和非 YouTube 地址将被拒绝。请提供频道链接。
配额
| 调用 | 成本 |
|---|---|
channels.list | 1 单位 |
playlistItems.list | 每 50 个上传视频 1 单位 |
videos.list | 每 50 个视频 1 单位 |
search.list（仅回退时） | 使用其独立配额池 |
默认运行消耗 3 单位（每日默认配额 10,000 单位）。自 2026 年 6 月 1 日起，search.list 拥有独立的每日 100 次调用配额池。在此之前，一次搜索消耗主配额池的 100 单位，因此旧指南会提到 100。失败的调用仍消耗配额。配额在太平洋时间午夜重置。每个报告末尾会显示本次使用的配额。
报告内容
来自 YouTube 的数据（直接返回）：
- 订阅者数，YouTube 会向下取整到三位有效数字。如果所有者隐藏了计数，报告显示“隐藏”且不给出猜测。
- 频道总观看量和公开视频数量。
- 每个近期视频的观看量、点赞数和评论数。
由脚本推导的数据（以 * 标记）：
- 上传节奏：最后 N 个上传视频之间的中位间隔天数、月均上传数（(N - 1) 个间隔 / 跨越天数 x 30.44），以及距上次上传的天数。
- 近期视频的观看量中位数和平均值。直播和即将到来的直播被排除。
- 趋势：最近 10 个上传视频的观看量中位数与前 10 个对比。更新的视频有更少的时间积累观看量。
- 参与度：每个视频的 (点赞数 + 评论数) / 观看量，取中位数。隐藏点赞数的视频被排除。关闭评论的视频评论数计为 0。
- Shorts 与长视频的区分，基于视频时长。这是一个启发式判断：时长 ≤ 180 秒视为 Shorts，因为 API 没有 Shorts 标志。
- 按观看量排序的前 5 个热门视频。
- 预估月观看量：最近 30 天内发布的视频当前观看量总和。这排除了历史目录的观看量。如果样本未覆盖到 30 天前，报告会说明并要求增大
--videos值。此检查假设上传播放列表按最新优先排列（通常如此）。
根据 YouTube API 政策 III.E.4.h，仅允许在 YouTube 自身数据旁展示衍生数据，并需明确标注非来自 YouTube。本报告已做到。每当引用带星号的数据时，请保留此标注。
收入估算方法
低估值 = 预估月观看量 / 1,000 x 0.25 美元
高估值 = 预估月观看量 / 1,000 x 4.00 美元
0.25 美元到 4.00 美元是 Social Blade 公布的默认 CPM 范围 (socialblade.com/youtube/calculator)。报告会显示带有实际数字的公式。这仅包含广告收入，不包括赞助、会员、购物、联盟营销以及粉丝资助。实际 RPM 因内容领域、受众国家和视频格式而异。Shorts 收入按不同条款合并计算。未加入 YouTube 合作伙伴计划的频道不产生广告收入。始终将其称为估算范围，而非实际收入。
错误
| 退出码 | 含义 | 应对措施 |
|---|---|---|
| 0 | 报告已打印 | |
| 2 | 输入错误、缺少密钥或未找到频道 | 修正输入，或请用户提供密钥或正确的链接 |
| 3 | 配额已用完 | 停止。告知用户配额在太平洋时间午夜重置。不要循环重试或切换密钥 |
| 4 | 其他 API 错误，如密钥无效或 API 未启用 | 将错误消息展示给用户 |
| 5 | 网络错误 | 重试一次，然后报告错误 |
错误输出会在失败前打印已使用的配额。每条消息和报告在打印前都会清除密钥信息。
规则
- 仅使用官方 API。不要爬取 YouTube 页面来填补数据缺口。报告数据缺口。
- 不缓存运行之外的任何数据。不要保存原始 API 响应。如果用户保留了报告，API 统计数据存储不得超过 30 天（政策 III.E.4.b）。
- 仅限公开数据。受众人口统计数据不属于公开数据：请参见
creator-audience技能。
最后检查于 2026 年 11 月 5 日，参照 YouTube Data API 参考资料、配额页面、修订历史和开发者政策。脚本的测试在离线模式下使用固定数据集运行。未在此处对实时 API 运行过。