YouTube Data API v3 videos.list 视频详情接口技术解析｜标准 JSON 返回参考

原创

Anzexi58

发布于 2026-07-23 10:11:11

3670

文章被收录于专栏：API接口开发API接口开发

一、接口基础说明

基础信息

接口名称：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 代码

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

api-key

YouTube Data API v3 videos.list 视频详情接口技术解析｜标准 JSON 返回参考

YouTube Data API v3 videos.list 视频详情接口技术解析｜标准 JSON 返回参考

一、接口基础说明

基础信息

主流业务落地场景

二、标准请求示例

三、标准成功完整 JSON 返回示例

四、核心字段释义

外层通用

snippet【基础元信息】

contentDetails【视频素材信息】

status【视频状态】

statistics【核心互动数据，数据分析必备】

五、常见异常 JSON 返回示例

1. API 配额耗尽（403）

2. VideoId 不存在、视频删除 / 私密不可见

3. 缺少必填参数 part（400）

六、开发接入关键注意事项

七、总结

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐