We are updating the Data API to match how YouTube counts views for Shorts. Learn more

此页面由 Cloud Translation API 翻译。

API Reference

借助 YouTube Data API，您可以将通常在 YouTube 网站上执行的功能集成到自己的网站或应用中。以下列表列出了您可以使用该 API 检索的不同类型的资源。该 API 还支持用于插入、更新或删除许多此类资源的方法。

本参考指南介绍了如何使用该 API 执行所有这些操作。本指南按资源类型进行编排整理。资源表示构成 YouTube 体验的一部分的项类型，例如视频、播放列表或订阅。对于每种资源类型，该指南都会列出一种或多种数据表示形式，并且资源以 JSON 对象的形式表示。该指南还列出了每种资源类型的一个或多个受支持的方法（LIST、POST、DELETE 等），并说明了如何在应用中使用这些方法。

调用 API

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

每个请求都必须指定 API 密钥（使用 key 参数）或提供 OAuth 2.0 令牌。您可以在Play 管理中心的项目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 资源包含有关特定频道或用户在 YouTube 上执行的操作的信息。活动 Feed 中报告的操作包括对视频评分、分享视频、将视频标记为收藏、上传视频等。每个 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 像素。建议上传 2560 x 1440 像素的图片。从 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 像素。建议上传 2560 x 1440 像素的图片。
从 API 针对第 1 步返回的响应中提取 url 属性的值。
调用 channels.update 方法可更新频道的品牌信息设置。将 brandingSettings.image.bannerExternalUrl 属性的值设置为第 2 步中获得的网址。

ChannelSections

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

请注意，只有当频道以浏览视图（而非动态视图）显示内容时，频道的版块才会显示。如需让频道在浏览视图中显示内容，请为指定频道将 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 播放列表。播放列表是一组可按顺序观看并与其他用户分享的视频。默认情况下，播放列表对其他用户是公开的，但播放列表可以是公开的，也可以是私享的。

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`	删除频道的水印图片。