ouTube Data API v3 视频详情接口（videos.list）完整介绍与标准 JSON 返回示例

一、接口简介

YouTube Data API v3videos.list是官方获取单 / 多条视频完整详情的标准接口。 鉴权方式：公开数据使用API Key；私有视频、评论、字幕需 OAuth2.0；通过id参数传入视频 ID 查询，part参数按需指定返回片段（snippet/contentDetails/statistics），统一返回标准 JSON 结构，用于海外短视频数据分析、创作者监控、竞品调研、内容素材采集等场景Google for Developers。

二、主流业务实战场景

  1. 海外博主数据监测：定时抓取达人视频播放、点赞、评论数据，评估账号流量变现能力
  2. 竞品海外内容分析：提取竞品视频标题、标签、时长、简介，拆解爆款选题逻辑
  3. 品牌海外舆情监控：批量检索品牌相关视频，统计用户互动与口碑倾向
  4. 短视频素材聚合工具：获取视频多尺寸封面、标题文案，用于内容聚合展示
  5. 行业趋势数据分析：按分类统计播放量、互动率，输出海外内容行业报表

三、标准完整 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

{ "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

{ "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

{ "kind": "youtube#videoListResponse", "etag": "\"xxx\"", "pageInfo": { "totalResults": 0, "resultsPerPage": 0 }, "items": [] }

4. 请求参数缺失 400 badRequest

{ "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#videoListResponse
  • items：视频数据数组，单条视频封装为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/sd
  • caption：是否自带字幕

4. statistics（互动数据核心）

  • viewCount：播放总量（字符串类型，需转数字计算）
  • likeCount：点赞数
  • commentCount：评论总数

六、开发使用注意事项

  1. part参数按需填写，只拉取需要片段减少配额消耗；
  2. 播放、点赞等数值为字符串，代码必须转整型避免计算报错；
  3. 接口存在每日配额（默认 10000 单位），批量采集需做缓存、限流；
  4. 时间字段为 UTC 时区，业务展示需手动转换本地时区；
  5. 无权限、下架视频会返回空 items 数组，需单独做空数组判断；
  6. 仅可用于合规数据分析，禁止批量爬取、商用倒卖平台原始视频数据。