如何获取 YouTube API Key（YouTube Data API v3）并发出第一次请求

YouTube API Key 是让你的代码读取 YouTube 公开数据的凭据：视频详情、频道统计、搜索结果、播放列表内容。Google 的文档说得很直接：“不提供 OAuth 2.0 token 的请求必须发送 API Key。该 Key 用于标识你的项目，并提供 API 访问、配额和报告。”没有 Key，就没有数据。

本指南带你从空的 Google Cloud 项目开始，大约十五分钟后跑通第一个可用的请求。你将启用 YouTube Data API v3、创建 Key、限制其使用范围、用 curl 和 Python 调用 API，然后把 Key 存到 Apifox 中，并把这次调用保存为可重复执行的测试。如果你想先了解整体情况，我们的 YouTube Data API 概览文章介绍了该 API 的覆盖范围；本文是动手实践的部分。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始前的准备

• 一个 Google 账号。用它就能打开 Cloud 控制台并创建项目。
• curl（macOS 和大多数 Linux 发行版自带）以及 Python 3 和 requests 包，用于运行代码示例。
• Apifox，如果你想把 Key 作为密钥保存，并把请求保存为测试。免费版足以覆盖本文所有内容。

第 1 步：创建 Google Cloud 项目

打开 Google Cloud 控制台并登录。使用页面顶部的项目选择器创建一个新项目，例如 youtube-integration。你之后看到的每个 API Key、配额桶和使用报告都归属于这个项目，因此建议每个应用一个项目，而不是让互不相关的工具共用一个 Key。如果该应用已经有项目，就直接用那个项目。

第 2 步：启用 YouTube Data API v3

新项目中 API 默认是关闭的。在控制台中进入 APIs & Services，打开 API Library，搜索 “YouTube Data API v3” 并启用它。Google 的入门指南从另一个方向描述了同样的检查：访问 Enabled APIs 页面，如果该 API 不在列表中，就启用它。

跳过这一步，你的第一个请求就会以 403 失败，提示该 API 未在项目中使用或已被禁用。这是全新的 Key “不生效” 最常见的原因。

第 3 步：创建 API Key

进入 APIs & Services，然后进入 Credentials。点击 Create credentials 并选择 API key。控制台会立即生成 Key 并在对话框中显示，把它复制到安全的地方。

把 Key 当作密码看待。不要把它粘贴到 Git 仓库、Slack 会话或客户端 JavaScript 包中。如果它已经混进了某次提交，我们的《发现并修复泄露的 API Key》指南介绍了清理方法。

第 4 步：限制 Key

Google 自己的文档写道：“不受限制的 API Key 是不安全的。”创建完成后立刻点击 Restrict key。你会看到两个相互独立的控制项，Cloud API keys 指南中有说明：

• 应用限制（Application restrictions）决定谁可以携带这个 Key。任选其一：网站（HTTP referrer，支持有限通配符）、IP 地址（IPv4、IPv6 或 CIDR 网段）、Android 应用（包名加 SHA-1 证书指纹）或 iOS 应用（bundle ID）。后端服务应使用 IP 地址，只在浏览器中运行的组件应使用 referrer。
• API 限制（API restrictions）决定这个 Key 可以调用哪些 API。选择 “Restrict key”，只勾选 YouTube Data API v3。这样即使 Key 泄露，攻击者也只能用掉 YouTube 的配额，拿不到其他东西。

保存后等几分钟让改动生效再测试。同一份指南还给了两个习惯：定期轮换 Key，以限制某个 Key 泄露后造成的损失；当所有调用方都迁移到新 Key 之后，删除旧 Key。下一步还有一个坑：如果你按 IP 把 Key 限制到自己的服务器，那么从笔记本发起的 curl 就会被拦截，这时要么在允许的主机上测试，要么单独创建一个开发用 Key。

第 5 步：用 curl 和 Python 发起第一个请求

所有接口都挂在 https://www.googleapis.com/youtube/v3/ 之下。可以把 Key 作为 key query 参数传入（Google 自己的示例就是这样做的），也可以放在 x-goog-api-key header 中，后者能让它不出现在 URL 和访问日志里。两种方式在线上 API 中都能用。

先从 videos.list 开始，这是最省配额的有用调用：它返回一个或多个视频 ID 的详情，消耗 1 个配额单位。下面的 ID 就是 Google 文档中使用的那个。

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

裁剪后的响应大致如下：

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

part 参数是必填的，它决定返回哪些部分；snippet、statistics、contentDetails 和 status 是你最常用的几个。

接下来是搜索，这是大多数人真正想要的调用。用 Python 的 requests 实现：

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

对于 search.list，part 必须是 snippet，maxResults 默认为 5，可取值 0 到 50，type 默认为 video,channel,playlist，所以如果你只想要视频，就把它设为 video。搜索结果的 videoId 位于 id 内部，而不是顶层，这就是上面循环读取 item["id"]["videoId"] 的原因。

第 6 步：在 Apifox 中保存 Key 并运行请求

Shell 变量对单个脚本够用，但对团队不行，也无法给你一个已保存、可重复运行的检查。下面是在 Apifox 中的同一个请求，Key 不会上传到云端。

1. 创建环境。新建一个名为 YouTube 的环境，包含两个变量：base_url 设为 https://www.googleapis.com/youtube/v3，以及 youtube_api_key。对于 Key，把共享值留作占位符，把真实 Key 粘贴到本地值字段。本地值保存在你客户端的缓存中，永远不会同步给队友；完整的设置见我们的 Apifox 环境与密钥变量指南。
2. 构建请求。新建请求，GET {{base_url}}/videos，query 参数 part=snippet,statistics 和 id=7lCDEYXw3mM，并添加 header x-goog-api-key，值为 {{youtube_api_key}}。选择 YouTube 环境并发送。你应该会看到与 curl 调用相同的 JSON。
3. 把它变成测试。在请求的后置处理器中添加断言：状态码等于 200，且 $.items[0].id 等于 7lCDEYXw3mM。保存请求并把它加入测试场景。这个检查现在可以按需运行、定时运行，或通过 Apifox CLI 在 CI 中运行，其中 --env-var "youtube_api_key=$YOUTUBE_API_KEY" 会在运行时注入 Key，而不需要存储它。

第一次轮换 Key 或修改限制时就能体会到它的价值：重跑一个测试场景，几秒内就能知道每个 YouTube 调用是否仍然正常。

配额与限制

YouTube Data API 不以美元计费，而是以配额单位计费，这些数字来自 Google 的配额计算器页面。每个启用该 API 的项目都会获得以下默认额度：

在共享的 10,000 单位额度池中，videos.list、channels.list、playlistItems.list、commentThreads.list 这类 list 方法每次消耗 1 个单位。写操作更贵：videos.update 和 videos.delete 是 50 个单位，captions.insert 是 400 个。同一页面上的四条规则决定了你应该如何围绕它做设计：

• 配额在太平洋时间午夜重置。
• 每个请求，包括无效请求，都至少消耗 1 个单位。反复重试一个错误调用的循环只会白白烧掉配额。
• 分页结果中每多取一页，消耗与第一页相同。
• 默认额度“可能随时调整”。在规划容量之前，请查看该页面，而不是某篇教程。

较早的指南会把一次搜索算作 10,000 额度池中的 100 个单位。当前页面把 search.list 放在独立配额桶中，所以上限仍然是每天 100 次搜索，但搜索不再占用其他调用的配额。

如果这还不够用，配额与合规审计页面会指引你填写 YouTube API Services Audit and Quota Extension Form。在提交之前，先缓存响应、只请求你需要的 part 值，并把多个 ID 合并到一次 videos.list 调用中（id 参数接受逗号分隔的列表）。用量会显示在 Cloud 控制台的 Quotas 页面。

常见错误及修复方法

Google 的错误参考列出了该 API 自己的 reason 代码。下表前两行来自用错误 Key 和不带 Key 向线上 API 发送真实请求的结果。

还有一条来自实践的经验：如果应用限制与调用方不匹配，你会收到 403，其中会指出被拦截的 referrer 或 IP。修正限制，或从允许的主机发起调用。另外注意，较早的论坛帖子把无效 Key 错误称为 keyInvalid；线上 API 返回的是 badRequest，并带有 API_KEY_INVALID 详情，因此请根据消息或详情来匹配，而不是沿用旧的 reason 字符串。

常见问题

YouTube API Key 是免费的吗？

是。创建 Key 不花钱，文档也以配额单位而非金额来计量该 API。上面的默认额度就是你无需申请即可获得的额度。

什么情况下需要 OAuth 而不是 API Key？

API Key 用于标识你的项目并访问公开数据。一旦涉及用户的私有数据，或者需要插入、更新、删除任何内容，Google 就要求提供拥有该数据的用户的 OAuth 2.0 token。给视频评分、列出自己的订阅，或使用 mine=true 过滤，都属于 OAuth 这一侧。我们对 API Key 与 bearer token 的对比解释了为什么这两种凭据回答的是不同的问题。

AI Agent 可以使用我的 YouTube API Key 吗？

可以，只要 Agent 运行在 Key 限制允许的位置。YouTube MCP server 是把视频数据交给编码助手的一种方式；给它一个限制到 Data API 和其所运行机器的 Key，并且不要让 Key 出现在 prompt 里。

Key 泄露了怎么办？

在 Credentials 页面删除它，并创建一个替代 Key。然后修复源头：把 Key 移到 Apifox 的本地值或密钥管理服务中，并扫描仓库，确保旧 Key 没有还留在提交历史里。

下一步

现在你有了一个项目、一个已启用的 API、一个受限的 Key，以及一个在 curl、Python 和 Apifox 中都能正常工作的请求。把保存好的测试场景接入 CI，并让 Quotas 页面告诉你什么时候该做优化。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名