YouTube Data API 免费吗？免费——但你一天大约只有 100 次搜索，不是无限

我认识的一个开发者做了个小项目，给一个小众社区推热门视频。测试时一切正常。上线后那天早上有几百人用，到大约中午 12:30，它突然什么都不返回了——只剩一串 403 错误。他以为自己被限流或者封了。都不是。他把一整天的配额花光了，而且只用了大约一百次请求就花光了，因为这一百次每一次都是搜索。

这就是当别人说「YouTube Data API 是免费的」时没人告诉你的那件事。它确实免费。坑不在钱上。坑在于「免费」附带一个用**单位（units）**计量的固定每日预算，而某一类调用吃掉这个预算的速度是另一类的一百倍。如果你不知道哪些调用贵，你写出来的东西就会在中午挂掉，而你完全不知道为什么。

对，它免费。上限是每天 10,000 单位。

我们把「免费」说清楚，因为大概率把你带到这里的那个搜索词——「youtube data api v3 official free」——是有确切答案的。YouTube Data API v3 没有按次收费。你不用挂结算账户、不用输卡号，你的用量永远不会生成账单。你在 Google Cloud Console 建个项目、打开这个 API、创建一个 key，就能调用。

你拿到的不是账单，而是每个项目每天默认 10,000 个配额单位。每次调用花掉一些单位。当累计达到 10,000，API 返回 403 quotaExceeded，并一直不响应直到配额重置。所以真正要紧的问题不是「免不免费」，而是「10,000 单位能撑多远」——而这完全取决于你调什么。

单位表，以及毁掉所有人一天的那一行

下面是每个常见操作的成本，这些是 2026 年公布的数字。

这张表看一遍，整个配额系统就通了。一次普通 list 调用花 1 单位。搜索花 100。这不是四舍五入的差别——这是同样的预算下，一天 10,000 次读取和一天 100 次搜索的差别。每一次请求，哪怕是返回错误的无效请求，也至少花 1 单位，所以一个对坏调用的重试循环也会悄悄把你抽干。

搜索这么贵，是因为它在做真正的工作：在整个 YouTube 上做排序。Google 故意把它定价成直接查询的 100 倍，就是要把你推向直接查询。而你也确实该这么做。

上传播放列表技巧：把一次 100 单位的搜索变成 2 单位的读取

最常见的浪费配额方式，是用 search.list 去拿一个频道的最新视频——调用 search 并加 channelId 过滤。它能用，而且每次花 100 单位。

但你几乎从不需要它。每个 YouTube 频道都有一个隐藏的「uploads」播放列表，包含它发过的每一个视频，最新在前。拿到它只需两个便宜的调用：

1. channels.list 带 part=contentDetails → 返回该频道的 uploads 播放列表 ID。1 单位。
2. 对那个播放列表 ID 调 playlistItems.list，maxResults=50 → 最新的 50 个上传。1 单位。

两个单位，50 个视频，最新在前。和 search.list 会收你 100 单位的结果一模一样。如果你的应用任何地方显示「这个频道的最新视频」，光这一处替换，就是「中午挂掉」和「再也不用操心配额」之间的差别。通用原则：搜索留给用户自己输入的开放式发现；其他一切都该是对你已经持有的 ID 做 list 调用。

API key 还是 OAuth：你到底需要哪个

两种认证方式，而大家老是拿错那个。

读公开数据，API key 就够了——搜索、列出频道上传、获取公开视频统计、读公开评论。它就是一个附在请求后面的字符串。不用用户登录，不用授权页。这覆盖了绝大多数只读应用。

一旦某个调用关乎某个具体用户、或者要改动什么，你就必须用 OAuth 2.0：上传视频、发表或管理评论、读某人的私密播放列表或订阅、给视频点赞。OAuth 意味着用户登录并授权你的应用，你代表他行事。

让你少踩坑的判断法则：如果一个未登录的访客在 youtube.com 上本来就能看到这数据，API key 就行；如果它需要以某个特定账号登录，就得用 OAuth。在某个调用真的逼你之前，别去碰 OAuth 那套复杂度。

配额什么时候重置，以及怎么拿更多

理解了预算之后，两件实务。

重置按太平洋时间。 你的每日配额在太平洋时间（PT）午夜补满，不是你所在时区的午夜，也不是从你开始用起算的 24 小时。如果你的应用在中午 12:30 用光、而你在欧洲，你可能要等到你那边的第二天早上。批处理任务要按这个时钟来排。

你可以申请更多，而且免费。 如果你已经优化过调用、确实需要超过 10,000 单位——一个有真实用户的真实产品——你提交 YouTube API Services Audit and Quota Extension（审核与配额扩展）表单，入口在 Cloud Console 配额页面。Google 审核你是否符合 API 条款以及你的使用场景；通过要几个工作日，且 Google 不为额外配额收费。但先优化。一个一边把配额全花在本可避免的 search.list 上、一边求着要更多配额的应用，是最容易被拒的那个，往往也是最不需要扩容的那个。

四步上手

1. 打开 Google Cloud Console，建一个项目（或选一个现有的），在「API 和服务」里启用 YouTube Data API v3。
2. 在「凭据」里创建一个 API key。这个 key 立刻就能读所有公开数据。
3. 发出你的第一个调用——列一个频道的上传，别用搜索——并盯着 API 控制台上的配额计量表，搞清楚你真实的调用组合到底花多少。
4. 只有当你需要用户相关的操作（上传、评论、私密数据）时，再去配一个 OAuth 2.0 客户端、加上授权流程。

免费，没错。但这里的「免费」意思是「按单位计量，不是按美元」，而那个应用在午饭时间挂掉的开发者，要是早知道那张表里的一行，本可以做出一个稳如磐石的东西。现在你知道了。