techhorizonlabs/creator-audience

创作者受众分析

YouTube不会公开发布受众人口统计数据。youtube-channel-profile所使用的Data API也不包含这些数据。可靠的信息来源只有两个：频道所有者自愿分享的他们自己的YouTube分析数据，或是经用户批准使用的付费第三方估算数据。除此之外的任何其他方法都只是猜测。请明确说明这一点。

同意规则

1. 频道所有者的数据由所有者本人提供。他们有权决定分享哪些数据、涵盖哪些日期以及谁能看到这些数据。在请求访问之前，请务必获得他们的书面同意（例如电子邮件或消息）。
2. 所有者必须使用自己的账户登录。切勿索要他们的密码或登录验证码，也绝不要代为输入。
3. 付费查询需要获得许可。在每次进行付费查询之前，必须询问用户并告知费用。
4. 严禁通过姓名、面部、声音、评论或缩略图来推断年龄、性别或地理位置。
5. 数据仅用于当前任务。仅向所有者及其指定的人员展示（YouTube政策 III.E.3.b）。在收到删除请求后的7天内删除数据（III.E.4.g）。如果保留数据，每30天需重新确认所有者的授权（III.E.4.b）。

途径一：所有者从YouTube Studio分享（首选方案）

此方法无需API操作。适用于一次性简报。

选项A，导出：请求所有者打开YouTube Studio，进入“分析”页面，然后选择“受众”选项卡。他们选择一个日期范围（过去90天是一个不错的默认选项），然后分享年龄、性别和主要国家/地区数据的截图或导出文件。

选项B，只读访问：所有者打开YouTube Studio，进入“设置”，然后是“权限”，接着点击“邀请”。他们输入用户的Google账户电子邮件，并选择“查看者（受限）”角色。该角色可以查看分析数据，但不能查看收入。邀请在30天后过期。工作结束后，所有者可以在同一屏幕中移除访问权限。品牌账户频道必须首先切换到频道权限。

途径二：YouTube Analytics API（适用于重复或大型任务）

当频道所有者或其团队将自行运行此分析，或用于涉及书面同意的持续合作时，使用此方法。

1. 在Google Cloud中创建一个项目。启用YouTube Analytics API和YouTube Data API v3。
2. 设置OAuth同意屏幕：用户类型选择“外部”，发布状态选择“测试”。添加所有者的Google账户作为测试用户。
3. 创建OAuth客户端ID，类型选择“桌面应用”，并下载客户端文件。请将其视为机密信息。
4. 仅请求以下范围：
   • https://www.googleapis.com/auth/yt-analytics.readonly
   • https://www.googleapis.com/auth/youtube.readonly（reports.query参考文档现在也要求此权限）
   • 仅当所有者同意分享收入时，才添加yt-analytics-monetary.readonly。
5. 在所有者本人登录的机器上运行登录流程。例如：

# pip install google-auth-oauthlib requests
from google_auth_oauthlib.flow import InstalledAppFlow
import requests
SCOPES = ["https://www.googleapis.com/auth/yt-analytics.readonly",
          "https://www.googleapis.com/auth/youtube.readonly"]
creds = InstalledAppFlow.from_client_secrets_file("client_secret.json", SCOPES).run_local_server(port=0)
base = "https://youtubeanalytics.googleapis.com/v2/reports"
common = {"ids": "channel==MINE", "startDate": "2026-08-01", "endDate": "2026-10-31"}
auth = {"Authorization": f"Bearer {creds.token}"}
age_gender = requests.get(base, headers=auth, params={**common,
    "metrics": "viewerPercentage", "dimensions": "ageGroup,gender"}).json()
countries = requests.get(base, headers=auth, params={**common,
    "metrics": "views,estimatedMinutesWatched", "dimensions": "country",
    "sort": "-views", "maxResults": 10}).json()

6. 当Google要求时，所有者应选择正确的频道。channel==MINE 表示他们当前登录的频道。
7. 读取 columnHeaders 和 rows。viewerPercentage 仅涵盖已登录的观看者。当没有数据时，YouTube会省略 rows。请报告为“不可用”，切勿报告为零。
8. 仅在内存中持有令牌。使用完毕后，由用户撤销令牌：所有者可以在 myaccount.google.com/permissions 上执行此操作。测试版应用的刷新令牌也会在7天后过期。

途径三：付费估算（Influencers Club MCP）

Influencers Club 可以估算公开YouTube频道的受众人口统计数据。这是一个第三方模型，而非YouTube官方数据。每次查询会消耗积分。

1. 运行 check_credits（免费）并记录余额。
2. 告知用户该工具及其费用，然后等待明确同意。费用参考服务器README（检查日期：2026年11月5日）：enrich_by_handle_analytics 消耗0.8积分，返回受众人口统计数据。enrich_by_handle 消耗1积分；在较旧的服务器上，需传递 include_audience_data 为 true 以获取受众部分。enrich_by_handle_raw 消耗0.03积分，不包含受众数据。请首先阅读工具自身的描述，因为不同版本可能存在差异。
3. 仅对单个频道进行一次调用，platform 设置为 youtube，handle 设置为频道句柄或频道ID。
4. 如果任何调用返回限制或信用错误，请立即停止。不要重试，并报告已完成多少次查询。
5. 不要使用 get_audience_locations 或 get_audience_interests 来完成此任务。它们是免费的筛选值列表，而非创作者的实际受众数据。

将结果标记为“由Influencers Club估算”，并附上查询日期。切勿将其与频道所有者的数据混合而不明确说明各自的来源。

在简报中应包含的内容

• 每个数据的来源：频道所有者的YouTube分析数据（需注明日期范围）、所有者的Studio导出文件，或第三方估算结果。
• 已登录观看者的年龄和性别分布比例，以及按观看次数排名靠前的国家/地区。
• 如果没有获得同意且没有批准付费，请写明：“受众人口统计数据：若无频道所有者的分析数据或付费估算，则无法获取。”这是一个完整的回答。

检查日期：2026年11月5日。参考来源包括YouTube Analytics API参考文档、指标与授权页面、YouTube关于频道权限的帮助文档，以及Influencers Club MCP的README和使用限制。