YouTube 开发者 API调用手册

按频道 Handle 读取资料

把 @Handle 转为频道 ID,并读取频道简介与公开统计。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 启用 API 并有项目 API Key;本场景不读取所有者私有频道数据。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

YOUTUBE_API_KEY
在启用 YouTube Data API v3 的 Google Cloud 项目中创建的 API Key;按调用环境限制 Key。
终端
export YOUTUBE_API_KEY='replace_with_your_restricted_api_key'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    在 Google Cloud 控制台创建或选择项目,进入 APIs & Services → Library,启用 YouTube Data API v3。

  2. 02

    在 Credentials → Create credentials → API key 创建 Key;将 API restrictions 设为 YouTube Data API v3,并按自己的服务端 IP 或前端来源配置应用限制。

  3. 03

    将 Key 放入自己的本地或服务端 YOUTUBE_API_KEY。以下是公开资料读取,不需要频道用户 OAuth,也不能据此读取私有数据。

  4. 04

    示例 Handle 是虚构值 example-handle;从频道地址 youtube.com/@xxx 取出 xxx,编辑请求里的 forHandle。

调用 01

按 Handle 查频道

本例只使用 forHandle 一种筛选,不同时混入 id 或 mine。

GEThttps://www.googleapis.com/youtube/v3/channels?part=snippet%2Cstatistics%2CcontentDetails&forHandle=example-handle&key=${YOUTUBE_API_KEY}

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
partQuerystring必填本例请求 snippet、statistics、contentDetails。
forHandleQuerystring必填频道 Handle,可带 @;本例不带 @。请替换虚构值。
keyQuerystring必填项目 API Key。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://www.googleapis.com/youtube/v3/channels?part=snippet%2Cstatistics%2CcontentDetails&forHandle=example-handle&key=${YOUTUBE_API_KEY}"
Python 3
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/channels?part=snippet%2Cstatistics%2CcontentDetails&forHandle=example-handle&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
// 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/channels?part=snippet%2Cstatistics%2CcontentDetails&forHandle=example-handle&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[].id;contentDetails.relatedPlaylists.uploads 是上传列表 ID,并非视频 ID。 以下为结构示意,非本站实测结果。

JSON
{
  "kind": "youtube#channelListResponse",
  "items": [
    {
      "id": "UCexamplechannel00000000",
      "snippet": {
        "title": "示例频道",
        "description": "虚构的频道资料示意"
      },
      "statistics": {
        "viewCount": "10000",
        "subscriberCount": "1200",
        "hiddenSubscriberCount": false,
        "videoCount": "20"
      },
      "contentDetails": {
        "relatedPlaylists": {
          "uploads": "UUexamplechannel00000000"
        }
      }
    }
  ]
}

常见错误与排查

HTTP 403 quotaExceeded项目的相应配额已耗尽。
查看 Google Cloud 的 YouTube Data API 配额页,分清 Search Queries 与其他端点额度;减少轮询或申请额度。
HTTP 403 forbidden请求没有适当授权。
确认 API 已启用、Key 的 API/应用限制正确;需要私有数据时必须改用用户 OAuth,不能拿 API Key 代替。
HTTP 400 invalidCriteria频道筛选条件不符合要求。
forHandle、id、forUsername、mine 等仅选择一种;mine 还要求用户授权。

调用注意

  • 每次调用为其他端点配额桶的 1 单位;读不到频道时先核对 Handle,不能把空结果当作订阅数为零。
  • subscriberCount 按官方规则向下保留三位有效数字;它不是精确后台订阅数。检查 hiddenSubscriberCount 和字段是否存在。
  • 需要可靠列出频道上传视频时,以 uploads 播放列表配合 playlistItems.list;不能用搜索页冒充完整上传记录。

注意事项

  • 本页使用项目 API 配额,不提供购买配额的结算接口;申请提升额度可能需要合规审核,不承诺自动批准。
  • 默认配额目前分为每天 100 次 search.list、100 次 videos.insert,其他端点共用每天 10,000 单位;以实际项目控制台为准。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    channels.list核验日期 2026-10-15
  3. 03
    频道字段与订阅数精度核验日期 2026-10-15
  4. 04
    Data API 通用错误核验日期 2026-10-15

YouTube 开发者 API的其他调用手册

← 返回YouTube 开发者 API的全部功能