YouTube Data API v3 视频详情接口（videos.list）完整介绍与标准 JSON 返回示例
一、接口简介
YouTube Data API v3
videos.list 是官方获取单 / 多条视频完整详情的标准接口鉴权方式：公开数据使用 API Key；私有视频、评论、字幕需 OAuth2.0；通过 id 参数传入视频 ID 查询，part 参数按需指定返回片段（snippet/contentDetails/statistics），统一返回标准 JSON 结构，用于海外短视频数据分析、创作者监控、竞品调研、内容素材采集等场景Google for Developers。二、主流业务实战场景
海外博主数据监测：定时抓取达人视频播放、点赞、评论数据，评估账号流量变现能力
竞品海外内容分析：提取竞品视频标题、标签、时长、简介，拆解爆款选题逻辑
品牌海外舆情监控：批量检索品牌相关视频，统计用户互动与口碑倾向
短视频素材聚合工具：获取视频多尺寸封面、标题文案，用于内容聚合展示
行业趋势数据分析：按分类统计播放量、互动率，输出海外内容行业报表
三、标准完整 JSON 返回（正常成功示例，官方原生结构）
json
{
"kind": "youtube#videoListResponse",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/XwZ123abcDEF456\"",
"pageInfo": {
"totalResults": 1,
"resultsPerPage": 1
},
"items": [
{
"kind": "youtube#video",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
"id": "7lCDEYXw3mM",
"snippet": {
"publishedAt": "2012-06-20T22:45:24.000Z",
"channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"title": "Google I/O 101: Q&A On Using Google APIs",
"description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
"thumbnails": {
"default": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg",
"width": 120,
"height": 90
},
"medium": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg",
"width": 320,
"height": 180
},
"high": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg",
"width": 480,
"height": 360
}
},
"channelTitle": "Google Developers",
"tags": ["Google API", "OAuth2", "Google I/O", "开发教程"],
"categoryId": "28",
"liveBroadcastContent": "none"
},
"contentDetails": {
"duration": "PT1H23M12S",
"dimension": "2d",
"definition": "hd",
"caption": "true",
"licensedContent": true
},
"statistics": {
"viewCount": "158907",
"likeCount": "5947",
"favoriteCount": "0",
"commentCount": "241"
}
}
]}四、高频异常错误 JSON 示例
1. 每日配额耗尽 403 quotaExceeded
json
{
"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"
}
],
"status": "PERMISSION_DENIED"
}}2. API Key 无效 / 未开启接口 403 forbidden
json
{
"error": {
"code": 403,
"message": "API key not valid. Please pass a valid API key.",
"errors": [
{
"message": "API key not valid. Please pass a valid API key.",
"domain": "usageLimits",
"reason": "keyInvalid"
}
],
"status": "PERMISSION_DENIED"
}}3. 视频 ID 不存在 / 视频已下架 404 notFound
json
{
"kind": "youtube#videoListResponse",
"etag": "\"xxx\"",
"pageInfo": {
"totalResults": 0,
"resultsPerPage": 0
},
"items": []}4. 请求参数缺失 400 badRequest
json
{
"error": {
"code": 400,
"message": "Missing required parameter: id",
"errors": [
{
"message": "Missing required parameter: id",
"domain": "global",
"reason": "missingParameter",
"location": "parameter",
"locationType": "query"
}
],
"status": "INVALID_ARGUMENT"
}}五、核心字段极简说明
1. 顶层公共结构
kind：资源类型固定youtube#videoListResponseitems：视频数据数组，单条视频封装为youtube#video对象pageInfo：分页统计总数与每页条数
2. snippet（基础元信息）
id：视频唯一 VID，查询主键title/description：视频标题、简介文案publishedAt：ISO 标准 UTC 发布时间channelId/channelTitle：创作者频道 ID 与频道名thumbnails：多分辨率封面图地址tags：视频标签数组，用于内容归类分析
3. contentDetails（视频媒体属性）
duration：时长 ISO 格式（PT1H23M12S=1 小时 23 分 12 秒）definition：清晰度 hd/sdcaption：是否自带字幕
4. statistics（互动数据核心）
viewCount：播放总量（字符串类型，需转数字计算）likeCount：点赞数commentCount：评论总数
六、开发使用注意事项
part参数按需填写，只拉取需要片段减少配额消耗；播放、点赞等数值为字符串，代码必须转整型避免计算报错；
接口存在每日配额（默认 10000 单位），批量采集需做缓存、限流；
时间字段为 UTC 时区，业务展示需手动转换本地时区；
无权限、下架视频会返回空 items 数组，需单独做空数组判断；
仅可用于合规数据分析，禁止批量爬取、商用倒卖平台原始视频数据。
