YouTube Data API v3 videos.list 视频详情接口技术解析｜标准 JSON 返回参考
一、接口基础说明
基础信息
接口名称：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 代码
