此页面由 Cloud Translation API 翻译。

API Reference

通过 YouTube 数据 API，您可以将通常在 YouTube 网站上执行的函数整合到自己的网站或应用中。以下列表指出了您可以使用 API 检索的不同资源类型。该 API 还支持插入、更新或删除其中许多资源的方法。

本参考指南介绍了如何使用该 API 执行所有这些操作。本指南按资源类型组织整理。资源代表 YouTube 体验中所包含的一类内容，例如视频、播放列表或订阅。本指南针对每种资源类型列出了一种或多种数据表示法，资源以 JSON 对象的形式表示。本指南还针对每种资源类型列出了一种或多种支持的方法（LIST、POST、DELETE 等），并说明了如何在您的应用中使用这些方法。

调用 API

以下要求适用于 YouTube Data API 请求：

每个请求都必须指定一个 API 密钥（通过 key 参数）或提供 OAuth 2.0 令牌。您可以在 Developer Console 的 API 访问权限窗格中找到您项目的 API 密钥。
您必须为每个插入、更新和删除请求发送授权令牌。对于任何要检索经身份验证用户的私有数据的请求，您还必须发送授权令牌。

此外，某些用于检索资源的 API 方法可能支持需要授权的参数，或者在请求获得授权时可能包含其他元数据。例如，如果请求获得了某个用户所上传视频的授权，那么其中也可能包含私有视频。
该 API 支持 OAuth 2.0 身份验证协议。您可以通过以下任一方式提供 OAuth 2.0 令牌：
- 请使用如下所示的 access_token 查询参数：?access_token=oauth2-token
- 请使用 HTTP Authorization 标头，例如：Authorization: Bearer oauth2-token
有关在应用中实现 OAuth 2.0 身份验证的完整说明，请参阅身份验证指南。

资源类型

activity

activity 资源包含特定频道或用户在 YouTube 上执行的操作的相关信息。活动供稿中报告的操作包括对视频评分、共享视频、将视频标记为收藏、上传视频等。每个 activity 资源都标识了操作类型、与操作相关联的频道以及与操作相关联的资源，例如已评分或上传的视频。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /activities`	返回符合请求条件的渠道活动事件列表。例如，您可以检索与特定频道或用户自己的频道相关联的事件。
`insert`	`POST /activities`	注意：此方法已弃用，不再受支持。

字幕

caption 资源表示 YouTube 字幕轨道。字幕轨道只能与一个 YouTube 视频相关联。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`delete`	`DELETE /captions`	删除指定的字幕轨道。
`download`	`GET /captions/id`	下载字幕轨道。除非请求指定了 `tfmt` 参数的值，否则字幕轨道将以原始格式返回，并且以原始语言显示（除非请求指定了 `tlang` 参数的值）。
`insert`	`POST /captions`	上传字幕轨。
`list`	`GET /captions`	返回与指定视频相关联的字幕轨道列表。请注意，API 响应不包含实际字幕，并且 `captions.download` 方法能够检索字幕轨道。
`update`	`PUT /captions`	更新字幕轨道。更新字幕轨道时，您可以更改轨道的草稿状态和/或上传新的字幕文件。

ChannelBanners

channelBanner 资源包含的网址可用于将新上传的图片设置为频道的横幅图片。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法 HTTP 请求说明

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`insert`	`POST /channelBanners/insert`	将频道横幅图片上传到 YouTube。此方法代表更新频道横幅图片的三步流程的前两个步骤：调用 `channelBanners.insert` 方法，将二进制图片数据上传到 YouTube。图片的宽高比必须为 16:9，且至少为 2048x1152 像素。我们建议您上传一张 2560x1440 像素的图片。从 API 针对第 1 步返回的响应中提取 `url` 属性的值。调用 `channels.update` 方法来更新频道的品牌信息设置。将 `brandingSettings.image.bannerExternalUrl` 属性的值设为在第 2 步中获得的网址。

相对于 https://www.googleapis.com/youtube/v3 的 URI

insert

POST /channelBanners/insert

将频道横幅图片上传到 YouTube。此方法代表更新频道横幅图片的三步流程的前两个步骤：

调用 channelBanners.insert 方法，将二进制图片数据上传到 YouTube。图片的宽高比必须为 16:9，且至少为 2048x1152 像素。我们建议您上传一张 2560x1440 像素的图片。
从 API 针对第 1 步返回的响应中提取 url 属性的值。
调用 channels.update 方法来更新频道的品牌信息设置。将 brandingSettings.image.bannerExternalUrl 属性的值设为在第 2 步中获得的网址。

ChannelSections

channelSection 资源包含频道选择推介的一组视频的相关信息。例如，一个版块可以展示频道最新上传的视频、最热门的上传视频，或者一个或多个播放列表中的视频。

请注意，只有当频道以浏览视图（而不是 Feed 视图）显示内容时，频道的版块才会显示。要让频道在浏览视图中显示内容，请将指定频道的 brandingSettings.channel.showBrowseView 属性设置为 true。

一个频道最多可以创建 10 个搁架。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`delete`	`DELETE /channelSections`	删除频道版块。
`insert`	`POST /channelSections`	向已通过身份验证的用户的频道添加频道部分。一个频道最多可以创建 10 个搁架。
`list`	`GET /channelSections`	返回符合 API 请求条件的 `channelSection` 资源列表。
`update`	`PUT /channelSections`	更新频道版块。

频道

channel 资源包含有关 YouTube 频道的信息。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /channels`	返回符合请求条件的零个或多个 `channel` 资源的集合。
`update`	`PUT /channels`	更新频道的元数据。请注意，此方法目前仅支持更新 `channel` 资源的 `brandingSettings` 和 `invideoPromotion` 对象及其子属性。

CommentThreads

commentThread 资源包含有关 YouTube 评论会话的信息，其中包括一条顶级评论和对该评论的回复（如果有）。commentThread 资源可以表示关于视频或频道的评论。

顶层评论和回复实际上是嵌套在 commentThread 资源中的 comment 资源。commentThread 资源不一定包含对评论的所有回复，并且如果您想检索特定评论的所有回复，则需要使用 comments.list 方法。另请注意，有些评论没有回复。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /commentThreads`	返回与 API 请求参数匹配的评论线程列表。
`insert`	`POST /commentThreads`	创建新的顶级评论。如需向现有评论添加回复，请改用 `comments.insert` 方法。

注释

comment 资源包含一条 YouTube 评论的相关信息。comment 资源可以表示关于视频或频道的评论。此外，评论可以是顶级评论，也可以是对顶级评论的回复。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /comments`	返回与 API 请求参数匹配的注释列表。
`setModerationStatus`	`POST /comments/setModerationStatus`	设置一条或多条评论的审核状态。该 API 请求必须获得与评论相关联的频道或视频的所有者授权。
`insert`	`POST /comments`	创建对现有评论的回复。注意：如需创建顶级评论，请使用 `commentThreads.insert` 方法。
`markAsSpam`	`POST /comments/markAsSpam`	注意：此方法已弃用，不再受支持。
`delete`	`DELETE /comments`	删除评论。
`update`	`PUT /comments`	修改评论。

GuideCategories

guideCategory 资源用于标识 YouTube 根据频道的内容或其他指标（例如频道的热门程度）通过算法指定的类别。该列表与视频类别类似，不同之处在于视频上传者可以指定视频类别，但只有 YouTube 可以指定频道类别。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /guideCategories`	返回可与 YouTube 频道相关联的类别列表。

I18nLanguages

i18nLanguage 资源用于标识 YouTube 网站支持的应用语言。应用语言也可称为界面语言。对于 YouTube 网站，系统会根据 Google 帐号设置、浏览器语言或 IP 位置自动选择应用语言。用户也可以从 YouTube 网站页脚中手动选择所需的界面语言。

每个 i18nLanguage 资源都标识一个语言代码和名称。调用 videoCategories.list 和 guideCategories.list 等 API 方法时，语言代码可用作 hl 参数的值。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /i18nLanguages`	返回 YouTube 网站支持的应用语言列表。

I18nRegions

i18nRegion 资源用于标识 YouTube 用户可以选为首选内容区域的地理区域。内容区域也可称为内容语言区域。对于 YouTube 网站，系统可以根据 YouTube 域或用户的 IP 位置等启发法自动选择内容区域。用户也可以从 YouTube 网站页脚中手动选择所需的内容区域。

每个 i18nRegion 资源都标识一个地区代码和名称。调用 search.list、videos.list、activities.list 和 videoCategories.list 等 API 方法时，可将区号用作 regionCode 参数的值。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /i18nRegions`	返回 YouTube 网站支持的内容区域列表。

成员

member 资源表示 YouTube 频道的频道会员。会员可定期向创作者提供资金支持，并获享特别福利。例如，当创作者为聊天开启会员专享模式时，会员就可以聊天。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /members`	列出频道的成员（以前称为“赞助者”）。该 API 请求必须获得频道所有者的授权。

MembershipsLevels

membershipsLevel 资源用于标识授权 API 请求的创建者的价格级别。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /membershipsLevels`	返回授权了 API 请求的渠道拥有的零个或多个 `membershipsLevel` 资源集合。关卡按隐式显示顺序返回。

PlaylistItems

playlistItem 资源用于标识播放列表中包含的其他资源，例如视频。此外，playlistItem 资源还包含所含资源的详细信息，这些资源与资源在该播放列表中的使用方式相关。

YouTube 还使用播放列表来标识频道的已上传视频列表，其中列表中的每个 playlistItem 表示一个上传的视频。您可以从给定频道的 channel resource 中检索该列表的播放列表 ID。然后，您可以对该列表使用 playlistItems.list 方法。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`delete`	`DELETE /playlistItems`	删除播放列表项。
`insert`	`POST /playlistItems`	将资源添加到播放列表中。
`list`	`GET /playlistItems`	返回与 API 请求参数匹配的播放列表项集合。您可以检索指定播放列表中的所有播放列表项目，也可以按唯一 ID 检索一个或多个播放列表项目。
`update`	`PUT /playlistItems`	修改播放列表项。例如，您可以更新内容在播放列表中的位置。

播放列表

playlist 资源表示 YouTube 播放列表。播放列表是可以连续观看并与其他用户分享的视频集合。一个播放列表最多可以包含 200 个视频，YouTube 对每位用户创建的播放列表数量没有限制。默认情况下，播放列表会向其他用户公开显示，但播放列表可以是公开或私享的。

YouTube 还会使用播放列表来标识频道的特殊视频集，例如：

已上传的视频
好评如潮（赞过）的视频
观看记录
稍后观看

更具体地说，这些列表与频道相关联，频道集合了个人、群组或公司的视频、播放列表和其他 YouTube 信息。您可以从指定频道的 channel resource 中检索每个列表的播放列表 ID。

然后，您可以使用 playlistItems.list 方法来检索其中的任何列表。您还可以通过调用 playlistItems.insert 和 playlistItems.delete 方法，在这些列表中添加或移除项。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`delete`	`DELETE /playlists`	删除播放列表。
`list`	`GET /playlists`	返回与 API 请求参数匹配的播放列表集合。例如，您可以检索已验证用户拥有的所有播放列表，也可以按唯一 ID 检索一个或多个播放列表。
`insert`	`POST /playlists`	创建播放列表。
`update`	`PUT /playlists`	修改播放列表。例如，您可以更改播放列表的标题、说明或隐私状态。

搜索

搜索结果包含与 API 请求中指定的搜索参数匹配的 YouTube 视频、频道或播放列表的相关信息。虽然搜索结果指向可唯一标识的资源（例如视频），但它自身没有持久性数据。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /search`	返回与 API 请求中指定的查询参数匹配的搜索结果集合。默认情况下，搜索结果集会标识匹配的 `video`、`channel` 和 `playlist` 资源，但您也可以将查询配置为仅检索特定类型的资源。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`delete`	`DELETE /subscriptions`	删除订阅。
`insert`	`POST /subscriptions`	为经过身份验证的用户的频道添加订阅。
`list`	`GET /subscriptions`	返回符合 API 请求条件的订阅资源。

缩略图

thumbnail 资源用于标识与资源相关联的不同缩略图大小。请注意缩略图的以下特征：

资源的 snippet.thumbnails 属性是一个对象，用于标识该资源可用的缩略图。
thumbnail 资源包含一系列对象。每个对象的名称（default、medium、high 等）均引用缩略图图片的大小。
不同类型的资源可能支持不同的缩略图大小。
不同类型的资源可以为同名的缩略图定义不同的尺寸。例如，video 资源的 default 缩略图通常为 120 x 90 像素，而 channel 资源的 default 缩略图通常为 88 x 88 像素。
同一类型的资源对于某些图片，可能仍然具有不同的缩略图大小，具体取决于原始图片或上传到 YouTube 的内容的分辨率。例如，与非高清视频相比，高清视频可能支持的缩略图分辨率更高。
每个包含缩略图大小相关信息的对象都有一个 width 属性和 height 属性。但是，系统可能不会返回该图片的宽度和高度属性。
如果上传的缩略图不符合要求的尺寸，系统会调整其大小以匹配正确的尺寸，而不改变其宽高比。图片未剪裁，但可能包含黑条以确保大小正确。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`set`	`POST /thumbnails/set`	将自定义视频缩略图上传到 YouTube 并为视频设置该缩略图。

VideoAbuseReportReasons

videoAbuseReportReason 资源包含有关视频因包含侮辱性内容而遭到举报的原因的信息。当您的应用调用 videos.reportAbuse 方法来举报滥用视频时，该请求会使用 videoAbuseReportReason 资源中的信息来确定视频被举报的原因。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /videoAbuseReportReasons`	检索可用于举报侮辱性视频的原因列表。

VideoCategories

videoCategory 资源用于标识已与上传的视频相关联的类别。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`list`	`GET /videoCategories`	返回可与 YouTube 视频相关联的类别列表。

视频

video 资源表示 YouTube 视频。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`insert`	`POST /videos`	将视频上传到 YouTube，并可选择设置视频的元数据。
`list`	`GET /videos`	返回与 API 请求参数匹配的视频列表。
`delete`	`DELETE /videos`	删除 YouTube 视频。
`update`	`PUT /videos`	更新视频的元数据。
`rate`	`POST /videos/rate`	为视频添加“顶”或“踩”评分，或者删除视频的评分。
`getRating`	`GET /videos/getRating`	检索授权用户对指定视频列表的评分。
`reportAbuse`	`POST /videos/reportAbuse`	举报包含侮辱性内容的视频。

水印

watermark 资源用于标识在指定频道的视频播放期间显示的图片。您还可以指定图片要关联的目标频道以及时间详情，以确定水印何时在视频播放期间出现以及显示的时间长度。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法	HTTP 请求	说明
相对于 `https://www.googleapis.com/youtube/v3` 的 URI
`set`	`POST /watermarks/set`	将水印图片上传到 YouTube 并为频道设置水印。
`unset`	`POST /watermarks/unset`	删除频道的水印图片。