ouTube 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 返回（正常成功示例，官方原生结构）

复制代码

{
  "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：评论总数

六、开发使用注意事项

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