一、接口基础说明
基础信息
- 接口名称：videos.list（YouTube Data API 视频详情查询接口）
- 请求地址：o0b.cn/anzexi
- 请求方式：GET
- 返回格式：标准 JSON
- 鉴权方式：API Key
- 核心入参
- key：Google 云平台创建的 API 密钥
- id：视频唯一 VideoId，单次最多传入 50 个逗号分隔 ID，支持批量查询
- part【必填】：按需指定返回模块（snippet,statistics,contentDetails,status等）
重要说明：part决定返回哪些数据，不要一次性请求全部 part，节约配额（Quota）。
主流业务落地场景
- 海外短视频数据分析系统：批量抓取播放、点赞、评论数据，做网红视频数据监测
- 社媒选品工具：监控 YouTube 带货视频，挖掘爆款商品、热门赛道
- 多语种内容聚合平台：采集视频标题、简介、封面、时长用于站点展示
- MCN 机构数据看板：跟踪旗下创作者视频流量变化
- 竞品舆情监控：检索品牌相关视频，统计互动指标、提取用户评论
二、标准请求示例
GET https://www.googleapis.com/youtube/v3/videos ?id=dQw4w9WgXcQ &part=snippet,statistics,contentDetails,status &key=你的API_KEY
三、标准成功完整 JSON 返回示例
{ "kind": "youtube#videoListResponse", "etag": "\"p4VTdlkQv3HQeTEaXgvLePAydmU/abc123DEF456\"", "pageInfo": { "totalResults": 1, "resultsPerPage": 1 }, "items": [ { "kind": "youtube#video", "etag": "\"p4VTdlkQv3HQeTEaXgvLePAydmU/item01\"", "id": "dQw4w9WgXcQ", "snippet": { "publishedAt": "2009-10-25T06:57:33Z", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)", "description": "The official video for Rick Astley's Never Gonna Give You Up", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg", "width": 120, "height": 90 }, "medium": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg", "width": 320, "height": 180 }, "high": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 480, "height": 360 }, "standard": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg", "width": 640, "height": 480 }, "maxres": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "width": 1280, "height": 720 } }, "channelTitle": "Rick Astley", "tags": [ "Rick Astley", "Never Gonna Give You Up", "pop music" ], "categoryId": "10", "liveBroadcastContent": "none", "localized": { "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)", "description": "The official video for Rick Astley's Never Gonna Give You Up" } }, "contentDetails": { "duration": "PT3M33S", "dimension": "2d", "definition": "hd", "caption": "false", "licensedContent": true, "contentRating": {}, "projection": "rectangular" }, "status": { "uploadStatus": "processed", "privacyStatus": "public", "license": "youtube", "embeddable": true, "publicStatsViewable": true, "madeForKids": false }, "statistics": { "viewCount": "14682956328", "likeCount": "162354211", "favoriteCount": "0", "commentCount": "19743254" } } ] }
四、核心字段释义
外层通用
- items：视频数组，多条批量查询会包含多条对象
- id：VideoId，视频唯一标识
snippet【基础元信息】
- publishedAt：UTC 发布时间
- channelId / channelTitle：创作者频道 ID 与名称
- title / description：视频标题、简介
- thumbnails：多尺寸封面图地址
- tags：视频标签数组
- categoryId：分类 ID
contentDetails【视频素材信息】
- duration：ISO8601 时长格式（PT3M33S = 3 分 33 秒），程序需要自行转换秒数
- definition：清晰度 hd/sd
- embeddable：是否允许外部站点嵌入播放
status【视频状态】
- privacyStatus：public公开 / unlisted不公开 / private私密
- publicStatsViewable：互动数据是否对外可见
statistics【核心互动数据，数据分析必备】
全部为字符串类型，运算务必转为数字
- viewCount：播放量
- likeCount：点赞数
- commentCount：评论总数
五、常见异常 JSON 返回示例
1. API 配额耗尽（403）
{ "error": { "code": 403, "message": "The request cannot be completed because you have exceeded your quota.", "errors": [ { "message": "The request cannot be completed because you have exceeded your quota.", "domain": "youtube.quota", "reason": "quotaExceeded" } ] } }
2. VideoId 不存在、视频删除 / 私密不可见
{ "kind": "youtube#videoListResponse", "etag": "\"xxxx\"", "pageInfo": { "totalResults": 0, "resultsPerPage": 0 }, "items": [] }
3. 缺少必填参数 part（400）
{ "error": { "code": 400, "message": "Required parameter: part", "errors": [ { "message": "Required parameter: part", "domain": "youtube.parameter", "reason": "missingRequiredParameter", "location": "parameters", "locationType": "parameter" } ] } }
六、开发接入关键注意事项
- 数值全部字符串：播放、点赞、评论是 string，直接运算会报错；
- 时长格式转换：PTxxMxxS 需要写工具转换成总秒数；
- 配额（Quota）管控：不同 part 消耗配额不同，仅拉取业务必需模块；
- 被删除、私密、地区限制视频不会出现在 items 数组，业务必须判断items.length == 0；
- 不要高频轮询，建议增加本地缓存，减少 API 调用；
- 禁止绕过规则大规模爬虫采集，仅允许 API 合规调用；
- 接口不返回视频源播放地址，仅提供元数据、封面、互动指标。
七、总结
YouTube Data API v3 videos.list 是官方标准化海外视频元数据接口，通过传入 VideoId 获取标题、封面、时长、播放点赞评论等结构化信息，广泛用于海外社媒数据分析、选品系统、MCN 数据监控。相比网页爬虫，官方接口稳定性强、格式统一，是海外内容数据项目标准对接方案。
如果你需要，我可以额外配套：
- 频道信息接口说明
- 视频搜索接口 search.list 文档 + JSON 样例
- Python 简易调用 Demo 代码
