API Reference

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

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

调用该 API

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

  1. 每个请求都必须指定 API 密钥（通过 key 参数）或提供 OAuth 2.0 令牌。您可以在开发者控制台中项目的 API 访问权限窗格中找到 API 密钥。

  2. 您必须为每个插入、更新和删除请求发送授权令牌。对于检索已通过身份验证的用户的私有数据的任何请求，您还必须发送授权令牌。

    此外，某些用于检索资源的 API 方法可能支持需要授权的参数，或者在请求获得授权时可能包含其他元数据。例如，如果检索用户上传视频的请求经过相应用户的授权，则该请求也可能包含私享视频。

  3. 该 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 返回与请求条件匹配的频道活动事件列表。例如，您可以检索与特定频道或用户自己的频道相关联的事件。

字幕

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 请求 说明
相对于 https://www.googleapis.com/youtube/v3 的 URI
insert POST /channelBanners/insert 将频道横幅图片上传到 YouTube。此方法表示更新频道横幅图片的三步流程中的前两步：
  1. 调用 channelBanners.insert 方法，将二进制映像数据上传到 YouTube。图片必须具有 16:9 的宽高比，并且至少为 2048x1152 像素。建议您上传一张 2560 像素 x 1440 像素的图片。
  2. 从 API 为第 1 步返回的响应中提取 url 属性的值。
  3. 调用 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 方法。
delete DELETE /comments 删除评论。
update PUT /comments 修改评论。

I18nLanguages

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

每个 i18nLanguage 资源都包含一个语言代码和一个名称。在调用 videoCategories.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 返回零个或零个以上 membershipsLevel 资源的集合，这些资源归授权 API 请求的频道所有。级别按隐式显示顺序返回。

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 资源，但您也可以配置查询，以便仅检索特定类型的资源。

订阅

subscription 资源包含有关 YouTube 用户订阅的信息。当频道中添加新视频时，或者当其他用户在 YouTube 上执行多项操作之一（例如上传视频、为视频评分或评论视频）时，订阅会通知用户。

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

方法 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 缩略图通常为 120x90 像素，而 channel 资源的 default 缩略图通常为 88x88 像素。
  • 对于某些图片，相同类型的资源可能仍具有不同的缩略图尺寸，具体取决于原始图片的分辨率或上传到 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 删除频道的视频水印图片。