读取视频资料和公开统计
根据已知视频 ID 查询标题、时长和当前可返回的播放、点赞、评论数。
← 返回平台功能接入准备
- 有项目 API Key;目标视频对当前调用身份可见。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
YOUTUBE_API_KEY- 在启用 YouTube Data API v3 的 Google Cloud 项目中创建的 API Key;按调用环境限制 Key。
YOUTUBE_VIDEO_ID- 虚构视频 ID;替换为搜索结果或自己可见视频的 ID。
export YOUTUBE_API_KEY='replace_with_your_restricted_api_key'
export YOUTUBE_VIDEO_ID='EXAMPLE1234'以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。
调用步骤
- 01
在 Google Cloud 控制台创建或选择项目,进入 APIs & Services → Library,启用 YouTube Data API v3。
- 02
在 Credentials → Create credentials → API key 创建 Key;将 API restrictions 设为 YouTube Data API v3,并按自己的服务端 IP 或前端来源配置应用限制。
- 03
将 Key 放入自己的本地或服务端 YOUTUBE_API_KEY。以下是公开资料读取,不需要频道用户 OAuth,也不能据此读取私有数据。
- 04
从搜索结果 id.videoId 或 YouTube watch?v= 后取得视频 ID;把它放入 YOUTUBE_VIDEO_ID,不能填完整视频 URL。
查询视频详情
一次请求补齐 snippet、contentDetails、statistics 三组数据。
https://www.googleapis.com/youtube/v3/videos?part=snippet%2CcontentDetails%2Cstatistics&id=${YOUTUBE_VIDEO_ID}&key=${YOUTUBE_API_KEY}参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
partQuery | string必填 | 逗号分隔的字段组;本例 snippet,contentDetails,statistics。 |
idQuery | string必填 | 本场景按视频 ID 查询;多个 ID 用逗号分隔,需遵守接口数量限制。 |
keyQuery | string必填 | 项目 API Key。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
--request GET \
--url "https://www.googleapis.com/youtube/v3/videos?part=snippet%2CcontentDetails%2Cstatistics&id=${YOUTUBE_VIDEO_ID}&key=${YOUTUBE_API_KEY}"
import json
import os
import re
import urllib.request
import urllib.error
def expand(value):
return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
lambda match: os.environ[match.group(1)], value)
url = expand("https://www.googleapis.com/youtube/v3/videos?part=snippet%2CcontentDetails%2Cstatistics&id=${YOUTUBE_VIDEO_ID}&key=${YOUTUBE_API_KEY}")
headers = {
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
return process.env[name];
});
}
const url = expand("https://www.googleapis.com/youtube/v3/videos?part=snippet%2CcontentDetails%2Cstatistics&id=${YOUTUBE_VIDEO_ID}&key=${YOUTUBE_API_KEY}");
const headers = Object.fromEntries(
Object.entries({}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
method: "GET",
headers,
signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
返回示例
按官方字段整理的响应结构示意,ID、文本和数字均为虚构,非接口实测结果。统计数常以字符串返回;缺失字段不应填零,items 为空时不要虚构视频信息。 以下为结构示意,非本站实测结果。
{
"kind": "youtube#videoListResponse",
"items": [
{
"id": "EXAMPLE1234",
"snippet": {
"title": "示例视频",
"channelId": "UCexamplechannel00000000"
},
"contentDetails": {
"duration": "PT3M20S"
},
"statistics": {
"viewCount": "12345",
"likeCount": "321",
"commentCount": "12"
}
}
]
}常见错误与排查
HTTP 403 quotaExceeded项目的相应配额已耗尽。- 查看 Google Cloud 的 YouTube Data API 配额页,分清 Search Queries 与其他端点额度;减少轮询或申请额度。
HTTP 403 forbidden请求没有适当授权。- 确认 API 已启用、Key 的 API/应用限制正确;需要私有数据时必须改用用户 OAuth,不能拿 API Key 代替。
HTTP 400 incompatibleParameters筛选条件冲突。- id、chart、myRating 等筛选只按接口规则选择;本例只传 id。
调用注意
- 每次调用为其他端点配额桶的 1 单位;先保存视频 ID,再批量补资料比反复搜索更节省搜索额度。
- contentDetails.duration 是 ISO 8601 时长,需自行转换。公开读取不会返回仅限所有者可见的 dislikeCount。
- 播放统计口径会变更;当前官方注明自 2026-08-24 起各视频格式的 viewCount 按开始播放计数,历史序列比较需注意口径。
注意事项
- 本页使用项目 API 配额,不提供购买配额的结算接口;申请提升额度可能需要合规审核,不承诺自动批准。
- 默认配额目前分为每天 100 次 search.list、100 次 videos.insert,其他端点共用每天 10,000 单位;以实际项目控制台为准。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01创建项目、启用 API、申请凭证与当前配额核验日期 2026-10-15
- 02videos.list核验日期 2026-10-15
- 03视频字段与统计口径核验日期 2026-10-15
- 04Data API 通用错误核验日期 2026-10-15
