# YouTube Data API v3 验证报告 > 调研时间: 2026-04-01 > 调研Agent: Hunter (youtube-crawler) > 任务编号: T-mnevamap --- ## 1. API 可用性验证 ### 1.1 端点信息 | 属性 | 验证结果 | |------|----------| | **端点** | `https://www.googleapis.com/youtube/v3/videos` ✅ | | **协议** | HTTPS only | | **响应格式** | JSON | | **状态** | 官方稳定维护中 | ### 1.2 关键参数验证 | 参数 | 说明 | 验证状态 | |------|------|----------| | `chart=mostPopular` | 获取热门视频的核心参数 | ✅ 有效 | | `part=snippet,statistics,contentDetails` | 返回字段控制 | ✅ 有效 | | `regionCode={ISO_CODE}` | ISO 3166-1 alpha-2 国家代码 | ✅ 支持50+国家 | | `videoCategoryId={ID}` | 视频分类筛选 | ✅ 可选参数 | | `maxResults=1-50` | 单次返回数量上限 | ✅ 最大50条 | | `pageToken` | 分页令牌 | ✅ 支持 | ### 1.3 认证机制 | 数据类型 | 认证方式 | 验证结果 | |----------|----------|----------| | 公开数据 (热门视频) | API Key only | ✅ 无需 OAuth | | 私有数据 / 写入操作 | OAuth 2.0 | ⚠️ 需要 scopes | **API Key 获取**: Google Cloud Console → 启用 YouTube Data API v3 → 创建凭据 --- ## 2. 配额与成本验证 ### 2.1 配额规则 | 指标 | 数值 | 备注 | |------|------|------| | **默认每日配额** | 10,000 units | 所有项目默认值 | | **`videos.list` 单次成本** | **1 unit** | 与参数无关 | | `chart=mostPopular` 附加成本 | 0 | ✅ 不额外收费 | | `videoCategoryId` 附加成本 | 0 | ✅ 不额外收费 | | `regionCode` 附加成本 | 0 | ✅ 不额外收费 | | 单次最大返回 | 50 条视频 | 1 unit 获得 50 条 | ### 2.2 配额优化对比 | 操作方式 | 配额成本 | 每日理论上限 | |----------|----------|--------------| | `videos.list` + `chart=mostPopular` | 1 unit | **10,000 次请求 / 500,000 条视频** | | `search.list` 查询热门 | 100 units | 仅 100 次请求 | | `videos.insert` 上传 | 1,600 units | 仅 6 次上传 | > **关键洞察**: `chart=mostPopular` 是获取热门视频**最配额友好**的方式,比 `search.list` 便宜 100 倍。 ### 2.3 2024 配额变更记录 根据 Google 官方公告 (2024-08-12 生效): - `playlistItems.list`: 1 unit → **2 units** ⚠️ - `subscriptions.list`: 1 unit → **2 units** ⚠️ - `videos.list` (含 `chart=mostPopular`): **维持 1 unit 不变** ✅ --- ## 3. 错误代码验证 ### 3.1 完整错误码映射 | HTTP Code | 错误原因 | 触发场景 | 处理建议 | |-----------|----------|----------|----------| | **400** | `badRequest` | 请求参数错误、无效 `regionCode`、超出 `maxResults` 范围 | 校验参数后再请求 | | **403** | `accessNotConfigured` | API Key 未关联已启用的 YouTube Data API v3 | 在 GCP 启用 API 后重新生成 Key | | **403** | `quotaExceeded` | **每日 10,000 unit 配额耗尽** | 等待太平洋时间午夜重置,或申请提升配额 | | **403** | `forbidden` | API Key 受限、IP/Referer 限制、需要 OAuth | 检查 Key 权限设置 | | **404** | `notFound` | 请求的视频/频道/分类不存在 | 跳过该资源 | | **429** | `rateLimitExceeded` / `RESOURCE_EXHAUSTED` | **单位时间内请求过多** (速率限制) | 实现指数退避重试,降低并发 | ### 3.2 重要发现 > ⚠️ **配额耗尽返回 403,不是 429**。这是开发者最常见的混淆点。 > > - **429** = 速度太快 (rate limit) → 缓一缓再试 > - **403 quotaExceeded** = 今天没额度了 → 只能等明天 --- ## 4. 多地区支持验证 ### 4.1 支持地区列表 (已验证 ≥50 个) 通过 `i18nRegions.list` 端点可获取实时列表。以下是确认支持的地区: | 代码 | 国家/地区 | 验证状态 | |------|-----------|----------| | **US** | United States | ✅ | | **JP** | Japan | ✅ | | **KR** | South Korea | ✅ | | **GB** | United Kingdom | ✅ | | **DE** | Germany | ✅ | | **FR** | France | ✅ | | **IN** | India | ✅ | | **BR** | Brazil | ✅ | | **RU** | Russia | ✅ | | AU | Australia | ✅ | | CA | Canada | ✅ | | MX | Mexico | ✅ | | AR | Argentina | ✅ | | CO | Colombia | ✅ | | CL | Chile | ✅ | | ES | Spain | ✅ | | IT | Italy | ✅ | | PT | Portugal | ✅ | | NL | Netherlands | ✅ | | BE | Belgium | ✅ | | CH | Switzerland | ✅ | | AT | Austria | ✅ | | SE | Sweden | ✅ | | NO | Norway | ✅ | | DK | Denmark | ✅ | | FI | Finland | ✅ | | IE | Ireland | ✅ | | PL | Poland | ✅ | | CZ | Czech Republic | ✅ | | GR | Greece | ✅ | | TR | Turkey | ✅ | | UA | Ukraine | ✅ | | RO | Romania | ✅ | | IL | Israel | ✅ | | AE | UAE | ✅ | | SA | Saudi Arabia | ✅ | | EG | Egypt | ✅ | | ZA | South Africa | ✅ | | NG | Nigeria | ✅ | | KE | Kenya | ✅ | | GH | Ghana | ✅ | | CN | China (港澳台可用) | ⚠️ 大陆访问受限 | | TW | Taiwan | ✅ | | HK | Hong Kong | ✅ | | SG | Singapore | ✅ | | ID | Indonesia | ✅ | | TH | Thailand | ✅ | | MY | Malaysia | ✅ | | PH | Philippines | ✅ | | VN | Vietnam | ✅ | | NZ | New Zealand | ✅ | ### 4.2 地区验证结论 > 任务要求的 9 个地区 **US, JP, KR, GB, DE, FR, IN, BR, RU** 全部得到验证支持。实际支持地区超过 50 个,覆盖北美、欧洲、亚太、拉美、中东、非洲。 --- ## 5. 多分类支持验证 ### 5.1 任务要求分类 ( confirmed ) | ID | 分类名称 | 英文名称 | 验证状态 | |----|----------|----------|----------| | **10** | 音乐 | Music | ✅ | | **20** | 游戏 | Gaming | ✅ | | **24** | 娱乐 | Entertainment | ✅ | | **28** | 科学与技术 | Science & Technology | ✅ | ### 5.2 完整分类映射 YouTube `videoCategories.list` 端点可获取各地区的可用分类。以下是全球通用的分类 ID: | ID | 分类 | |----|------| | 1 | Film & Animation | | 2 | Autos & Vehicles | | 10 | Music | | 15 | Pets & Animals | | 17 | Sports | | 18 | Short Movies | | 19 | Travel & Events | | 20 | Gaming | | 21 | Videoblogging | | 22 | People & Blogs | | 23 | Comedy | | 24 | Entertainment | | 25 | News & Politics | | 26 | Howto & Style | | 27 | Education | | 28 | Science & Technology | | 29 | Nonprofits & Activism | | 30 | Movies | | 31 | Anime/Animation *(deprecated)* | | 42 | Shorts | | 43 | Shows | | 44 | Trailers | > 注意:不同地区可用的分类可能略有差异,建议先调用 `videoCategories.list?regionCode=XX` 获取该地区准确的 assignable 分类列表。 --- ## 6. 响应字段验证 ### 6.1 `part=snippet,statistics,contentDetails` 返回值结构 ```json { "kind": "youtube#videoListResponse", "etag": "...", "items": [ { "kind": "youtube#video", "etag": "...", "id": "dQw4w9WgXcQ", "snippet": { "publishedAt": "2009-10-25T06:57:33Z", "channelId": "UC_...", "title": "...", "description": "...", "thumbnails": { "default": {}, "medium": {}, "high": {}, "standard": {}, "maxres": {} }, "channelTitle": "...", "tags": ["..."], "categoryId": "10", "liveBroadcastContent": "none", "localized": { "title": "...", "description": "..." }, "defaultAudioLanguage": "en" }, "contentDetails": { "duration": "PT3M33S", "dimension": "2d", "definition": "hd", "caption": "false", "licensedContent": true, "contentRating": {}, "projection": "rectangular" }, "statistics": { "viewCount": "1234567890", "likeCount": "12345678", "favoriteCount": "0", "commentCount": "2345678" } } ], "pageInfo": { "totalResults": 200, "resultsPerPage": 50 }, "nextPageToken": "..." } ``` ### 6.2 字段可用性说明 | 字段路径 | 数据类型 | 说明 | |----------|----------|------| | `id` | string | 视频唯一 ID | | `snippet.title` | string | 视频标题 | | `snippet.description` | string | 视频描述 | | `snippet.channelId` | string | 频道 ID | | `snippet.channelTitle` | string | 频道名称 | | `snippet.publishedAt` | ISO 8601 | 发布时间 | | `snippet.thumbnails.high.url` | string | 高清缩略图 URL | | `snippet.tags` | array | 标签列表 (可能为空) | | `snippet.categoryId` | string | 分类 ID | | `statistics.viewCount` | string | 观看次数 (字符串数字) | | `statistics.likeCount` | string | 点赞数 (可能缺失) | | `statistics.commentCount` | string | 评论数 (可能缺失) | | `contentDetails.duration` | ISO 8601 | 视频时长 (PT#M#S) | | `pageInfo.totalResults` | integer | 该 chart/region 的总结果数 (通常 ≈200) | | `nextPageToken` | string | 下一页令牌 | > ⚠️ `likeCount` 和 `commentCount` 可能因视频设置(关闭评论/隐藏点赞)而缺失,抽取时必须做默认值处理。 --- ## 7. 验证结论 (Summary) | 验证项 | 结果 | |--------|------| | API 端点可用性 | ✅ 稳定可用 | | `chart=mostPopular` 参数 | ✅ 有效,1 unit | | API Key 认证 (无需 OAuth) | ✅ 已验证 | | 每日配额 10,000 | ✅ 官方默认值 | | 9 个目标地区支持 | ✅ 全部支持 | | 4 个目标分类支持 | ✅ 全部支持 | | 错误码 429/403/404 | ✅ 行为已确认 | | Python `requests` 可行性 | ✅ 完全可行 | | JSON/CSV 导出 | ✅ 完全可行 | --- ## 8. 参考来源 - [YouTube Data API (v3) - Quota Usage - Google Developers](https://developers.google.com/youtube/v3/getting-started#quota) - [YouTube Data API - Determine Quota Cost](https://developers.google.com/youtube/v3/determine_quota_cost) - [YouTube Data API - videos.list](https://developers.google.com/youtube/v3/docs/videos/list) - [YouTube Data API - videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list) - [Stack Overflow: YouTube API v3 video category IDs](https://stackoverflow.com/questions/17698040/youtube-api-v3-where-can-i-find-a-list-of-each-videocategoryid) - [Mixed Analytics: List of YouTube Video Category IDs](https://mixedanalytics.com/blog/list-of-youtube-video-category-ids/) - [Dev.to: Multi-Region Video Discovery with YouTube Data API](https://dev.to/ahmet_gedik778845/multi-region-video-discovery-with-youtube-data-api-3o5o)