当前位置：首页 > news >正文

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

news 2026/6/26 6:23:19

一、接口简介

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

二、主流业务实战场景

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

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