修订历史记录

本页面列出了 YouTube Data API (v3) 的变更和文档更新。订阅此变更日志。订阅

2025 年 7 月 10 日

自 2025 年 7 月 21 日起，YouTube 将调整 video.list 方法的 mostPopular 图表返回的内容。过去，mostPopular 图表反映的是“时下流行”列表中的精选视频。现在，mostPopular 排行榜将显示“时下流行”音乐、电影和游戏排行榜中的视频。此 API 变更与 YouTube 热门趋势页面的弃用同步进行。

2025 年 3 月 26 日

自 2025 年 3 月 31 日起，YouTube 将更改 Shorts 短视频的观看次数统计方式。过去，短视频的播放时长达到一定的秒数之后，系统才会统计一次 Shorts 观看。现在，“观看次数”这项指标将统计短视频开始播放或重放的次数，而且没有最低观看时长要求。 了解详情

自 2025 年 3 月 31 日起，Data API 中的以下字段将根据此变更返回 Shorts 短视频的观看次数：

  • channels.statistics.viewCount
  • videos.statistics.viewCount

2024 年 10 月 30 日

该 API 现在支持识别包含逼真加工内容或合成内容 (A/S) 的视频。详细了解 与 A/S 内容相关的 YouTube 政策。

A/S 内容的示例包括以下视频：

  • 呈现真实人物的言论或行为，但实际并非本人言行
  • 加工有关真实事件或地点的视频片段
  • 生成逼真但实际并不存在的场景

如需指明视频是否包含 A/S 内容，请设置 status.containsSyntheticMedia 属性。您可以在调用 videos.insert 或 videos.update 方法时设置此属性。如果设置了该属性，则会在 video 资源中返回该属性。

2024 年 4 月 30 日

注意：这是一则弃用公告。

此更新包含以下更改：

该 API 不再支持插入或检索频道讨论。此变更与 YouTube 网站上支持的功能一致，即不支持向频道发布评论。

2024 年 3 月 13 日

注意：这是一则弃用公告。

此更新包含以下更改：

已弃用 captions.insert 和 captions.update 方法的 sync 参数。YouTube 将于 2024 年 4 月 12 日起停止支持该参数。

由于此项更改，开发者在插入或更新字幕轨道时必须添加时间信息，否则上传会失败。

2024 年 3 月 12 日

此更新包含以下更改：

更新了 captions 资源的文档，指出 snippet.name 字段允许的最大长度为 150 个字符。如果轨道名称的长度超过此值，API 会返回 nameTooLong 错误。

2024 年 3 月 7 日

注意：这是一则弃用公告。

channel 资源属性 brandingSettings.channel.moderateComments 已被弃用。YouTube 将于 2024 年 3 月 7 日起停止支持该参数。

2024 年 1 月 31 日

此更新包含以下更改：

channels.list 方法的新 forHandle 参数可让您通过指定频道的 YouTube 标识名来检索有关频道的信息。

2023 年 11 月 9 日

由于 videoId 资源不再通过 API 调用返回，因此已移除 Comments 下对 videoId 资源的所有引用。

2023 年 9 月 12 日

注意：这是一则弃用公告。

comments.markAsSpam 方法已弃用多年。此方法在 YouTube 上已不受支持，并且不再通过 API 提供支持。

我们已在引用 comments.markAsSpam 方法的所有文档中添加了弃用通知。

2023 年 8 月 22 日

search.list 方法现在支持 videoPaidProductPlacement 参数。借助此参数，您可以过滤搜索结果，使其仅包含创作者标记为包含付费宣传内容的视频。

2023 年 8 月 18 日

video 资源的 liveStreamingDetails.concurrentViewers 定义已更新，指出 YouTube Data API 返回的并发观看者人数可能与通过 YouTube 数据分析获得的经过处理的、已去除垃圾内容的并发观看者人数有所不同。YouTube 帮助中心提供了有关直播指标的更多信息。

2023 年 8 月 7 日

正如我们在 2023 年 6 月 12 日宣布的那样，search.list 方法的 relatedToVideoId 参数已被弃用。该参数已不再受支持，并且 API 文档中已移除对该参数的引用。

2023 年 6 月 28 日

thumbnails.set 方法现在支持 uploadRateLimitExceeded 错误，该错误表示频道在过去 24 小时内上传的缩略图数量过多，应稍后重试。

2023 年 6 月 12 日

注意：这是一则弃用公告。

search.list 方法的 relatedToVideoId 参数已被弃用。自 2023 年 8 月 7 日起，YouTube 将停止支持该参数。

目前，我们已在 search.list 方法的文档中添加了弃用通知。此参数将于 2023 年 8 月 7 日或之后从 search.list 文档中完全移除。

此外，我们还从 API 实现指南中移除了一个演示如何检索相关视频的示例。

2022 年 8 月 22 日

将 video.statistics 字段的注释类型从无符号 long 改为字符串。

2022 年 8 月 5 日

YouTube 更改了字幕 ID 的生成方式，并为所有字幕轨道分配了新的字幕 ID。对于存储 caption_id 值的应用，此变更可能是不向后兼容的变更，但不会影响不存储 caption_id 值的应用。

从现在起到 2022 年 12 月 1 日，captions.list、captions.update、captions.download 和 captions.delete 方法将同时支持旧字幕轨道 ID 和新字幕轨道 ID。不过，自 2022 年 12 月 1 日起，YouTube 将停止支持旧版字幕轨道 ID。届时，如果使用旧版字幕轨道 ID 调用上述任何 API 方法，系统都会返回 captionNotFound 错误。

为应对此变更，您应计划在现在到 2022 年 12 月 1 日之间完全替换所有存储的字幕轨道数据。这意味着，对于您存储字幕轨道数据的任何视频，您都应删除当前存储的数据，然后调用 captions.list 方法来检索视频的当前字幕轨道集，并像往常一样将 API 响应中的数据存储起来。

2022 年 7 月 12 日

《YouTube API 服务条款》已更新。如需了解详情，请参阅 YouTube API 服务条款 - 修订历史记录。

2022 年 4 月 27 日

videos.insert 方法说明已更新，指出上传视频的文件大小上限已从 128GB 增加到 256GB。

2022 年 4 月 8 日

subscriptions.list 方法的 myRecentSubscribers 和 mySubscribers 参数定义均已更新，以说明 API 返回的订阅者数量可能有限。此变更表示文档更正，而不是 API 行为变更。

2021 年 12 月 15 日

正如我们在 2021 年 11 月 18 日宣布的那样，为了在整个 YouTube 平台上将视频的“不喜欢”次数设为私密，video 资源的 statistics.dislikeCount 属性现在已设为私密。

您可以访问 YouTube 的官方博客，详细了解此变更。

2021 年 11 月 18 日

为了配合在整个 YouTube 平台上将视频的“踩”次数设为私享的变更，video 资源的 statistics.dislikeCount 属性将从 2021 年 12 月 13 日起设为私享。这意味着，只有在 API 请求经过视频所有者身份验证的情况下，该属性才会包含在来自 videos.list 端点的 API 响应中。

videos.rate 端点不受此变化的影响。

如果开发者不公开显示“不喜欢”数量，但仍需要通过 API 客户端获取“不喜欢”数量，可以申请列入豁免许可名单。如需申请豁免，您必须填写此申请表单。

您可以访问 YouTube 的官方博客，详细了解此变更。

2021 年 7 月 2 日

注意：这是一则弃用公告。

commentThreads.update 端点已被弃用，不再受支持。 此端点复制了可通过其他 API 端点实现的功能。您可以改为调用 comments.update

方法，并且如果您的代码需要 commentThreads 资源，则对 commentThreads.list 方法进行二次调用。

2021 年 7 月 1 日

所有使用 YouTube API 服务的开发者都必须完成 API 合规性审核，才能获得超过默认配额分配（10,000 个单位）的配额。到目前为止，合规性审核流程和额外的配额单位分配申请都是由开发者填写并提交 YouTube API 服务 - 审核和配额增加表单来完成的。

为了明确这些流程并更好地满足使用我们 API 服务的开发者的需求，我们新增了三份表单以及一份填写这些表单的指南：

  • 接受过审核的开发者的申请表单：已通过 API 合规性审核的开发者可以填写并提交此简短的表单，申请增加分配的配额。
  • 申诉表单：如果开发者的 API 项目未通过合规性审核（或配额单位增加申请被拒），可以填写并提交此表单。
  • 控制权变更表单：如果开发者或代表开发者运营 API 客户端的任何一方发生与 API 项目相关的控制权变更（例如，通过股票买卖、合并或其他形式的企业交易），则必须填写并提交此表单。这样一来，YouTube 的 API 团队就可以更新我们的记录，审核新 API 项目的用例合规性，并验证开发者的当前配额分配情况。

每份新表单都会告知我们您打算如何使用 YouTube 的 API，以便我们更好地为您提供帮助。

如需了解详情，请参阅我们的新 API 合规性审核指南。

2021 年 5 月 12 日

注意：这是一则弃用公告。

此更新涵盖了以下 API 变更：

  • channel 资源的 contentDetails.relatedPlaylists.favorites 属性已被弃用。如 2016 年 4 月 28 日的修订历史记录条目中所述，收藏视频功能已弃用多年。

    在此更新之前，如果 API 客户端尝试将视频添加到不存在的“收藏夹”播放列表，API 仍会创建新的播放列表。今后，在这种情况下，系统不会创建播放列表，并且 API 会返回错误。尝试通过添加、修改或删除项来修改喜爱歌曲播放列表的行为也已全部弃用（如之前公告中所述），并且随时可能会开始返回错误。

  • 以下 channel 资源属性已弃用。YouTube 工作室界面和 YouTube 中已不再支持这些属性。因此，这些功能也不再受 API 支持。

    • brandingSettings.channel.defaultTab
    • brandingSettings.channel.featuredChannelsTitle
    • brandingSettings.channel.featuredChannelsUrls[]
    • brandingSettings.channel.profileColor
    • brandingSettings.channel.showBrowseView
    • brandingSettings.channel.showRelatedChannels

    所有属性都已从 channel 资源表示法中移除，并且其定义已从资源的属性列表中移除。此外，方法专用文档中已移除与这些属性相关的错误。

  • 以下 channelSection 资源属性已弃用。YouTube 工作室界面和 YouTube 中已不再支持这些属性。因此，这些功能也不再受 API 支持。

    • snippet.style
    • snippet.defaultLanguage
    • snippet.localized.title
    • localizations
    • localizations.(key)
    • localizations.(key).title
    • targeting
    • targeting.languages[]
    • targeting.regions[]
    • targeting.countries[]

    与此变更相关联，channelSection.list 方法的 hl 参数也已被弃用，因为其支持的功能不受支持。

    所有属性都已从 channelSection 资源表示法中移除，并且其定义已从资源的属性列表中移除。此外，方法专用文档中已移除与这些属性相关的错误。

  • 对于 channelSection 资源的 snippet.type 属性，以下值已被弃用。这些值在 YouTube 频道页面上已不受支持，因此也无法再通过 API 使用。

    • likedPlaylists
    • likes
    • postedPlaylists
    • postedVideos
    • recentActivity
    • recentPosts

  • playlist 资源的 snippet.tags[] 属性已被弃用。YouTube 上已不再支持此属性，因此，我们也不再通过 API 支持此属性。

2021 年 2 月 9 日

playlistItem 资源支持两个新属性：

2021 年 1 月 28 日

此更新包含以下更改：

  • playlistItems.delete、playlistItems.insert、playlistItems.list、playlistItems.update、playlists.delete、playlists.list 和 playlists.update 方法均支持新的 playlistOperationUnsupported 错误。当请求尝试执行特定播放列表不允许的操作时，就会出现此错误。例如，用户无法从其上传的视频播放列表中删除视频，也无法删除该播放列表本身。

    在所有情况下，此错误都会返回 400 HTTP 响应代码（错误请求）。

  • 文档中已移除 playlistItems.list 方法的 watchHistoryNotAccessible 和 watchLaterNotAccessible 错误。虽然用户的观看记录和稍后观看列表确实无法通过 API 访问，但 API 不会返回这些特定错误。

2020 年 10 月 15 日

开发者政策中新增了两个部分：

  • 新的第 III.E.4.i 条提供了有关通过 YouTube 嵌入式播放器收集和发送的数据的更多信息。您有责任确保在用户与任何 YouTube 嵌入式播放器互动以表明播放意图之前，您不会通过该播放器向我们发送任何用户数据。您可以通过将自动播放设置为 false，来限制在用户与播放器互动之前与 YouTube 共享的数据。
  • 新的第 III.E.4.j 条涉及在您的网站和应用中嵌入内容之前检查内容的“面向儿童的内容”(MFK) 状态。您有责任了解您在 API 客户端中嵌入的视频何时属于面向儿童的内容，并相应地处理从嵌入式播放器收集的数据。因此，您必须先使用 YouTube Data API 服务检查内容的状态，然后再通过任何 YouTube 嵌入式播放器将内容嵌入到 API 客户端中。

新的查找视频的“面向儿童”状态指南介绍了如何使用 YouTube Data API 服务查找视频的“面向儿童”状态。

除了这些更改之外，我们还在嵌入式播放器参数文档中添加了提醒，说明如果您启用自动播放功能，播放将会在用户未与播放器进行任何互动的情况下进行；因此，播放数据收集和共享将会在网页加载时进行。

2020 年 10 月 8 日

此更新包含与 channel 资源相关的三项细微更改：

  • 用于标识频道缩略图的 snippet.thumbnails 对象对于新创建的频道可能为空，并且可能需要长达一天的时间才能填充。
  • 即使对于频道所有者，statistics.videoCount 属性也仅反映频道公开视频的数量。此行为与 YouTube 网站上显示的数据一致。
  • 如果渠道关键字（在 brandingSettings.channel.keywords 属性中标识）超出允许的最大长度 500 个字符，或者包含未转义的英文引号 (")，则可能会被截断。请注意，500 个字符的限制不是每个关键字的限制，而是所有关键字的总长度限制。此行为与 YouTube 网站上的行为一致。

2020 年 9 月

注意：这是一则弃用公告。

此更新涵盖了以下 API 变更。所有变更将于 2020 年 9 月 9 日（即本公告的发布日期）或之后生效。鉴于此，开发者不应再依赖以下任何 API 功能。

  • 以下 API 资源、方法、参数和资源属性已立即弃用，并将于本公告发布之日或之后停止运行：
  • 如果 API 请求将 managedByMe 参数设置为 true，则 channels.list 方法的 API 响应不再包含 prevPageToken 属性。此变更不会影响其他 channels.list 请求的 prevPageToken 属性，也不会影响任何请求的 nextPageToken 属性。
  • channel 资源的 contentDetails.relatedPlaylists.watchLater 和 contentDetails.relatedPlaylists.watchHistory 属性均于 2016 年 8 月 11 日宣布弃用。playlistItems.insert 方法和 playlistItems.delete 方法对这些播放列表的支持也已完全弃用，并且这两个属性已从文档中移除。
  • channels.list 方法的 mySubscribers 参数（已于 2013 年 7 月 30 日宣布弃用）已从文档中移除。使用 subscriptions.list 方法及其 mySubscribers 参数可检索经过身份验证的用户的频道的订阅者列表。
  • channel 资源的 invideoPromotion 对象及其所有子属性（已于 2017 年 11 月 27 日 宣布弃用）已从文档中移除。

2020 年 7 月 29 日

我们简化了 API 请求的配额收费流程，移除了与 part 参数相关的额外费用。自即日起，我们将仅针对所调用的方法收取基本费用。如需详细了解简化版配额，请点击此处。

此项变更的影响是，大多数 API 调用的配额费用会略有降低，而某些 API 调用的费用仍保持不变。此变更不会增加任何 API 调用的费用。总而言之，可能的影响是，您在 Google Cloud 控制台中看到的分配配额将能发挥更大的作用。

我们强烈建议所有开发者为其项目完成合规性审核，以确保能够继续访问 YouTube API 服务。

此修订历史记录条目最初发布于 2020 年 7 月 20 日。

2020 年 7 月 28 日

通过 videos.insert 端点上传的所有视频（如果上传自 2020 年 7 月 28 日之后创建的未经验证的 API 项目），都将限制为私享观看模式。如需解除此限制，每个项目都必须接受审核，以验证是否符合服务条款。

如果创作者使用未经验证的 API 客户端上传视频，则会收到一封电子邮件，其中说明其视频已被锁定为私享，并且他们可以使用官方客户端或经过审核的客户端来避免此限制。

在 2020 年 7 月 28 日之前创建的 API 项目目前不受此更改的影响。不过，我们强烈建议所有开发者为其项目完成合规性审核，以确保能够继续访问 YouTube API 服务。

2020 年 7 月 21 日

[更新于 2020 年 7 月 28 日。]此修订历史记录条目中提及的文档更新已于 2020 年 7 月 28 日重新发布。

昨天，我们发布了一项与配额收费流程相关的文档更新。 不过，由于出现意外情况，配额变更尚未生效。因此，为了确保准确性，我们已恢复文档。为避免混淆，我们已移除说明相应变更的版本历史记录条目，并将在近期重新发布。

2020 年 7 月 7 日

注意：这是一则弃用公告。

videos.insert 方法的 autoLevels 和 stabilize 参数现已弃用，并且这两个参数已从文档中移除。系统会忽略这些值，并且这些值不会影响新上传视频的处理方式。

2020 年 6 月 15 日

新的遵守 YouTube 开发者政策指南提供了指导和示例，可帮助您确保 API 客户端遵守 YouTube API 服务条款和政策 (API TOS) 的特定部分。

本指南可帮助您了解 YouTube 如何强制执行《API 服务条款》的某些方面，但不会取代任何现有文档。本指南解答了开发者在 API 合规性审核期间提出的一些最常见的问题。我们希望，通过帮助您了解我们如何解读和执行我们的政策，该指南能简化您的功能开发流程。

2020 年 6 月 4 日

注意：这是对之前弃用公告的更新。

频道公告功能现已完全弃用。此变更最初于 2020 年 4 月 17 日宣布，现已生效。因此，activities.insert 方法不再受支持，并且 activities.list 方法不再返回频道公告。如需了解详情，请访问 YouTube 帮助中心。

2020 年 4 月 17 日

注意：这是一则弃用公告。

YouTube 即将弃用频道公告功能。因此，activities.insert 方法将被弃用，而 activities.list 方法将停止返回频道公告。这些变更将于 2020 年 5 月 18 日或之后在 API 中生效。如需了解详情，请访问 YouTube 帮助中心。

2020 年 3 月 31 日

此更新包含以下更改：

  • 新资源和方法

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

      此资源取代了 sponsor 资源，后者已作为 YouTube Live Streaming API 的一部分记录在案。sponsor 资源现已弃用，API 客户端应更新对 sponsors.list 方法的调用，改为使用 members.list 方法。

    • 新的 membershipsLevel 资源用于标识由授权 API 请求的创建者管理的定价级别。 membershipsLevels.list 方法会检索创作者的所有会员等级的列表。

2020 年 1 月 10 日

该 API 现在支持识别面向儿童的内容，YouTube 将其称为“面向儿童的内容”。如需详细了解“面向儿童的内容”，请访问 YouTube 帮助中心。

channel 和 video 资源支持两个新属性，以便内容创作者和观看者识别面向儿童的内容：

  • 借助 selfDeclaredMadeForKids 属性，内容创作者可以指定频道或视频是否面向儿童。

    对于渠道，可以在调用 channels.update 方法时设置此属性。对于视频，可以在调用 videos.insert 或 videos.update 方法时设置此属性。

    请注意，只有在频道所有者授权 API 请求的情况下，此属性才会包含在包含 channel 或 video 资源的 API 响应中。
  • 借助 madeForKids 属性，任何用户都可以检索频道或视频的“面向儿童的内容”状态。例如，状态可能根据 selfDeclaredMadeForKids 属性的值来确定。如需详细了解如何为频道、视频或直播设置观众群，请访问 YouTube 帮助中心。

我们还更新了 YouTube API 服务的《服务条款》和《开发者政策》。如需了解详情，请参阅 YouTube API 服务条款 - 修订历史记录。YouTube API 服务条款和开发者政策的变更将于 2020 年 1 月 10 日（太平洋时间）生效。

2019 年 9 月 10 日

我们已更新 API 参考文档，以反映 YouTube 上报告订阅人数的方式发生的变化，以及由此导致的 API 响应变化。由于这项变更，YouTube Data API 服务返回的订阅人数将向下舍入为三位有效数字（如果订阅人数超过 1,000）。此变更会影响 channel 资源的 statistics.subscriberCount 属性。

注意：即使在用户发送了有关其自有频道的授权数据请求的情况下，此变更也会影响相应属性值。频道所有者仍然可以在 YouTube 工作室中看到确切的订阅人数。

例如，如果某个频道的订阅人数为 123,456，则 statistics.subscriberCount 属性将包含值 123000。 下表显示了订阅人数在 API 响应中如何舍入，以及在其他公开显示的 YouTube 用户界面中如何缩写：

订阅人数示例 YouTube Data API 公开显示的 YouTube 界面
1,234 1230 1230
12,345 12300 1.23 万
123,456 123000 12.3 万
1,234,567 1230000 123 万
12,345,678 12300000 1230 万
123,456,789 123000000 1.23 亿

2019 年 4 月 4 日

此更新包含以下更改：

  • 我们更新了 API 参考文档，以便更好地说明每种方法的常见用例，并通过 API Explorer 微件提供动态、高质量的代码示例。如需查看示例，请参阅 channels.list 方法的文档。现在，描述 API 方法的页面上新增了两个元素：

    • 借助 API Explorer 微件，您可以选择授权范围、输入示例参数和属性值，然后发送实际的 API 请求并查看实际的 API 响应。该微件还提供全屏视图，其中显示完整的代码示例，这些示例会动态更新，以使用您输入的范围和值。

    • 常见用例部分介绍了相应页面上所介绍方法的一个或多个常见用例。例如，您可以调用 channels.list 方法来检索有关特定频道的数据，或检索有关当前用户频道的数据。

      您可以使用该部分中的链接，在 API 探索器中填充适合您的使用情形的示例值，或者打开已填充这些值的全屏 API 探索器。这些更改旨在让您更轻松地找到直接适用于您尝试在自己的应用中实现的用例的代码示例。

    目前，代码示例支持 Java、JavaScript、PHP、Python 和 curl。

  • 代码示例工具也已更新，采用新的界面，提供上述所有相同的功能。借助该工具，您可以探索不同方法的使用情形，将值加载到 API Explorer 中，并打开全屏 API Explorer 以获取 Java、JavaScript、PHP 和 Python 代码示例。

    随着此项变更的推出，之前列出了适用于 Java、JavaScript、PHP 和 Python 的可用代码示例的页面已被移除。

  • 我们更新了 Java、JavaScript、PHP 和 Python 的快速入门指南。修订后的指南介绍了如何使用 API Explorer 中的代码示例，通过 API 密钥运行一个示例，并通过 OAuth 2.0 客户端 ID 运行另一个示例。

请注意，上述更改取代了 2017 年添加到 API 文档中的互动式工具。

2018 年 7 月 9 日

此更新包含以下更改：

  • channel 资源的 snippet.thumbnails 属性的定义已更新，以说明在应用中显示缩略图时，您的代码应使用 API 响应中返回的图片网址。例如，您的应用不应在 API 响应中返回的网址中使用 http 网域，而应使用 https 网域。

    自 2018 年 7 月起，频道缩略图网址将仅在 https 网域中提供，这也是网址在 API 响应中的显示方式。在此时间之后，如果您的应用尝试从 http 网域加载 YouTube 图片，则可能会看到损坏的图片。

  • 注意：这是一则弃用公告。

    video 资源的 recordingDetails.location.altitude 属性已被弃用。无法保证视频会为此属性返回值。同样，即使 API 请求尝试为相应属性设置值，传入的数据也可能不会存储。

2018 年 6 月 22 日

实现指南（之前称为“实现和迁移指南”）已更新，移除了有关从 v2 API 迁移到 v3 API 的说明。此外，还移除了 v3 API 中已废弃的功能（例如“收藏的视频”）的相关说明。

2017 年 11 月 27 日

此更新包含以下更改：

  • 注意：这是一则弃用公告。

    YouTube 将移除对精选视频和精选网站功能的支持，这些功能在 API 中通过 channel 资源的 invideoPromotion 对象提供支持。因此，该对象（包括其所有子属性）将被弃用。

    在 2017 年 12 月 14 日之前，您仍可以检索和设置 invideoPromotion 数据。在付款日期后：

    • 尝试在调用 channels.list 时检索 invideoPromotion 部分将返回空的 invideoPromotion 或根本不返回任何 invideoPromotion 数据。
    • 在调用 channels.update 时尝试更新 invideoPromotion 数据将返回成功响应，直到 2018 年 5 月 27 日为止，但这些尝试将被视为无操作，也就是说，它们实际上不会执行更新。

    2018 年 5 月 27 日之后，这些请求可能会返回错误消息，例如，指示 invalidPromotion 是无效的部分。

2017 年 11 月 16 日

此更新包含以下更改：

  • 交互式代码段工具现在支持 Node.js 代码示例。您还可以在几乎所有 API 方法（例如 channels.list 方法）的文档中看到这些示例。

    可自定义的示例旨在为您提供特定用例的 Node.js 应用起点。此功能类似于 Node.js 快速入门指南中的代码。不过，这些示例确实包含一些未在快速入门中显示的实用函数：

    • removeEmptyParameters 函数接受与 API 请求参数对应的键值对列表，并移除没有值的参数。
    • createResource 函数接受与 API 资源中的属性对应的键值对列表。然后，它会将属性转换为可在 insert 和 update 操作中使用的 JSON 对象。以下示例显示了一组属性名称和值，以及代码将为这些属性名称和值创建的 JSON 对象： 
      # Key-value pairs:
{'id': 'ABC123',
 'snippet.title': 'Resource title',
 'snippet.description': 'Resource description',
 'status.privacyStatus': 'private'}

# JSON object:
{
 'id': 'ABC123',
 'snippet': {
   'title': 'Resource title',
   'description': 'Resource description',
 },
 'status': {
   'privacyStatus': 'private'
 }
}

    所有这些示例都旨在供您下载并在本地运行。如需了解详情，请参阅代码段工具说明中有关在本地运行完整代码示例的前提条件。

2017 年 10 月 25 日

此更新包含以下更改：

  • 互动式代码段工具中的 Python 代码示例已更新为使用 google-auth 和 google-auth-oauthlib 库，而不是现已弃用的 oauth2client 库。

    除了这项更改之外，该工具现在还为已安装的 Python 应用和 Python Web 服务器应用提供完整的代码示例，这些应用使用略有不同的授权流程。如需查看完整示例（以及此变更），请执行以下操作：

    1. 前往互动式代码段工具或任何 API 方法（例如 channels.list 方法）的文档。
    2. 点击代码示例上方的 Python 标签页。
    3. 点击标签页上方的切换开关，即可从查看代码段切换为查看完整示例。
    4. 该标签页现在应显示使用 InstalledAppFlow 授权流程的完整代码示例。示例上方的说明对此进行了说明，还链接到了一个 Web 服务器应用示例。
    5. 点击该链接可切换到 Web 服务器示例。该示例使用 Flask Web 应用框架和不同的授权流程。

    所有这些示例都旨在供您下载并在本地运行。如果您想运行示例，请参阅代码段工具说明中有关在本地运行完整代码示例的说明。

2017 年 8 月 29 日

此更新包含以下更改：

  • 更新了 search.list 方法的 forContentOwner 参数的定义，指出如果该参数设置为 true，则 type 参数必须设置为 video。
  • 更新了 search.list 方法的 regionCode 参数的定义，以明确该参数会将搜索结果限制为可在指定区域观看的视频。
  • YouTube 已更新其品牌徽标和图标。您可以从品牌推广指南页面下载新的“developed with YouTube”徽标。该页面上还显示了其他新的 YouTube 徽标和图标，您可以从 YouTube 品牌网站下载这些徽标和图标。

2017 年 7 月 24 日

此更新包含以下更改：

  • 我们为 iOS 推出了新的 YouTube Data API 快速入门指南。本指南介绍了如何在以 Objective-C 或 Swift 编写的简单 iOS 应用中使用 YouTube Data API。
  • YouTube Data API 的互动式代码段工具现在包含说明文档，用于介绍该工具的一些功能：
    • 执行 API 请求
    • 在代码段和完整代码示例之间切换
    • 使用样板函数
    • 加载现有资源（用于更新方法）

    注意：该工具还嵌入在 API 方法的 API 参考文档中（示例）。

2017 年 6 月 1 日

此更新包含以下更改：

2017 年 5 月 17 日

此更新包含以下更改：

  • 我们更新了 API 参考文档，使代码段更加普遍且更具互动性。现在，介绍 API 方法（例如 channels.list 或 videos.rate）的页面提供了一个互动式工具，可让您查看和自定义 Java、JavaScript、PHP、Python、Ruby、Apps 脚本和 Go 中的代码段。

    对于任何给定的方法，该工具都会显示一个或多个应用场景的代码段，每个应用场景都描述了调用该方法的常用方式。例如，您可以调用 channels.list 方法来检索有关特定频道或当前用户频道的数据。

    您还可以与代码示例互动：

    • 修改参数和属性值，代码段会动态更新，以反映您提供的值。

    • 在代码段和完整示例之间切换。代码段显示了调用 API 方法的代码部分。完整示例包含该代码段以及用于授权和发送请求的样板代码。您可以从命令行或本地网络服务器复制并运行完整示例。

    • 点击按钮即可执行请求。（如需执行请求，您需要授权该工具代表您调用 API。）

    请注意，此工具已取代提供它的页面上的 API Explorer。（每个页面都会显示一个链接，以便您也可以选择在 API Explorer 中加载正在处理的请求。）

  • 数据 API 代码段工具也已更新，采用全新界面，提供上述所有相同的功能。本页中提供的主要新功能包括：

    • 支持写入数据的 API 请求。
    • 支持 Java 示例。
    • 用于授权用户和构建 API 请求的样板代码更加灵活和全面。

2017 年 4 月 27 日

此更新包含以下更改：

2017 年 3 月 30 日

此更新包含以下更改：

  • channel 资源的新 topicDetails.topicCategories[] 属性包含描述频道内容的维基百科网址列表。这些网址对应于资源 topicDetails.topicIds[] 属性中返回的主题 ID。
  • playlistItem 资源的新 contentDetails.videoPublishedAt 属性用于标识视频发布到 YouTube 的时间。资源已包含 snippet.publishedAt 属性，用于标识将相应项添加到播放列表的时间。
  • 与 channel 资源类似，video 资源现在会返回 topicDetails.topicCategories[] 属性，其中包含描述视频内容的维基百科网址列表。对于 video 资源，网址对应于资源 topicDetails.relevantTopicIds[] 属性中返回的主题 ID。
  • video 资源的新 contentDetails.contentRating.mpaatRating 属性用于标识美国电影协会为电影预告片或预览版给出的分级。

2017 年 2 月 27 日

正如我们最初于 2016 年 8 月 11 日宣布的那样，YouTube 已将支持的主题 ID 列表切换为精选列表。支持的主题 ID 的完整列表包含在 channel 和 video 资源的 topicDetails 属性中，以及 search.list 方法的 topicId 参数中。

请注意，精选列表有以下几项变更：

  • 以下主题已添加为 Society 的子主题：
    名称主题 ID
    企业/m/09s1f
    健康/m/0kt51
    军事/m/01h6rj
    政治/m/05qt0
    宗教/m/06bvp
  • 移除了之前是 Entertainment 子主题的 Animated cartoon 主题。
  • 移除了之前是 Music 子主题的 Children's music 主题。

此次更改后，与视频相关的主题现在始终在 video 资源的 topicDetails.relevantTopicIds[] 属性值中返回。

2016 年 11 月 29 日

此更新包含以下更改：

  • 自 2017 年 2 月 10 日起，支持的主题 ID 列表将有三项小更改：

    • Professional wrestling 类别之前是 Sports 类别的子级，现在是 Entertainment 的子级。
    • TV shows 类别是新类别，属于 Entertainment 的子级。
    • 之前是 Lifestyle 子类别的 Health 类别已被移除。

    另请注意，有几个父类别（Entertainment、Gaming、Lifestyle、Music 和 Sports）。与子类别（例如 Tennis）相关联的任何视频也会与父类别 (Sports) 相关联。

2016 年 11 月 10 日

此更新包含以下更改：

  • 正如我们在 2016 年 8 月 11 日首次宣布的那样，Freebase 和 Freebase API 的弃用需要对主题 ID 进行多项更改。主题 ID 用于标识与 channel 和 video 资源相关联的主题，您还可以使用 topicId 搜索参数查找与特定主题相关的频道或视频。

    自 2017 年 2 月 10 日起，YouTube 将开始返回一小部分主题 ID，而不是目前返回的粒度更精细的 ID。此外，请注意，无法保证频道和视频与任何主题相关联，这与当前的 API 行为一致。

    为了让您为这些变化做好 API 客户端准备，我们更新了以下 API 参数和属性的定义，以列出届时将支持的主题 ID。请注意，所有媒体资源的类别列表都相同。

  • 注意：这是一则弃用公告。

    以下属性即将弃用：

    • channel 资源的 topicDetails.topicIds[] 属性。此属性将支持到 2017 年 11 月 10 日。
    • video 资源的 topicDetails.relevantTopicIds[] 属性。此属性将支持到 2017 年 11 月 10 日。
    • video 资源的 topicDetails.topicIds[] 属性。自 2017 年 2 月 10 日起，此属性将不再包含值。（在此日期之后，topicDetails.relevantTopicIds[] 属性值将标识与视频关联的所有主题。）

  • 由于 Freebase 已被弃用，因此我们已从文档中移除使用 Freebase 主题进行搜索指南。该指南提供了代码示例，以展示应用如何与 Freebase API 搭配使用。

    此外，还从 search.list 方法的文档中移除了几个与主题 ID 相关的代码示例。

2016 年 11 月 2 日

此更新包含以下更改：

  • 新属性和参数

    • video 资源包含多个新属性：

      • player.embedHtml 属性包含一个 <iframe> 标记，您可以使用该标记嵌入可播放视频的播放器。新的 player.embedHeight 和 player.embedWidth 属性用于标识嵌入式播放器的尺寸。只有当 API 请求为 maxHeight 或 maxWidth 参数指定了值时，才会返回这些属性。这两个新参数将在本修订历史记录条目中稍后进行说明。

      • 新的 hasCustomThumbnail 属性用于指明视频上传者是否为视频提供了自定义缩略图。请注意，此属性仅对视频上传者可见。

      • 新的 fpbRatingReasons[] 用于标识视频获得 FPB（南非）分级的原因。

      • 新的 mcstRating 用于标识视频在越南获得的分级。

    • videos.list 方法支持两个新参数：maxHeight 和 maxWidth。在检索 video 资源中的 player 部分时，您可以使用这两个参数中的任意一个或同时使用这两个参数。

      默认情况下，player.embedHtml 属性中返回的 <iframe> 的高度为 360 像素。宽度会调整为与视频的宽高比一致，从而确保嵌入式播放器不会在视频周围显示黑边。例如，如果视频的宽高比为 16:9，则播放器的宽度为 640 像素。

      借助新参数，您可以指定嵌入代码应使用适合应用布局的高度和/或宽度，而不是默认尺寸。API 服务器会根据需要调整播放器尺寸，以确保嵌入式播放器不会在视频周围显示黑边。请注意，这两个参数都指定了嵌入式播放器的最大尺寸。因此，如果同时指定了这两个参数，则某个维度的值可能仍小于该维度允许的最大值。

      例如，假设某个视频的宽高比为 16:9。因此，如果未设置 maxHeight 或 maxWidth 参数，player.embedHtml 代码将包含一个 640x360 的播放器。

      • 如果 maxHeight 参数设置为 720，且未设置 maxWidth 参数，则 API 将返回 1280x720 的播放器。
      • 如果 maxWidth 参数设置为 960，且未设置 maxHeight 参数，则 API 会返回 960x540 的播放器。
      • 如果 maxWidth 参数设置为 960，且 maxHeight 参数设置为 450，则 API 将返回 800x450 的播放器。

      如上所述，新的 player.embedHeight 和 player.embedWidth 属性用于标识播放器的尺寸。

  • 对现有方法、属性和参数的更新

    • 更新了 channelSection 资源说明，指出频道最多可以创建 10 个不设置定位数据的搁架，最多可以创建 100 个设置了定位数据的搁架。

      此外，channelSection 资源的 targeting 属性已更新，以反映只能使用 API 设置定位选项这一事实。如果使用 YouTube 网站上的界面修改频道版块，定位选项会被删除。

    • 已更正 i18nLanguage 资源的 snippet.name 属性的定义，以反映该值表示语言名称（以 i18nLanguage.list 方法的 hl 参数指定的语言书写）。

    • playlistItem 资源的 contentDetails.note 属性已更新，以说明属性值的长度上限为 280 个字符。

    • playlistItem 资源的 contentDetails.startAt 和 contentDetails.endAt 属性已弃用。如果这些字段是在 playlistItems.insert 或 playlistItems.update 请求中设置的，则会被忽略。

    • playlistItems.delete 和 playlistItems.update 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。使用该方法的请求还需要通过提供对 https://www.googleapis.com/auth/youtubepartner 范围的访问权限的令牌进行授权。

    • search.list 方法的 publishedBefore 和 publishedAfter 参数均已更新，以指明参数值是包含在内的。例如，如果设置了 publishedBefore 参数，API 会返回在指定时间之前或指定时间创建的资源。

    • video 资源的 contentDetails.contentRating.grfilmRating 属性支持三个额外的值：grfilmK12、grfilmK15 和 grfilmK18。

    • 更新了 videos.insert 方法说明，指出上传视频的文件大小上限已从 64GB 增加到 128GB。

  • 新增和更新的错误

    • 该 API 支持以下新错误：

      错误类型 错误详情 说明
      forbidden (403) homeParameterDeprecated activities.list 方法会返回此错误，以表明无法通过此 API 获取用户的首页活动数据。如果您在未经授权的请求中将 home 参数设置为 true，则可能会出现此错误。
      invalidValue (400) invalidContentDetails playlistItems.insert 方法会返回此错误，以表明请求中的 contentDetails 对象无效。此错误发生的原因之一是 contentDetails.note 字段的长度超过 280 个字符。
      forbidden (403) watchHistoryNotAccessible playlistItems.list 方法返回此错误，表示相应请求尝试检索“观看记录”播放列表项，但无法使用该 API 检索这些项。
      forbidden (403) watchLaterNotAccessible playlistItems.list 方法返回此错误，表明相应请求尝试检索“稍后观看”播放列表项，但无法使用该 API 检索这些项。
      badRequest (400) uploadLimitExceeded videos.insert 方法返回此错误，以表明相应频道已超出可上传的视频数量。
      forbidden (403) forbiddenEmbedSetting videos.update 方法返回此错误，以表明 API 请求尝试为视频设置无效的嵌入设置。请注意，某些频道可能没有权限为直播提供嵌入式播放器。如需了解详情，请访问 YouTube 帮助中心。

    • 如果您将重复的视频插入播放列表，playlistItems.insert 方法不再返回错误。之前，某些不允许重复但已不再受支持的播放列表（例如“喜爱的视频”）会发生此错误。一般来说，播放列表允许包含重复视频。

  • 其他更新

    • 更新了 2016 年 9 月 15 日的修订历史记录条目，以明确说明，每当响应中包含 channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性时，它们始终分别包含值 HL 和 WL。此外，只有在经过授权的用户检索有关其自有频道的数据时，才会包含这些属性。

2016 年 9 月 15 日

此更新包含以下更改：

  • 2016 年 8 月 11 日的修订历史记录更新讨论了与主题 ID 相关的多项变更，包括自 2017 年 2 月 10 日起，支持的主题 ID 集将发生变化。支持的主题列表将于 2016 年 11 月 10 日发布。

  • 以下变更现已生效。我们已在 2016 年 8 月 11 日的修订历史记录更新中通知了这些变更：

    • 如果调用 activities.list 方法时将 home 参数设置为 true，则 API 响应现在包含与未登录 YouTube 的用户在首页上看到的内容类似的项。

      这项细微的更改旨在提供比 2016 年 8 月 11 日的修订历史记录更新中所述行为更好的用户体验。该更新曾指出，使用 home 参数的请求将返回一个空列表。

    • channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性现在包含所有渠道的 HL 和 WL 值。

      需要明确的是，只有在授权用户检索有关其自有频道的数据时，这些属性才会显示。即使是已获授权的用户检索自己频道的数据，这些属性也始终包含值 HL 和 WL。因此，无法通过 API 检索观看记录和“稍后观看”播放列表 ID。

      此外，对于频道的观看记录或“稍后观看”播放列表，检索播放列表详情 (playlists.list) 或播放列表项 (playlistItems.list) 的请求现在会返回空列表。对于新值 HL 和 WL，以及 API 客户端可能已存储的任何观看记录或稍后观看播放列表 ID，此行为均适用。

  • 不再返回 video 资源的 fileDetails.recordingLocation 对象及其子属性。以前，只有视频的所有者才能检索此数据（例如父 fileDetails 对象）。

2016 年 8 月 11 日

此更新包含以下更改：

  • 新发布的 YouTube API 服务条款（以下简称“更新后的条款”）已在 YouTube 工程和开发者博客中详细讨论，对当前的服务条款进行了多项更新。除了将于 2017 年 2 月 10 日生效的更新后的条款之外，此更新还包含多份支持性文档，用于帮助说明开发者必须遵守的政策。

    如需查看所有新文档，请参阅更新后的条款的版本历史记录。此外，未来对更新后的条款或相关支持文档所做的更改也会在该修订历史记录中说明。您可以通过相应文档中的链接订阅 RSS Feed，以获取该修订历史记录中的更改。

  • Freebase 和 Freebase API 的弃用导致了与主题 ID 相关的一些变更。主题 ID 用于以下 API 资源和方法：

    • channel 资源的 topicDetails 部分用于标识与频道相关的主题。
    • video 资源的 topicDetails 部分用于标识与视频相关联的主题。
    • 借助 search.list 方法的 topicId 参数，您可以搜索与特定主题相关的视频或频道。

    这些功能的变化如下：

    • 自 2017 年 2 月 10 日起，YouTube 将开始返回一小部分主题 ID，而不是迄今为止返回的更精细的 ID 集。这组支持的主题将识别出体育或篮球等高级别类别，但不会识别出具体的球队或球员。我们会公布支持的主题集，以便您有时间为这项变更做好应用准备。

    • 在 2017 年 2 月 10 日之前，您可以使用已检索到的任何 Freebase 主题 ID 来搜索内容。不过，在此时间之后，您将只能使用上一项中确定的一小部分主题，按主题检索搜索结果。

    • 2017 年 2 月 10 日之后，如果您尝试使用不在较小的支持主题 ID 集中的主题 ID 搜索结果，API 将返回空的结果集。

  • 自 2016 年 9 月 12 日起，以下多个 API 字段和参数将被弃用：

    • activities.list 方法的 home 参数允许经过授权的用户检索将显示在 YouTube 首页上的相应用户的活动 Feed。在 2016 年 9 月 12 日之后使用此参数的请求将返回一个空列表。

    • channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性仅对检索用户自有频道相关数据的已获授权用户可见。2016 年 9 月 12 日之后，contentDetails.relatedPlaylists.watchHistory 将返回值 HL，而 contentDetails.relatedPlaylists.watchLater 属性将针对所有渠道返回值 WL。

      在 2016 年 9 月 12 日之后，如果请求检索频道的观看历史记录或“稍后观看”播放列表的播放列表详情 (playlists.list)，系统将返回一个空列表。在此时间之后，请求检索任一此类播放列表中的播放列表项 (playlistItems.list) 也会返回空列表。新值 HL 和 WL 以及您的 API 客户端可能已存储的任何观看记录或“稍后观看”播放列表 ID 都是如此。

    • 自 2016 年 9 月 12 日起，系统将不再返回 video 资源的 fileDetails.recordingLocation 对象或其任何子属性。由于父 fileDetails 对象只能由视频所有者检索，因此只有视频所有者才能检索此数据。

2016 年 6 月 13 日

此更新包含以下更改：

  • channel 资源的 contentDetails.googlePlusUserId 属性已被弃用。之前，只有当频道与 Google+ 个人资料相关联时，此属性才会存在。弃用后，该属性将不再包含在任何 channel 资源中。

  • comment 资源的 snippet.authorGoogleplusProfileUrl 属性已被弃用。之前，只有当频道与 Google+ 个人资料相关联时，此属性才会存在。弃用后，该属性将不再包含在任何 comment 资源中。

由于在弃用后不会返回这两个属性，因此已从相应资源文档中移除了这两个属性。

2016 年 5 月 31 日

此更新包含以下更改：

  • subscriptions.list 方法的新 myRecentSubscribers 参数会检索经过身份验证的用户的频道的订阅者列表，并按订阅者订阅频道的时间以倒序排列。

    请注意，新参数仅支持检索经过身份验证的用户频道的最近 1,000 位订阅者。如需检索完整的订阅者列表，请使用 mySubscribers 参数。该参数不会按特定顺序返回订阅者，也不会限制可检索的订阅者数量。

  • 我们更新了 activity、playlistItem、playlist、search result、thumbnail 和 video 资源的 snippet.thumbnails.(key) 属性的定义，以说明某些视频还提供其他缩略图尺寸。

    • standard 图片的宽度为 640 像素，高度为 480 像素。
    • maxres 图片的宽度为 1280 像素，高度为 720 像素。

  • 更新了 channelSection.list 方法的 part 参数的定义，指出检索 targeting 部分需要花费 2 个配额单位。

  • 现在，当未经正确授权的请求尝试检索 video 资源的 fileDetails、processingDetails 或 suggestions 部分时，videos.list 方法会返回 forbidden (403) 错误。这些部分仅适用于视频的所有者。

2016 年 5 月 17 日

新的 Data API 代码段工具可针对常见的 YouTube Data API 用例提供简短的代码段。目前，代码段适用于 Apps 脚本、Go、JavaScript、PHP、Python 和 Ruby 中的所有只读 API 方法。

对于每种方法，该工具都会显示一个或多个使用情形的代码示例。例如，它为 search.list 方法提供了 5 个代码段：

  • 按关键字列出视频
  • 按位置列出视频
  • 列出直播活动
  • 搜索经过身份验证的用户的视频
  • 列出相关视频

对于每种使用情形，该工具都会显示 API 请求中使用的参数。您可以修改参数值，在这种情况下，该工具会更新代码段，以反映您提供的参数值。

最后，该工具会显示每个请求的 API 响应。如果您修改了请求参数，API 响应将基于您提供的参数值。请注意，您需要授权该工具代表您提交请求，以便显示 API 响应。

2016 年 4 月 28 日

此更新包含以下更改：

  • video 资源的新 contentDetails.projection 属性用于指定视频的投影格式。有效的属性值为 360 和 rectangular。

  • video 资源的 recordingDetails.location 和 fileDetails.recordingLocation 属性均已更新，以说明这两个属性之间的区别：

    • recordingDetails.location 属性用于标识视频所有者希望与视频相关联的位置。您可以修改此位置信息，它会出现在公开视频的搜索结果中，并且可能会向用户显示公开视频的位置信息。
    • fileDetails.recordingLocation 属性值是不可变的，表示与原始上传的视频文件相关联的位置。此值仅对视频所有者可见。

  • channel 资源的 contentDetails.relatedPlaylists.favorites 属性的定义已更新，其中指出属性值可能包含指向无法提取的空播放列表的播放列表 ID。这是因为“收藏的视频”功能已被弃用。请注意，此属性不受 API 弃用政策的约束。

  • 更新了 ineligibleAccount 错误的定义（该错误可由 comments.insert、comments.update、commentThreads.insert 或 commentThreads.update 方法返回），以反映当用于授权 API 请求的 YouTube 账号尚未与用户的 Google 账号合并时，会发生该错误。

2016 年 4 月 20 日

此更新包含以下更改：

  • channels.update 方法的 part 参数的定义已更新，以说明 localizations 也是该参数的有效值。

  • “使用入门”指南的配额使用情况部分已更新，其中添加了指向 Google 开发者控制台的链接，您可以在该控制台中查看实际配额和配额使用情况。

2016 年 3 月 16 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • channelBanner 资源文档已更新，其中指出上传的频道横幅图片的建议尺寸为 2560 像素 x 1440 像素。最小尺寸（2048 x 1152 像素）未发生变化。

    • channel 资源的新 snippet.customUrl 属性用于标识与频道相关联的自定义网址。（并非所有频道都有自定义网址。）YouTube 帮助中心介绍了获取自定义网址的资格要求以及如何设置该网址。

    • channel 资源的 brandingSettings.watch 对象及其所有子属性已被弃用。

    • 对 search.list 请求的 API 响应现在包含 regionCode 属性。该属性用于标识搜索查询所用的地区代码。区域代码用于指示 API 返回指定国家/地区的搜索结果。

      该属性值是用于标识区域的双字母 ISO 国家/地区代码。i18nRegions.list 方法会返回受支持区域的列表。默认值为 US。如果指定了不受支持的地区，YouTube 仍可能会选择其他地区（而非默认值）来处理查询。

    • videoAbuseReportReason 资源的 snippet.label 和 snippet.secondaryReasons[].label 属性的定义已更新，以说明这些属性包含滥用行为举报原因的本地化标签文本。

      此外，videoAbuseReportReasons.list 方法现在支持 hl 参数，该参数用于指定 API 响应中标签文本应使用的语言。默认形参值为 en_US。

    • video 资源的新 contentDetails.contentRating.ecbmctRating 属性用于标识视频在土耳其文化和旅游部评估和分类委员会的分级。

      此外，其他分级系统的 API 属性支持以下新属性值：

      • contentDetails.contentRating.fpbRating（南非）
        评分：10；属性值：fpb10
      • contentDetails.contentRating.moctwRating（台湾）
        分级：R-12；属性值：moctwR12
      • contentDetails.contentRating.moctwRating（台湾）
        分级：R-15；属性值：moctwR15

    • video 资源的 liveStreamingDetails.activeLiveChatId 属性包含与视频关联的有效实时聊天的 ID。仅当视频是当前正在直播且已启用实时聊天的直播时，才会显示相应属性值。广播结束后，实时聊天结束，系统不再为相应视频返回该属性。

    • video 资源的 status.rejectionReason 属性支持新的属性值 legal。

  • 该 API 支持以下新错误：

    错误类型 错误详情 说明
    badRequest (400) notEditable channelSections.insert、channelSections.update 和 channelSections.delete 方法会返回此错误，以表明无法创建、更新或删除指定的频道版块。
    badRequest (400) styleRequired channelSections.insert 和 channelSections.update 方法会返回此错误，以表明 API 请求中提交的 channelSection 资源必须为 snippet.style 属性指定值。
    badRequest (400) typeRequired channelSections.insert 和 channelSections.update 方法会返回此错误，以表明 API 请求中提交的 channelSection 资源必须为 snippet.type 属性指定值。
    badRequest (400) processingFailure commentThreads.list 方法会返回此错误，以表明 API 服务器未能成功处理请求。虽然这可能是暂时性错误，但通常表示请求的输入无效。检查请求正文中的 commentThread 资源结构，确保其有效。
    forbidden (403) commentsDisabled commentThreads.list 方法会返回此错误，以表明由 videoId 参数标识的视频已停用评论。
    badRequest (400) commentTextTooLong commentThreads.insert 方法会返回此错误，以表明要插入的 comment 资源的 snippet.topLevelComment.snippet.textOriginal 属性包含的字符过多。
    invalidValue (400) videoAlreadyInAnotherSeriesPlaylist playlistItems.insert 方法会返回此错误，以表明您尝试添加到播放列表中的视频已在另一系列播放列表中。如需详细了解系列播放列表，请访问 YouTube 帮助中心。
    badRequest (400) subscriptionForbidden subscriptions.insert 方法会返回此错误，以表明您已达到订阅数量上限，或者您最近创建的订阅过多。在后一种情况下，您可以过几个小时后重试请求。
    badRequest (400) invalidCategoryId videos.update 方法会返回此错误，以表明上传的 video 资源中的 snippet.categoryId 属性指定了无效的类别 ID。使用 videoCategories.list 方法检索支持的类别。
    badRequest (400) invalidDescription videos.update 方法会返回此错误，以表明上传的 video 资源中的 snippet.description 属性指定了无效值。
    badRequest (400) invalidPublishAt videos.update 方法会返回此错误，以表明上传的 video 资源中的 status.publishAt 属性指定了无效的预定发布时间。
    badRequest (400) invalidRecordingDetails videos.update 方法会返回此错误，以表明上传的 video 资源中的 recordingDetails 对象指定了无效的录制详细信息。
    badRequest (400) invalidTags videos.update 方法会返回此错误，以表明上传的 video 资源中的 snippet.tags 属性指定了无效值。
    badRequest (400) invalidTitle videos.update 方法返回此错误，表示上传的 video 资源中的 snippet.title 属性指定了无效或空白的视频标题。
    badRequest (400) invalidVideoMetadata videos.update 方法会返回此错误，以表明请求元数据无效。如果请求更新了 video 资源的 snippet 部分，但未同时为 snippet.title 和 snippet.categoryId 属性设置值，则会发生此错误。

2015 年 12 月 18 日

根据欧盟 (EU) 法律规定，您必须向欧盟境内的最终用户披露相关信息并征求他们的意见。因此，对于欧盟境内的最终用户，您必须遵守《欧盟地区用户意见征求政策》。我们已在 YouTube API 服务条款中添加了有关此要求的通知。

2015 年 11 月 19 日

该 API 现在支持为 playlist 和 video 资源的 snippet.title 和 snippet.description 属性、channelSection 资源的 snippet.title 属性以及 channel 资源的 snippet.description 属性设置和检索本地化文本。

  • 设置本地化的商品名和说明

    在为资源调用 insert 或 update 方法时，您可以为该资源设置本地化值。如需为资源设置本地化值，请执行以下两项操作：

    • 确保为资源的 snippet.defaultLanguage 属性设置了值。该属性用于标识资源 snippet.title 和 snippet.description 属性的语言。其值可以是任意受支持的应用语言或大多数其他 ISO 639-1:2002 语言代码。例如，如果您上传的视频的标题和说明均为英文，则应将 snippet.defaultLanguage 属性设置为 en。

      更新 channel 资源的注意事项：如需为 channel 资源设置 snippet.defaultLanguage 属性，您实际上需要更新 brandingSettings.channel.defaultLanguage 属性。

    • 将 localizations 对象添加到您要更新的资源。每个对象键都是一个字符串，用于标识应用语言或 ISO 639-1:2002 语言代码，并且每个键都映射到一个包含相应资源的本地化标题（和说明）的对象。

      以下代码段示例将资源的默认语言设置为英语。它还会向视频添加本地化的德语和西班牙语标题及说明：

      {
  "kind": "youtube#video",
  ...
  "snippet": {
    "title": "Playing soccer",
    "description": "We play soccer in the park on Sundays.",
    "defaultLanguage": "en",
    ...
  },
  "localizations":
    "de": {
      "title": "Fußball spielen",
      "description": "Wir spielen Fußball im Park am Sonntag"
    },
    "es": {
      "title": "Jugar al fútbol",
      "description": "Nosotros jugamos fútbol en el parque los domingos",
    }
  }
}

      • 重要提示：请注意，更新资源的本地化数据时，您的 API 请求必须包含所有现有的本地化版本的数据。例如，如果您随后发送请求，要求向上述示例中的视频添加葡萄牙语数据，则该请求需要包含德语、西班牙语和葡萄牙语的本地化数据。

  • 检索本地化值

    该 API 支持两种检索资源本地化值的方式：

    • 将 hl 参数添加到 channels.list、channelSections.list、playlists.list 或 videos.list 请求中，以检索特定应用语言（YouTube 网站支持该语言）的本地化数据。如果该语言有本地化的资源详情，则资源的 snippet.localized 对象将包含本地化的值。不过，如果没有本地化详细信息，snippet.localized 对象将包含资源默认语言的资源详细信息。

      例如，假设 videos.list 请求检索到了上述视频的数据，其中包含本地化的德语和西班牙语数据。如果将 hl 参数设置为 de，则资源将包含以下数据：

      {
  "kind": "youtube#video",
  ...
  "snippet": {
    "title": "Playing soccer",
    "description": "We play soccer in the park on Sundays.",
    "defaultLanguage": "en",
    "localized": {
      "title": "Fußball spielen",
      "description": "Wir spielen Fußball im Park am Sonntag"
    }
    ...
  }
}

      不过，如果将 hl 参数设置为 fr，则 snippet.localized 对象将包含英文版名称和说明，因为英语是资源的默认语言，并且没有本地化的法语详细信息。

      重要提示：hl 参数仅支持用于标识 YouTube 网站支持的应用语言的值。如需确定是否有其他语言的本地化文本，您需要检索资源的 localizations 部分并进行过滤，以确定是否存在本地化文本。

      例如，您需要检索完整的本地化列表，以确定是否有阿巴拉契亚英语的本地化文本。

    • 检索资源时，请在 part 参数值中添加 localizations，以检索该资源的所有本地化详细信息。如果您要检索的本地化数据所用的语言不是当前 YouTube 应用语言，则需要使用此方法检索所有本地化数据，然后进行过滤以确定是否存在所需的本地化数据。

  • 与本地化文本值相关的错误

    该 API 还支持以下针对本地化文本值的新错误：

    错误类型 错误详情 说明
    badRequest (400) defaultLanguageNotSetError 此错误表示，尝试为资源插入或更新 localizations 对象的请求失败，原因是未为相应资源设置 snippet.defaultLanguage 属性。channels.update、channelSections.insert、channelSections.update、playlists.insert、playlists.update、videos.insert 和 videos.update 方法支持此错误。
    badRequest (400) localizationValidationError 此错误表示资源 localizations 对象中的某个值未能通过验证。例如，如果对象包含无效的语言代码，则可能会出现此错误。channels.update、channelSections.insert、channelSections.update、playlists.insert 和 playlists.update 方法支持此错误。

2015 年 11 月 4 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • search.list 方法的 order 参数已更新，以说明如果您按 viewCount 对直播进行排序，则 API 结果会按直播仍在进行时的并发观看者人数进行排序。

    • search.list 方法的 relatedToVideoId 参数已更新，现在会注明：如果设置了该参数，则唯一支持的其他参数为 part、maxResults、pageToken、regionCode、relevanceLanguage、safeSearch、type（必须设置为 video）和 fields。此更新并不表示 API 行为发生了变化。

    • video 资源的 snippet.publishedAt 属性的定义已更新，指出该属性值（用于指定视频的发布日期和时间）可能与视频的上传时间不同。例如，如果某个视频在上传时设为私享视频，之后又改为公开视频，则相应属性值会指定该视频改为公开视频的时间。更新后的定义还说明了私享视频和不公开列出视频的相应值是如何填充的。

      此变更并不表示 API 行为发生了变化。

    • video 资源的 status.publishAt 属性的定义已更新，现在包含以下备注：

      • 如果您在调用 videos.update 方法时设置了此属性的值，则还必须将 status.privacyStatus 属性值设置为 private，即使视频已设为私享也是如此。
      • 如果请求安排在过去某个时间发布视频，则会立即发布。因此，将 status.publishAt 属性设置为过去的日期和时间的效果与将视频的 privacyStatus 从 private 更改为 public 相同。

    • video 资源的 contentDetails.contentRating.cncRating 属性用于指定法国电影分级委员会对相应视频的分级。此属性取代了现已弃用的 contentDetails.contentRating.fmocRating 属性。

    • channel 资源的 brandingSettings.channel.keywords 的定义已更新，以正确反映该属性值包含以空格分隔的字符串列表，而不是之前文档中记录的以英文逗号分隔的列表。此更新并不表示 API 行为发生了变化。

    • thumbnails.set 方法的文档已更新，可准确反映请求的正文包含您要上传并与视频关联的缩略图。请求正文不包含 thumbnail 资源。之前，文档中说明了调用此方法时不应提供请求正文。此更新并不表示 API 行为发生了变化。

    • activity 资源的说明已更新，以反映 activities.list 方法目前不包含与新视频评论相关的资源。资源的 snippet.type 和 contentDetails.comment 也已更新。

  • 新增和更新的错误

    • 该 API 现在支持以下错误：

      错误详情
      activities.insert
      HTTP 响应代码badRequest (400)
      原因invalidMetadata
      说明kind 属性与所提供的 ID 类型不匹配。
      commentThreads.update
      comments.insert
      comments.update
      HTTP 响应代码badRequest (400)
      原因commentTextTooLong
      说明要插入或更新的 comment 资源中的 snippet.topLevelComment.snippet.textOriginal 属性包含的字符过多。
      playlistItems.insert
      playlistItems.update
      HTTP 响应代码forbidden (403)
      原因playlistItemsNotAccessible
      说明相应请求未获得适当的授权，无法插入、更新或删除指定的播放列表项。
      playlists.delete
      playlists.insert
      playlists.update
      HTTP 响应代码badRequest (400)
      原因playlistForbidden
      说明此操作已被禁止，或者请求未获得适当的授权。
      search.list
      HTTP 响应代码badRequest (400)
      原因invalidLocation
      说明location 和/或 locationRadius 参数值的格式不正确。
      search.list
      HTTP 响应代码badRequest (400)
      原因invalidRelevanceLanguage
      说明relevanceLanguage 参数值的格式不正确。
      subscriptions.insert
      HTTP 响应代码badRequest (400)
      原因subscriptionForbidden
      说明 如果满足以下任一条件，则会发生此错误：
      • 您尝试创建的订阅已存在
      • 您已达到订阅数量上限
      • 您正尝试订阅自己的频道，但此操作不受支持。
      • 您最近创建的订阅过多，需要等待几个小时才能重试该请求。
      videos.update
      HTTP 响应代码badRequest (400)
      原因invalidDefaultBroadcastPrivacySetting
      说明相应请求尝试为默认广播设置无效的隐私设置。

2015 年 8 月 28 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • video 资源的 statistics.favoriteCount 属性已被弃用。

      根据我们的弃用政策，此属性将在本公告发布后至少一年内继续包含在 video 资源中。不过，该属性值现在始终设置为 0。

2015 年 8 月 7 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • video 资源的 snippet.tags[] 属性的定义已更新，以提供有关 API 服务器如何计算属性值长度的更多信息。请注意，此更新并不表示 API 的行为发生了变化。

      具体而言，该定义现在说明，如果标记包含空格，API 服务器会像处理用英文引号括起来的标记值一样处理该标记值，并且英文引号会计入字符数限制。因此，就字符数限制而言，标记“Foo-Baz”包含 7 个字符，而标记“Foo Baz”包含 9 个字符。

    • commentThreads.insert 方法不再支持 shareOnGooglePlus 参数，该参数之前用于指示是否还应将评论和对该评论的回复发布到评论者的 Google+ 个人资料中。如果请求提交了该参数，API 服务器会忽略该参数，但会正常处理请求。

2015 年 6 月 18 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • commentThreads.list 方法的新 order 参数用于指定 API 响应应列出评论线程的顺序。您可以按时间或相关性对帖子串进行排序。默认行为是按时间顺序排列。

    • video 资源的新 snippet.defaultAudioLanguage 属性用于指定视频的默认音轨中使用的语言。

    • 更新了 video 资源的 contentDetails.licensedContent 属性的定义，明确指出内容必须最初上传到与 YouTube 内容合作伙伴相关联的频道，然后由该合作伙伴提出版权主张。这并不表示实际 API 行为发生了变化。

    • captions.delete、captions.download、captions.insert、captions.list 和 captions.update 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。使用该方法的请求还需要通过提供对 https://www.googleapis.com/auth/youtubepartner 范围的访问权限的令牌进行授权。

  • 新增和更新的错误

    • 该 API 现在支持以下错误：

      错误详情
      videos.rate
      HTTP 响应代码badRequest (400)
      原因emailNotVerified
      说明用户必须先验证自己的电子邮件地址，然后才能对视频进行评分。
      videos.rate
      HTTP 响应代码badRequest (400)
      原因videoPurchaseRequired
      说明只有租借了视频的用户才能为租借的视频评分。

    • subscriptions.delete 和 subscriptions.insert 方法不再支持 accountClosed 和 accountSuspended 错误。

2015 年 4 月 27 日

此更新包含以下更改：

  • 新资源和方法

    • 新的 videoAbuseReportReason 资源包含有关视频因包含滥用内容而被标记的原因的信息。您可以使用 videoAbuseReportReasons.list 方法检索视频可能被标记的所有原因的列表。

    • 新的 videos.reportAbuse 方法提供了一种实际标记包含滥用内容的视频的方式。请求正文包含一个 JSON 对象，用于指定要标记的视频以及该视频被认为包含滥用内容的原因。有效原因可从上述 videoAbuseReportReason.list 方法中获取。

      我们还更新了迁移指南，其中包含举报滥用视频的示例。进行此更改后，v3 API 现在支持计划支持的所有 v2 API 功能。迁移指南中还介绍了所有这些功能。

  • 对现有资源和方法的更新

    • search.list 方法的新 forDeveloper 过滤条件参数可将搜索限制为仅检索通过开发者的应用或网站上传的视频。forDeveloper 参数可以与可选的搜索参数（例如 q 参数）搭配使用。

      对于此功能，每个上传的视频都会自动添加与开发者在 Google Developers Console 中的应用相关联的项目编号。

      当后续搜索请求将 forDeveloper 参数设置为 true 时，API 服务器会使用该请求的授权凭据来识别开发者。因此，开发者可以将结果限制为通过开发者自己的应用或网站上传的视频，但不能限制为通过其他应用或网站上传的视频。

      新功能提供的功能与 v2 API 支持的开发者标记功能类似，但并不完全相同。

    • channel 资源的新 snippet.country 属性可让频道所有者将其频道与特定国家/地区相关联。

      注意：如需为 channel 资源设置 snippet.country 属性，您实际上需要更新 brandingSettings.channel.country 属性。

    • 该 API 现在支持针对 channelSection 资源进行定位。通过频道版块定位，您可以限制只有符合特定条件的用户才能看到某个内容版块。

      该 API 公开了三种定位选项。用户必须满足频道版块的所有定位设置，才能看到该版块。

    • 已更正 video 资源的 contentDetails.duration 属性的定义，以反映该值可以表示小时、天数等。

    • channelSections.delete、playlistItems.delete、playlists.delete、subscriptions.delete 和 videos.delete 方法的文档已更正，以反映这些方法在成功时都会返回 HTTP 204 响应代码 (No Content)。

  • 新增和更新的错误

    • 该 API 现在支持以下错误：

      错误类型 错误详情 说明
      badRequest (400) targetInvalidCountry 如果插入的 channelSection 资源包含 targeting.countries[] 属性的无效值，channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) targetInvalidLanguage 如果插入的 channelSection 资源包含 targeting.languages[] 属性的无效值，channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) targetInvalidRegion 如果插入的 channelSection 资源包含 targeting.regions[] 属性的无效值，channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) operationNotSupported 如果 API 用户无法插入评论来回复由 snippet.parentId 属性标识的顶级评论，comments.insert 方法会返回此错误。在 commentThread 资源中，snippet.canReply 属性用于指明当前查看者是否可以回复相应帖子。
      badRequest (400) invalidChannelId 如果请求中的 channelId 参数指定了无效的渠道 ID，search.list 方法会返回此错误。
      badRequest (400) subscriptionForbidden 如果 API 用户尝试订阅自己的频道，subscriptions.insert 方法会返回此错误。

    • captions.update 方法不再支持 invalidMetadata 和 videoNotFound 错误。

2015 年 4 月 16 日

此更新包含以下更改：

  • 我们更新了迁移指南，其中说明了如何迁移仍在使用 v2 API 的评论功能的应用。

    该指南还重点介绍了 v2 API 不支持但 v3 API 支持的几项评论功能。其中包括：

    • 检索有关频道的评论
    • 检索与频道相关的所有评论串，这意味着 API 响应可以包含有关频道或其任何视频的评论。
    • 更新评论的文字内容
    • 将评论标记为垃圾评论
    • 设置评论的审核状态

  • 我们更新了订阅推送通知指南，以反映通知仅推送到 Google PubSubHubBub 中心，而不会像之前所说的那样也推送到 Superfeedr 中心。

2015 年 4 月 9 日

此更新包含以下更改：

  • 借助该 API 的新 commentThread 和 comment 资源，您可以检索、插入、更新、删除和审核评论。

    • commentThread 资源包含有关 YouTube 评论串的信息，该评论串包含一条顶级评论以及对该评论的回复（如果有）。commentThread 资源可以表示有关视频或频道的评论。

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

      该 API 支持以下针对 commentThread 资源的方法：

    • comment 资源包含有关单个 YouTube 评论的信息。comment 资源可以表示有关视频或频道的评论。此外，该评论可以是顶级评论，也可以是对顶级评论的回复。

      该 API 支持以下针对 comment 资源的方法：

    请注意，如 2015 年 4 月 2 日的修订历史记录中所述，API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围是调用 comments.insert、comments.update、comments.markAsSpam、comments.setModerationStatus、comments.delete、commentThreads.insert 和 commentThreads.update 方法所必需的。

  • 新的订阅推送通知指南介绍了该 API 通过 PubSubHubBub（一种适用于可通过网络访问的资源的服务器到服务器发布/订阅协议）对推送通知提供的新支持。当频道执行以下任一操作时，您的 PubSubHubBub 回调服务器可以接收 Atom Feed 通知：

    • 上传视频
    • 更新视频的标题
    • 更新视频的说明

  • 我们还更新了迁移指南，其中说明了新增的推送通知支持。不过，由于 v2 API 支持许多 v3 API 不支持的其他类型的推送通知，因此该指南的已弃用部分仍列出了对 PubSubHubBub 的支持。

  • API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围现在是之前支持 https://www.googleapis.com/auth/youtube 范围的任何 API 方法的有效范围。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest (400) invalidRating 如果请求中包含 rating 参数的意外值，videos.rate 方法会返回此错误。

  • subscriptions.insert 方法不再支持 subscriptionLimitExceeded 错误，该错误之前表示与请求关联的订阅者已超出订阅速率限制。

2015 年 4 月 2 日

此更新包含以下更改：

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

    该 API 支持用于列出、插入、更新、下载和删除字幕轨的方法。

  • 我们还更新了迁移指南，其中说明了如何迁移仍在使用 v2 API 中的字幕功能的应用。

  • 该 API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围要求与 API 服务器的通信通过 SSL 连接进行。

    此新范围授予的访问权限与 https://www.googleapis.com/auth/youtube 范围授予的访问权限相同。事实上，这两个范围在功能上是相同的，因为 YouTube API 服务器只能通过 HTTPS 端点访问。因此，即使 https://www.googleapis.com/auth/youtube 范围不需要 SSL 连接，实际上也没有其他方式来发出 API 请求。

    调用所有 caption 资源的方法都需要使用此新范围。

2015 年 3 月 11 日

此更新包含以下更改：

  • YouTube Data API (v3) 迁移指南包含一个名为 v3 API 中的新增功能的新标签页，其中列出了 v3 API 支持但 v2 API 不支持的功能。之前，本指南的其他标签页中也列出了这些功能，现在也是如此。例如，有关如何更新频道视频内宣传广告系列数据的新功能也列在频道（个人资料）标签页下。

  • 我们已更新 YouTube Data API (v3) 迁移指南，其中指出 v3 API 将支持以下 v2 API 功能：

  • 我们已更新 YouTube Data API (v3) 迁移指南，其中指出 v3 API 将不支持以下 v2 API 功能：

    • 检索视频推荐 - v3 API 不会检索仅包含针对当前 API 用户推荐的视频的列表。不过，您可以使用 v3 API 通过调用 activities.list 方法并将 home 参数值设置为 true 来查找推荐视频。

      在 API 响应中，如果资源的 snippet.type 属性的值为 recommendation，则该资源对应于推荐视频。在这种情况下，contentDetails.recommendation.reason 和 contentDetails.recommendation.seedResourceId 属性将包含有关视频推荐原因的信息。请注意，我们不保证响应中会包含特定数量的推荐视频。

    • 检索频道建议

    • 检索新订阅的视频 - v3 API 不会检索仅包含 API 用户订阅的频道最近上传的视频的列表。不过，您可以使用 v3 API 通过调用 activities.list 方法并将 home 参数值设置为 true 来查找新的订阅视频。

      在 API 响应中，如果资源的 snippet.type 属性的值为 upload，则该资源对应于新的订阅视频。请注意，我们不保证响应中会包含特定数量的新订阅视频。

    • 支持 RSS Feed

    • 针对 Feed 更新的推送通知 - v2 API 支持使用简单更新协议 (SUP) 或 PubSubHubbub 来监控 YouTube 用户的用户活动 Feed，并提供推送通知。系统会针对以下情况提供通知：订阅新频道、视频被评分、分享、标记为收藏、评论或上传。

      v3 API 将支持使用 PubSubHubbub 协议的推送通知，但通知仅涵盖视频上传以及视频标题或视频说明的更新。

    • 频道位置 - v2 API 使用 <yt:location> 标记来标识用户在频道的 YouTube 公开个人资料中输入的位置。虽然一些开发者使用此字段将频道与特定国家/地区相关联，但该字段的数据无法始终用于此目的。

    • 设置或检索开发者标记 - v2 API 支持在上传视频时将关键字或开发者标记与视频相关联。开发者标记不会向 YouTube 用户显示，但视频所有者可以检索与特定开发者标记匹配的视频。

      v3 API 将提供类似但不完全相同的功能。具体而言，开发者将能够搜索自己应用上传的视频。对于此功能，每个上传的视频都会自动添加与开发者在 Google Developers Console 中的应用相关联的项目编号。然后，开发者使用同一项目编号搜索视频。

    • 按发布日期、观看次数或评分列出视频 - 在 v2 API 中，您可以使用 orderby 参数按位置、时长、发布日期、标题和其他几个值对播放列表中的视频进行排序。在 v3 API 中，播放列表项通常按位置升序排序，没有其他排序选项。

      但也有一些例外情况。对于以下类型的播放列表，新上传的视频、收藏的视频、点赞的视频或最近观看的视频会自动添加为第一个项目（snippet.position=0）。因此，这些列表实际上是根据商品添加到列表中的时间从最新到最旧排序的。

      • 用户上传
      • 收藏的视频
      • 顶过的视频
      • 观看记录

      不过请注意，添加到“稍后观看”播放列表的新内容会添加到该列表的末尾，因此该列表实际上是按从旧到新的顺序排序的。

    • 批量处理 - v3 API 支持 v2 API 曾支持的批量处理使用情形之一。v3 API 的 channels.list、channelSections.list、guideCategories.list、playlistItems.list、playlists.list、subscriptions.list、videoCategories.list 和 videos.list 方法均支持 id 参数，该参数可用于指定以英文逗号分隔的 ID 列表（视频 ID、频道 ID 等）。使用这些方法，您可以通过单个请求检索多个资源的列表。

    进行这些更改后，该指南现在可以识别旧版 (v2) API 中支持的所有功能，这些功能将在当前 API 版本 (v3) 中被弃用。

2015 年 3 月 4 日

此更新包含以下更改：

  • channelSections.delete 和 channelSections.update 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。

  • 以下属性及其子属性已被弃用：

    • brandingSettings.image.backgroundImageUrl
    • brandingSettings.image.largeBrandedBannerImageImapScript
    • brandingSettings.image.largeBrandedBannerImageUrl
    • brandingSettings.image.smallBrandedBannerImageImapScript
    • brandingSettings.image.smallBrandedBannerImageUrl

    注意：这些属性均不受 API 弃用政策的约束。

  • video 资源的新 contentDetails.contentRating.contentDetails.contentRating.djctqRatingReasons 属性用于标识说明视频获得 DJCQT（巴西）分级的原因。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    notFound (404) channelNotFound 如果请求的 id 参数指定的渠道无法找到，channels.update 方法会返回此错误。
    badRequest (400) manualSortRequiredinvalidValue 如果请求尝试设置播放列表项的位置，但播放列表未使用手动排序，则 playlistItems.insert 和 playlistItems.update 方法会返回此错误。例如，播放列表中的项目可以按日期或热门程度排序。您可以通过从请求正文中发送的资源中移除 snippet.position 元素来解决此错误。如果您希望播放列表项在列表中具有特定位置，则需要先将播放列表的排序设置更新为手动。您可以在 YouTube 视频管理器中调整此设置。
    forbidden (403) channelClosed 如果请求的 channelId 参数指定了已关闭的渠道，playlists.list 方法会返回此错误。
    forbidden (403) channelSuspended 如果请求的 channelId 参数指定了已被中止的频道，playlists.list 方法会返回此错误。
    forbidden (403) playlistForbidden 如果请求的 id 参数不支持相应请求，或者请求未获得适当的授权，playlists.list 方法会返回此错误。
    notFound (404) channelNotFound 如果请求的 channelId 参数指定的渠道无法找到，playlists.list 方法会返回此错误。
    notFound (404) playlistNotFound 如果请求的 id 参数指定的播放列表无法找到，playlists.list 方法会返回此错误。
    notFound (404) videoNotFound 如果请求的 id 参数指定的视频找不到，videos.list 方法会返回此错误。
    badRequest (400) invalidRating 如果请求包含 rating 参数的意外值，videos.rate 方法会返回此错误。

2015 年 3 月 2 日

此更新包含以下更改：

2015 年 1 月 14 日

此更新包含以下更改：

  • 我们更新了 YouTube Data API (v3) 迁移指南，其中说明了如何使用 v3 API 通过 JavaScript 上传视频。（如需了解详情，请参阅上传视频部分。）此功能与 v2 API 支持的基于浏览器的上传功能相当。请注意，迁移指南的这一更改并不反映实际的 API 更改，而是反映了可用于通过客户端 JavaScript 上传视频的新示例代码。

    鉴于 JavaScript 客户端库和 CORS 支持上传视频，迁移指南不再将基于浏览器的上传列为 v3 API 中可能会被弃用的功能。

  • videos.insert 方法的文档已更新，其中包含上述新的 JavaScript 代码示例。我们还更新了 YouTube Data API (v3) 的 JavaScript 代码示例列表。

2014 年 11 月 11 日

此更新包含以下更改：

  • 对 search.list 方法的调用的配额费用已更改为 100 个单位。

    重要提示：在许多情况下，您可以使用其他 API 方法以更低的配额成本检索信息。例如，假设您想查找上传到 GoogleDevelopers 频道的视频，可以采用以下两种方式。

    • 配额费用：100 个单位

      调用 search.list 方法并搜索 GoogleDevelopers。

    • 配额费用：6 个单位

      调用 channels.list 方法以查找正确的频道 ID。将 forUsername 参数设置为 GoogleDevelopers，并将 part 参数设置为 contentDetails。在 API 响应中，contentDetails.relatedPlaylists.uploads 属性用于指定频道已上传视频的播放列表 ID。

      然后，调用 playlistItems.list 方法，并将 playlistId 参数设置为捕获的 ID，将 part 参数设置为 snippet。

2014 年 10 月 8 日

此更新包含以下更改：

  • channel 资源包含两个新属性：

    • status.longUploadsStatus 属性用于指明频道是否符合上传时长超过 15 分钟的视频的条件。仅当频道所有者授权了 API 请求时，系统才会返回此属性。有效的属性值包括：

      • allowed - 频道可以上传时长超过 15 分钟的视频。
      • eligible - 频道可以上传时长超过 15 分钟的视频，但必须先启用相应功能。
      • disallowed - 相应频道无法上传时长超过 15 分钟的视频，或不符合上传此类视频的条件。

      如需详细了解这些值，请参阅相应属性的定义。YouTube 帮助中心还提供了有关此功能的更详细信息。

    • invideoPromotion.useSmartTiming 属性用于指明频道的宣传广告系列是否使用“智能定时”。此功能会尝试在视频中更可能吸引用户点击且不太可能打断观看体验的时间点展示宣传内容。此功能还会选择一个宣传广告在每个视频中展示。

  • video 资源的 snippet.title 和 snippet.categoryId 属性的定义均已更新，以明确 API 处理对 videos.update 方法的调用的方式。如果您调用该方法来更新 video 资源的 snippet 部分，则必须为这两个属性设置值。

    如果您尝试更新 video 资源的 snippet 部分，但未为这两个属性设置值，则 API 会返回 invalidRequest 错误。相应错误的说明也已更新。

  • video 资源的 contentDetails.contentRating.oflcRating 属性用于标识新西兰电影和文学作品分级办公室给出的视频分级，现在支持两个新分级：oflcRp13 和 oflcRp16。这些值分别对应于 RP13 和 RP16 分级。

  • channelBanners.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest bannerAlbumFull 频道所有者的 YouTube 频道横幅图片相册中的图片过多。频道所有者应前往 http://photos.google.com，找到相册页面，然后从该相册中移除一些图片。

2014 年 9 月 12 日

此更新包含以下更改：

  • 对 search.list 方法的调用的配额费用已从 1 个单位更改为 2 个单位，此外还需支付指定资源部分的费用。

2014 年 8 月 13 日

此更新包含以下更改：

  • subscriptions.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest subscriptionLimitExceeded 相应请求所标识的订阅者已超出订阅速率限制。您可以在几小时后尝试订阅更多内容。

2014 年 8 月 12 日

此更新包含以下更改：

  • 新指南将应用迁移到 YouTube Data API (v3) 介绍了如何使用 YouTube Data API (v3) 来执行 YouTube Data API (v2) 中提供的功能。旧版 API 已于 2014 年 3 月 4 日正式弃用。本指南旨在帮助您将仍在使用 v2 API 的应用迁移到最新 API 版本。

2014 年 7 月 8 日

此更新包含以下更改：

  • playlists.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest maxPlaylistExceeded 如果频道已达到允许的播放列表数量上限，而无法创建播放列表，则会发生此错误。

2014 年 6 月 18 日

此更新包含以下更改：

2014 年 5 月 28 日

此更新包含以下更改：

  • search.list 方法现在支持 location 和 locationRadius 参数，可让您搜索与地理位置相关联的视频。请求必须为这两个参数指定值，才能根据地理位置检索结果；如果请求仅包含这两个参数中的一个，API 将返回错误。

    • location 参数用于指定圆形地理区域中心的纬度/经度坐标。

    • locationRadius 参数用于指定与视频相关联的位置与区域中心之间的最大距离，以便视频仍能包含在搜索结果中。

2014 年 5 月 13 日

此更新包含以下更改：

  • channel 资源的 invideoPromotion.items[] 属性已更新，其中指出您通常只能为频道设置一个推广商品。如果您尝试插入的推广商品过多，API 将返回 tooManyPromotedItems 错误，该错误具有 HTTP 400 状态代码。

  • channelSection 资源现在可以包含有关几种新类型的精选内容的信息。channelSection 资源的 snippet.type 属性现在支持以下值：

    • postedPlaylists - 频道所有者发布到频道活动动态中的播放列表
    • postedVideos - 频道所有者发布到频道活动动态中的视频
    • subscriptions - 频道所有者已订阅的频道

  • video 资源的新 contentDetails.contentRating.ifcoRating 属性用于标识视频从爱尔兰电影分级办公室获得的分级。

  • 更新了 watermark 资源的 position.cornerPosition 属性的定义，指出水印始终显示在播放器的右上角。

  • 更新了 search.list 方法的 q 参数的定义，指出搜索字词可以使用布尔值 NOT (-) 运算符来排除与特定搜索字词相关联的视频。该值还可以使用布尔 OR (|) 运算符来查找与多个搜索字词中的任一字词相关联的视频。

  • 更新了 API 响应中针对 search.list 调用的 pageInfo.totalResults 属性的定义，指出该值是近似值，可能无法表示确切的值。此外，最大值为 1,000,000。您不应使用此值创建分页链接。请改为使用 nextPageToken 和 prevPageToken 属性值来确定是否显示分页链接。

  • watermarks.set 和 watermarks.unset 方法已更新，以反映 API 会针对成功向这些方法发出的请求返回 HTTP 204 响应代码。

2014 年 5 月 2 日

此更新包含以下更改：

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

    该 API 支持一种用于列出受支持的应用语言的方法。在调用 videoCategories.list 和 guideCategories.list 等 API 方法时，支持的语言可用作 hl 参数的值。

  • 新的 i18nRegion 资源用于标识 YouTube 用户可以选择作为首选内容区域的地理区域。内容区域也可以称为内容语言区域。对于 YouTube 网站，系统可能会根据启发式方法（例如 YouTube 网域或用户的 IP 位置）自动选择内容区域，用户也可以从 YouTube 网站页脚手动选择所需的内容区域。

    该 API 支持一种用于列出受支持的内容区域的方法。在调用 search.list、videos.list、activities.list 和 videoCategories.list 等 API 方法时，支持的地区代码可用作 regionCode 参数的值。

2014 年 4 月 7 日

此更新包含以下更改：

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

    该 API 支持用于列出、插入、更新或删除频道版块的方法。您可以指定特定频道 ID 或指定唯一频道板块 ID 的列表，检索经过身份验证的用户的频道的频道板块列表。

    我们还更新了错误文档，其中介绍了 API 专门针对这些新方法支持的错误消息。

  • 更新了 video 资源的 fileDetails 对象的定义，以说明只有当视频的 processingDetails.fileDetailsAvailability 属性的值为 available 时，才会返回该对象。

    同样，video 资源的 suggestions 对象的定义已更新，以说明仅当视频的 processingDetails.tagSuggestionsAvailability 属性或其 processingDetails.editorSuggestionsAvailability 属性的值为 available 时，才会返回该对象。

  • 更新了 videos.insert 和 videos.update 方法的文档，以反映在调用这些方法时可以设置 status.publishAt 属性。

  • 更新了 channel 资源的 invideoPromotion 对象的定义，以说明该对象只能由频道的所有者检索。

  • 更新了 videos.rate 方法的参数列表，以反映该方法实际上不支持 onBehalfOfContentOwner 参数。这是一个文档错误，因为设置此参数的 videos.rate 请求会返回 500 错误。

2014 年 3 月 31 日

此更新包含以下更改：

2014 年 3 月 13 日

此更新包含以下更改：

  • 该 API 现在支持 channel 资源的 contentOwnerDetails 部分。新部分包含与已关联到频道的 YouTube 合作伙伴相关的频道数据，包括与频道关联的内容所有者的 ID，以及内容所有者与频道关联的日期和时间。请注意，此新部分不受弃用政策的约束。

  • 文档现在列出了以下属性支持的最大字符长度：

    资源 属性 最大长度
    channel invideoPromotion.items[].customMessage 40 个字符
    video snippet.title 100 个字符
    video snippet.description 5000 字节
    video snippet.tags 500 个字符。请注意，属性值是一个列表，列表项之间的英文逗号计入限制。

  • channel 资源的 brandingSettings.watch.featuredPlaylistId 属性已被弃用。如果您尝试设置其值，API 将返回错误。

  • 以下 video 资源属性已添加到在插入或更新视频时可以设置的值列表中：

  • 错误文档现在针对每种错误类型指定了 HTTP 响应代码。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest (400) invalidCriteria 如果请求指定的过滤条件参数无法搭配使用，channels.list 方法会返回此错误。
    badRequest (400) channelTitleUpdateForbidden 如果您尝试更新频道的 brandingSettings 部分并更改 brandingSettings.channel.title 属性的值，channels.update 方法会返回此错误。（请注意，如果您省略该属性，API 不会返回错误。）
    badRequest (400) invalidRecentlyUploadedBy 如果 invideoPromotion.items[].id.recentlyUploadedBy 属性指定的频道 ID 无效，channels.update 方法会返回此错误。
    badRequest (400) invalidTimingOffset 如果 invideoPromotion 部分指定了无效的时间偏移量，channels.update 方法会返回此错误。
    badRequest (400) tooManyPromotedItems 如果 invideoPromotion 部分指定的推广商品数量超过允许的数量，channels.update 方法会返回此错误。
    forbidden (403) promotedVideoNotAllowed 如果 invideoPromotion.items[].id.videoId 属性指定的视频 ID 无法找到或无法用作推广的商品，channels.update 方法会返回此错误。
    forbidden (403) websiteLinkNotAllowed 如果 invideoPromotion.items[].id.websiteUrl 属性指定的网址不允许使用，channels.update 方法会返回此错误。
    required (400) requiredTimingType 如果请求未指定 YouTube 应何时显示推广商品的默认时间设置，channels.update 方法会返回此错误。
    required (400) requiredTiming channels.update 方法必须为每个推广的商品指定一个 invideoPromotion.items[].timing 对象。
    required (400) requiredWebsiteUrl channels.update 方法必须为每个推广的商品指定 invideoPromotion.items[].id.websiteUrl 属性。
    badRequest (400) invalidPublishAt 如果请求元数据指定的预定发布时间无效，videos.insert 方法会返回此错误。

2014 年 3 月 4 日

此更新包含以下更改：

2013 年 12 月 5 日

此更新包含以下更改：

  • search.list 方法的文档已更新，可正确反映在提交搜索请求时，您无需为正好一个过滤参数指定值。您可以为零个或一个过滤参数设置值。

  • search.list 方法的参数定义已更新，现在指出，如果您还为以下任一参数指定了值，则必须将 type 参数的值设置为 video：

    • eventType
    • videoCaption
    • videoCategoryId
    • videoDefinition
    • videoDimension
    • videoDuration
    • videoEmbeddable
    • videoLicense
    • videoSyndicated
    • videoType

  • 上传的频道横幅图片的最小尺寸已降至 2048 像素 x 1152 像素。（之前，最小尺寸为 2120 像素 x 1192 像素。）此外，请注意 channel 资源文档指定了通过该 API 投放的所有横幅图片的最大尺寸。例如，电视应用的 brandingSettings.image.bannerTvImageUrl 图片的最大尺寸为 2120 像素 x 1192 像素，但实际图片可能为 2048 像素 x 1152 像素。YouTube 帮助中心还提供了有关如何优化频道图片以在不同类型的设备上显示的更多指南。

  • 我们更新了多个 channel 资源属性定义，以反映以下信息：

    • brandingSettings.channel.description 属性的值的长度上限为 1,000 个字符。
    • brandingSettings.channel.featuredChannelsTitle 属性的长度上限为 30 个字符。
    • brandingSettings.channel.featuredChannelsUrls[] 属性现在最多可列出 100 个频道。
    • 如果设置了 brandingSettings.channel.unsubscribedTrailer 属性值，则该值必须指定频道所有者拥有的公开或不公开列出的视频的 YouTube 视频 ID。

  • channels.update 方法现在支持更新 invideoPromotion.items[].promotedByContentOwner 属性。该属性用于指明在显示宣传广告时是否显示内容所有者的名称。只有在以下情况下才能设置此属性：使用 onBehalfOfContentOwner 参数代表内容所有者发出设置属性值的 API 请求。

  • playlistItems.list 和 playlistItems.insert 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。

  • contentDetails.contentRating.acbRating 属性现在可以指定电影的澳大利亚分级委员会 (ACB) 分级，也可以指定儿童电视节目的澳大利亚通信和媒体管理局 (ACMA) 分级。

  • 新的 contentDetails.contentRating.catvRating 和 contentDetails.contentRating.catvfrRating 属性分别用于标识视频在加拿大电视分级制度和魁北克省使用的法语电影分级制度下获得的分级。

  • videoCategory 资源的新 snippet.assignable 属性用于指明更新后的视频或新上传的视频是否可以与相应视频类别相关联。

  • 我们为以下方法添加了代码示例：

2013 年 10 月 24 日

此更新包含以下更改：

  • 该 API 包含两项旨在帮助查找和展示直播内容的附加功能：

    搜索结果中的新 snippet.liveBroadcastContent 属性用于指明视频或频道资源是否包含直播内容。有效的属性值为 upcoming、active 和 none。

    请注意，2013 年 10 月 1 日还发布了另外两项用于识别直播内容的功能：search.list 方法的 eventType 参数和搜索结果的 snippet.liveBroadcastContent 属性。

  • videos.insert 方法现在支持 notifySubscribers 参数，该参数用于指明 YouTube 是否应向订阅相应视频频道的用户发送有关新视频的通知。此参数的默认值为 True，表示会向订阅者发送关于新上传视频的通知。不过，如果频道所有者上传的视频数量较多，可能更倾向于将该值设置为 False，以免向频道订阅者发送有关每部新视频的通知。

  • 调用 channels.update 方法时可修改的属性列表已更新，现在包含 invideoPromotion.items[].customMessage 和 invideoPromotion.items[].websiteUrl 属性。此外，该列表已修改为可识别可修改的 brandingSettings 属性。这些 brandingSettings 属性之前已可修改，因此文档变更并不反映 API 现有功能的变更。

  • playlists.insert、playlists.update 和 playlists.delete 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。

  • playlists.insert 方法现在支持 onBehalfOfContentOwnerChannel 参数，该参数已受其他多种方法支持。

  • video 资源的 contentDetails.contentRating.tvpgRating 属性现在支持值 pg14，该值对应于 TV-14 评分。

  • 已更正搜索结果中 snippet.liveBroadcastContent 属性的定义，以反映 live 是有效的属性值，但 active 不是有效的属性值。

  • video 资源的 contentDetails.contentRating.mibacRating 属性现在支持另外两种分级：

    • mibacVap (VAP) - 儿童应由成人陪同。
    • mibacVm6 (V.M.6) - 必须年满 6 周岁才能观看。
    • mibacVm12 (V.M.12) - 必须年满 12 周岁才能观看。

  • channel 资源的新 invideoPromotion.items[].promotedByContentOwner 属性用于指明在显示宣传广告时是否会显示内容所有者的名称。只有在代表内容所有者发出设置相应值的 API 请求时，才能设置此字段。如需了解详情，请参阅 onBehalfOfContentOwner 参数。

2013 年 10 月 1 日

此更新包含以下更改：

  • channel 资源的新 auditDetails 对象包含多频道网络 (MCN) 在确定是否接受或拒绝特定频道时会评估的频道数据。请注意，任何检索此资源部分的 API 请求都必须提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit 范围的授权令牌。此外，如果 MCN 决定接受或拒绝频道，或者在令牌签发之日起两周内，必须撤消使用该范围的任何令牌。

  • channel 资源的 invideoPromotion.items[].id.type 属性现在支持值 recentUpload，表示推广的商品是指定频道中最近上传的视频。

    默认情况下，该渠道与设置视频内宣传广告数据的渠道相同。不过，您可以将新 invideoPromotion.items[].id.recentlyUploadedBy 属性的值设置为另一个频道的频道 ID，以宣传该频道最近上传的视频。

  • channel 资源包含三个新属性：brandingSettings.image.bannerTvLowImageUrl、brandingSettings.image.bannerTvMediumImageUrl、brandingSettings.image.bannerTvHighImageUrl，用于指定在电视应用中的频道页面上显示的横幅图片的网址。

  • 搜索结果中的新 snippet.liveBroadcastContent 属性用于指明视频或频道资源是否包含直播内容。有效的属性值为 upcoming、active 和 none。

    • 对于 video 资源，值为 upcoming 表示相应视频是尚未开始的直播，而值为 active 表示相应视频是正在进行的直播。
    • 对于 channel 资源，值 upcoming 表示频道有尚未开始的预定广播，而值 acive 表示频道有正在进行的直播。

  • 在 watermark 资源中，targetChannelId 属性已从对象更改为字符串。targetChannelId 属性现在直接指定水印图片所链接到的频道的 YouTube 频道 ID，而不是包含指定该 ID 的子属性。因此，我们移除了相应资源的 targetChannelId.value 属性。

  • thumbnails.set 方法现在支持 onBehalfOfContentOwner 参数，该参数已受其他多种方法支持。

  • search.list 方法现在支持 eventType 参数，该参数可限制搜索结果仅返回有效、即将开始或已完成的广播活动。

  • 新的 contentDetails.contentRating.mibacRating 属性用于标识视频从意大利文化和旅游部获得的评级。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest invalidImage 如果提供的图片内容无效，thumbnails.set 方法会返回此错误。
    forbidden videoRatingDisabled 如果被评级的视频的所有者已针对该视频停用评分功能，videos.rate 方法会返回此错误。

2013 年 8 月 27 日

此更新包含以下更改：

  • 新的 watermark 资源用于标识在指定频道的视频播放期间显示的图片。您还可以指定图片将链接到的目标频道，以及用于确定水印在视频播放期间的显示时间以及显示时长的计时详细信息。

    watermarks.set 方法用于上传和设置频道的水印图片。watermarks.unset 方法用于删除频道的水印图片。

    错误文档介绍了 API 专门针对 watermarks.set 和 watermarks.unset 方法支持的错误消息。

  • channel 资源的新 statistics.hiddenSubscriberCount 属性包含一个布尔值，用于指示频道的订阅人数是否处于隐藏状态。因此，如果频道的订阅人数公开显示，相应属性的值为 false。

  • playlists.list 方法现在支持 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 参数。这两个参数已受其他多种方法支持。

  • videos.list 方法现在支持 regionCode 参数，该参数用于标识应检索排行榜的内容区域。此参数只能与 chart 参数搭配使用。此参数值是 ISO 3166-1 alpha-2 国家/地区代码。

  • error documentation 描述了以下新的常见请求错误，该错误可能会出现在多种 API 方法中：

    错误类型 错误详情 说明
    forbidden insufficientPermissions 为请求提供的 OAuth 2.0 令牌关联的范围不足以访问所请求的数据。

2013 年 8 月 15 日

此更新包含以下更改：

  • channel 资源的 invideoPromotion 对象具有以下新增和更新的属性：

  • subscriptions.list 方法现在支持 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 参数。这两个参数已受其他多种方法支持。

  • 在对 thumbnails.set 请求的 API 响应中，kind 属性值已从 youtube#thumbnailListResponse 更改为 youtube#thumbnailSetResponse。

  • 我们为以下方法添加了代码示例：

    请注意，由于 playlistItems.insert 方法演示的功能现在由 videos.rate 方法处理，因此也移除了 playlistItems.insert 方法的 Python 示例。

  • error documentation 描述了以下新的请求上下文错误，该错误可能会在支持 mine 请求参数的任何 API 方法中发生：

    错误类型 错误详情 说明
    badRequest invalidMine 如果经过身份验证的用户是 YouTube 合作伙伴，则无法在请求中使用 mine 参数。您应移除 mine 参数，通过移除 onBehalfOfContentOwner 参数以 YouTube 用户的身份进行身份验证，或者通过提供 onBehalfOfContentOwnerChannel 参数（如果调用方法支持此参数）以合作伙伴的某个频道的身份进行操作。

2013 年 8 月 8 日

此更新包含以下更改：

2013 年 7 月 30 日

此更新包含以下更改：

  • 在 channelBanner 资源中，kind 属性的值已从 youtube#channelBannerInsertResponse 更改为 youtube#channelBannerResource。此资源会以 channelBanners.insert 请求的响应形式返回。

  • channel 资源的新 brandingSettings.channel.profileColor 属性指定了一种与频道内容相得益彰的醒目颜色。属性值是一个井号 (#)，后跟一个六字符的十六进制字符串，例如 #2793e6。

  • 该 API 现在支持指定订阅是针对频道的所有活动还是仅针对新上传的视频。subscription 资源的新 contentDetails.activityType 属性用于标识订阅者将收到通知的活动类型。有效的属性值为 all 和 uploads。

  • videos.list 方法支持用于检索 YouTube 上最热门视频排行榜的新参数：

    • chart 参数用于标识要检索的图表。目前，唯一支持的值是 mostPopular。请注意，chart 参数是一个过滤参数，这意味着它不能与同一请求中的其他过滤参数（id 和 myRating）一起使用。
    • videoCategoryId 参数用于标识应检索的排行榜所对应的视频类别。此参数只能与 chart 参数搭配使用。默认情况下，排行榜不限于特定类别。

  • video 资源的新 topicDetails.relevantTopicIds[] 属性提供与视频或其内容相关的一系列 Freebase 主题 ID。视频中可能会提及或出现这些主题的内容。

  • video 资源的 recordingDetails.location.elevation 属性已重命名为 recordingDetails.location.altitude，其 fileDetails.recordingLocation.location.elevation 属性已重命名为 fileDetails.recordingLocation.location.altitude。

  • video 资源的 contentDetails.contentRating 对象用于指定视频在各种分级方案（包括 MPAA 分级、TVPG 分级等）下获得的分级。对于每个分级系统，该 API 现在支持一个表示相应视频尚未分级的分级值。请注意，对于 MPAA 分级，“未分级”通常用于标识电影的未剪辑版本，而电影的剪辑版本已获得官方分级。

  • video 资源的新 contentDetails.contentRating.ytRating 属性用于标识有年龄限制的内容。如果 YouTube 认定视频包含不适合未满 18 周岁的用户观看的内容，则该属性的值为 ytAgeRestricted。如果相应属性不存在或属性值为空，则表示相应内容未被标识为受年龄限制的内容。

  • 已弃用 channels.list 方法的 mySubscribers 参数。使用 subscriptions.list 方法及其 mySubscribers 参数可检索经过身份验证的用户的频道的订阅者列表。

  • channelBanners.insert、channels.update、videos.getRating 和 videos.rate 方法现在均支持 onBehalfOfContentOwner 参数。该参数表示经过身份验证的用户正在代表参数值中指定的内容所有者执行操作。

  • 我们已更新 channels.update 方法的文档，以反映该方法可用于更新 channel 资源的 brandingSettings 对象及其子属性。该文档现在还列出了您可以为 channel 资源的 invideoPromotion 对象设置的更新后的属性列表。

  • error documentation 描述了以下新错误：

    错误类型 错误详情 说明
    forbidden accountDelegationForbidden 此错误并非特定于某个 API 方法。表示经过身份验证的用户无权代表指定的 Google 账号执行操作。
    forbidden authenticatedUserAccountClosed 此错误并非特定于某个 API 方法。表示经过身份验证的用户的 YouTube 账号已关闭。如果用户是代表其他 Google 账号行事，则此错误表示该其他账号已关闭。
    forbidden authenticatedUserAccountSuspended 此错误并非特定于某个 API 方法。表示经过身份验证的用户的 YouTube 账号已被暂停。如果用户是代表其他 Google 账号行事，则此错误表示该其他账号已被中止。
    forbidden authenticatedUserNotChannel 此错误并非特定于某个 API 方法。这表示 API 服务器无法识别与 API 请求关联的渠道。如果请求已获得授权并使用了 onBehalfOfContentOwner 参数，您还应设置 onBehalfOfContentOwnerChannel 参数。
    forbidden cmsUserAccountNotFound 此错误并非特定于某个 API 方法。CMS 用户无权代表指定的内容所有者执行操作。
    notFound contentOwnerAccountNotFound 此错误并非特定于某个 API 方法。找不到指定的内容所有者账号。
    badRequest invalidPart 此错误并非特定于某个 API 方法。相应请求的 part 参数指定了无法同时写入的部分。
    badRequest videoChartNotFound 如果请求指定了不受支持或不可用的视频排行榜，videos.list 方法会返回此错误。
    notFound videoNotFound videos.update 方法返回此错误，表示找不到您尝试更新的视频。检查请求正文中的 id 属性值，确保其正确无误。

2013 年 6 月 10 日

此更新包含以下更改：

  • channels.list 方法的新 forUsername 参数可让您通过指定频道的 YouTube 用户名来检索有关该频道的信息。

  • activities.list 方法现在支持 regionCode 参数，该参数用于指示 API 返回与指定国家/地区相关的结果。如果授权用户之前在 YouTube 上的活动不足以生成活动动态，YouTube 会使用此值。

  • 播放列表资源现在包含 snippet.tags 属性。该属性仅会返回给正在检索自己播放列表数据的授权用户。授权用户还可以在调用 playlists.insert 或 playlists.update 方法时设置播放列表标记。

  • 之前受 channels.list 和 search.list 方法支持的 onBehalfOfContentOwner 参数现在也受 videos.insert、videos.update 和 videos.delete 方法支持。请注意，当在对 videos.insert 方法的调用中使用此参数时，请求还必须为新的 onBehalfOfContentOwnerChannel 参数指定一个值，用于标识要将视频添加到的频道。频道必须与 onBehalfOfContentOwner 参数指定的内容所有者相关联。

    此参数表示请求的授权凭据标识的是一位 YouTube 内容管理系统用户，该用户代表参数值中指定的内容所有者执行操作。用户进行身份验证时使用的内容管理系统账号必须与指定的 YouTube 内容所有者相关联。

    此参数适用于拥有和管理许多不同 YouTube 频道的内容合作伙伴。借助此参数，这些合作伙伴只需进行一次身份验证，即可访问其所有视频和频道数据，而无需为每个频道单独提供身份验证凭据。

    具体来说，在此版本中，该参数现在可让内容合作伙伴在自己拥有的任何 YouTube 频道中插入、更新或删除视频。

  • error documentation 描述了以下新错误：

    错误类型 错误详情 说明
    forbidden insufficientCapabilities 此错误并非特定于某个 API 方法。表示调用 API 的 CMS 用户没有足够的权限来执行所请求的操作。此错误与 onBehalfOfContentOwner 参数的使用有关，该参数受多种 API 方法支持。
    unauthorized authorizationRequired 如果请求使用了 home 参数，但未获得适当的授权，activities.list 方法会返回此错误。

  • 在 channels 资源中，已移除 invideoPromotion.channelId 属性，因为已使用资源的 id 属性指定了渠道 ID。

  • 新的使用渠道 ID 指南介绍了 API 如何使用渠道 ID。对于从旧版 API 迁移的开发者，以及具有以下应用（即请求 default 用户的内容或依赖于“每个 YouTube 频道都有唯一用户名”这一概念的应用，但现在情况已不再如此）的开发者，本指南可能特别有用。

2013 年 5 月 22 日

此更新包含以下更改：

2013 年 5 月 14 日

此更新包含以下更改：

  • 独立页面现在列出了 Java、.NET、PHP 和 Ruby 的代码示例。

  • 列出 Python 代码示例的页面现在包含用于添加订阅、创建播放列表和更新视频的示例。

2013 年 5 月 10 日

此更新包含以下更改：

2013 年 5 月 8 日

此更新包含以下更改：

  • 频道资源现在支持 inVideoPromotion 对象，该对象封装了与频道关联的宣传广告系列的相关信息。频道可以使用视频内推广广告系列在视频播放器中显示推广视频的缩略图，以便在频道视频播放期间推广视频。

    您可以在 channels.list 请求的 part 参数值中添加 invideoPromotion，以检索此数据。

  • 新的 channels.update 方法可用于更新频道的视频内宣传广告系列数据。请注意，该方法仅支持更新 channel 资源的 invideoPromotion 部分，尚不支持更新该资源的其他部分。

2013 年 5 月 2 日

此更新包含以下更改：

  • 频道资源现在支持 status.isLinked 属性，该属性用于指明频道数据是否标识了已与 YouTube 用户名或 Google+ 账号相关联的用户。如果用户已拥有其中一种链接，则表示其已拥有公开的 YouTube 身份，这是执行多项操作（例如上传视频）的前提条件。

  • 订阅资源现在支持 subscriberSnippet 部分。该对象封装了订阅者频道的代码段数据。

  • 该 API 现在支持 videos.getRating 方法，该方法可检索经过身份验证的用户对一个或多个视频给出的评分。

  • 借助 videos.list 方法的新 myRating 参数，您可以检索经过身份验证的用户评分为 like 或 dislike 的视频列表。

    myRating 参数和 id 参数现在都被视为过滤条件参数，这意味着 API 请求必须指定这两个参数中的一个。（之前，id 参数是此方法的必需参数。）

    如果请求尝试检索视频分级信息，但未获得适当的授权，该方法会返回 forbidden 错误。

  • 随着 myRating 参数的引入，videos.list 方法也已更新，可支持分页。不过请注意，分页参数仅适用于使用 myRating 参数的请求。（使用 id 参数的请求不支持分页参数和信息。）

    • maxResults 参数用于指定 API 在结果集中可返回的视频数量上限，而 pageToken 参数用于标识您要检索的结果集中的特定网页。

    • 在响应 videos.list 请求时返回的 youtube#videoListResponse 资源现在包含 pageInfo 对象，该对象包含结果总数和当前结果集中包含的结果数等详细信息。youtube#videoListResponse 资源还可以包含 nextPageToken 和 prevPageToken 属性，每个属性都提供一个令牌，可用于检索结果集中的特定页面。

  • videos.insert 方法支持以下新参数：

    • autoLevels - 将此形参值设置为 true，以指示 YouTube 自动增强视频的亮度和色彩。
    • stabilize - 将此参数值设置为 true，可指示 YouTube 通过移除因相机运动而造成的画面抖动来调整视频。

  • 已将 channelTitle 属性添加到以下资源的 snippet 中：

    • playlistItem - 该属性用于指定添加了播放列表频道的名称。
    • playlist - 该属性用于指定创建播放列表的频道的名称。
    • subscription - 该属性用于指定订阅的频道的名称。

  • 我们为以下方法添加了代码示例：

  • subscriptions.list 方法的新 mySubscribers 参数可让您检索当前已通过身份验证的用户的订阅者列表。此参数只能在经过适当授权的请求中使用。

    注意：此功能旨在取代目前 channels.list 方法支持的 mySubscribers 参数。相应参数将被弃用。

  • 在 video 资源中，属性值 unspecified 不再是以下任何属性的可能值：

  • 现在，如果 API 请求包含意外参数，系统会返回 badRequest 错误，并且报告的错误原因是 unexpectedParameter。

  • 更新了当播放列表已包含允许的最大数量的项时 playlistItems.insert 方法返回的错误。现在，该错误会报告为 forbidden 错误，错误原因是 playlistContainsMaximumNumberOfVideos。

2013 年 4 月 19 日

此更新包含以下更改：

2013 年 3 月 12 日

此更新包含以下更改：

  • 已将 channelTitle 属性添加到以下资源的 snippet 中：

    • activity - 该属性用于指定负责相应 activity 的渠道的名称。
    • search - 该属性用于指定与搜索结果所标识的资源相关联的频道的名称。
    • video - 此属性用于指定上传视频的频道的名称。

  • search.list 方法支持以下新参数：

    • 借助 channelType 参数，您可以限制频道搜索范围，以检索所有频道或仅检索节目。

    • 借助 videoType 参数，您可以限制视频搜索范围，以检索所有视频，或仅检索电影或剧集。

  • 更新了 video 资源的 recordingDetails 部分的定义，指出只有在视频的地理位置数据或录制时间已设置的情况下，才会针对视频返回该对象。

  • playlistItems.update 方法现在会返回 invalidSnippet 错误，如果 API 请求未指定有效的代码段，则会返回此错误。

  • 部分 API 方法支持仅供 YouTube 内容合作伙伴使用的新参数。YouTube 内容合作伙伴包括电影和电视工作室、唱片公司以及其他在 YouTube 上提供内容的创作者。

    • onBehalfOfContentOwner 参数表示请求的授权凭据标识的是一位 YouTube 内容管理系统用户，该用户代表参数值中指定的内容所有者执行操作。用户进行身份验证时使用的内容管理系统账号必须与指定的 YouTube 内容所有者相关联。

      此参数适用于拥有和管理许多不同 YouTube 频道的内容合作伙伴。借助此参数，这些合作伙伴只需进行一次身份验证，即可访问其所有视频和频道数据，而无需为每个频道单独提供身份验证凭据。

      channels.list、search.list、videos.delete、videos.list 和 videos.update 方法均支持此参数。

    • channels.list 方法支持的 managedByMe 参数可指示 API 返回 onBehalfOfContentOwner 参数指定的内容所有者拥有的所有频道。

    • forContentOwner 参数（受 search.list 方法支持）指示 API 将搜索结果限制为仅包含 onBehalfOfContentOwner 参数指定的内容所有者拥有的资源。

2013 年 2 月 25 日

此更新包含以下更改：

  • 该 API 支持 video 资源的多个新部分和属性：

    • 新的 fileDetails、processingDetails 和 suggestions 部分会向视频所有者提供有关其上传视频的信息。此类数据在支持视频上传的应用中非常有用，包括以下内容：

      • 处理状态和进度
      • 处理视频时遇到的错误或其他问题
      • 缩略图的可用性
      • 有关如何提高视频或元数据质量的建议
      • 有关上传到 YouTube 的原始文件的详细信息

      只有视频所有者才能检索所有这些部分。下表简要介绍了各个新部分，而 video 资源文档定义了每个部分包含的所有属性。

      • fileDetails 对象包含有关上传到 YouTube 的视频文件的信息，包括文件的分辨率、时长、音频和视频编解码器、视频流比特率等。

      • processingProgress 对象包含有关 YouTube 在处理上传的视频文件方面的进度信息。该对象的属性用于标识当前处理状态，并估计 YouTube 完成视频处理所需的剩余时间。此部分还会指明视频是否有不同类型的数据或内容，例如文件详细信息或缩略图。

        此对象旨在进行轮询，以便视频上传者可以跟踪 YouTube 在处理上传的视频文件方面取得的进展。

      • suggestions 对象包含一些建议，这些建议可帮助您发现提升视频质量或改进上传视频的元数据的机会。

    • contentDetails 部分包含四个新属性。这些属性可以通过未经身份验证的请求进行检索。

      • dimension - 指示视频是否提供 2D 或 3D 版本。
      • definition - 表示视频是否提供标清或高清版本。
      • caption - 指示视频是否提供字幕。
      • licensedContent - 表示视频是否包含 YouTube 内容合作伙伴声明的内容。

    • status 部分包含两个新属性。视频所有者可以在插入或更新视频时为这两个属性设置值。这些属性也可以通过未经身份验证的请求进行检索。

      • embeddable - 指示视频是否可以嵌入到其他网站中。
      • license - 指定视频的许可。有效值为 creativeCommon 和 youtube。

  • part 参数的定义已针对 videos.list、videos.insert 和 videos.update 方法进行了更新，以列出上述新添加的部分以及之前不慎遗漏的 recordingDetails 部分。

  • channel 资源的新 contentDetails.googlePlusUserId 属性用于指定与频道关联的 Google+ 个人资料 ID。此值可用于生成指向 Google+ 个人资料的链接。

  • 每个缩略图对象现在都指定了图片的宽度和高度。目前，缩略图映像会在 activity、channel、playlist、playlistItem、search result、subscription 和 video 资源中返回。

  • playlistItems.list 现在支持 videoId 参数，该参数可与 playlistId 参数搭配使用，以仅检索表示指定视频的播放列表项。

    如果参数标识的视频在播放列表中找不到，该 API 会返回 notFound 错误。

  • 错误文档描述了一个新的 forbidden 错误，该错误表示请求未获得相应授权，无法执行所请求的操作。

  • 已移除 channel 资源的 snippet.channelId 属性。相应资源的 id 属性提供相同的值。

2013 年 1 月 30 日

此更新包含以下更改：

  • 新的错误页面列出了 API 可能会返回的错误。该页面包含可能针对多种不同 API 方法发生的一般错误，以及特定于方法的错误。

2013 年 1 月 16 日

此更新包含以下更改：

  • 现在，我们已针对以下列表中的方法和语言提供代码示例：

  • 资源现在可以报告 activity 操作，即 YouTube 将视频添加到自动生成的 YouTube 频道时发生的操作。channelItem（YouTube 会通过算法识别在 YouTube 网站上表现突出的主题，并自动为这些主题生成频道。）

  • 更新了以下 search.list 参数：

    • q 参数不再指定为过滤器，这意味着...
    • relatedToVideo 参数已重命名为 relatedToVideoId。
    • published 参数已被两个新参数（publishedAfter 和 publishedBefore）取代，这两个参数的说明如下。

  • search.list 方法支持以下新参数：

    参数名称 值 说明
    channelId string 返回由指定渠道创建的资源。
    publishedAfter datetime 返回在指定时间之后创建的资源。
    publishedBefore datetime 返回在指定时间之前创建的资源。
    regionCode string 返回指定国家/地区的资源。
    videoCategoryId string 过滤视频搜索结果，使其仅包含与指定视频类别相关联的视频。
    videoEmbeddable string 过滤视频搜索结果，以仅显示可在网页上的嵌入式播放器中播放的视频。将参数值设置为 true，即可仅检索可嵌入的视频。
    videoSyndicated string 过滤视频搜索结果，使其仅包含可在 YouTube.com 之外播放的视频。将参数值设置为 true，即可仅检索联合发布的视频。

  • 多个 API 资源支持新属性。下表列出了资源及其新属性：

    资源 属性名称 值 说明
    activity contentDetails.playlistItem.playlistItemId string YouTube 分配的播放列表内容 ID，用于唯一标识播放列表中的内容。
    activity contentDetails.channelItem object 一个对象，其中包含有关已添加到频道的资源的信息。仅当 snippet.type 为 channelItem 时，此属性才会存在。
    activity contentDetails.channelItem.resourceId object 一个对象，用于标识已添加到频道的资源。与其他 resourceId 属性一样，它包含一个 kind 属性，用于指定资源类型，例如视频或播放列表。它还包含多个属性（videoId、playlistId 等）中的一个，用于指定唯一标识相应资源的 ID。
    channel status object 此对象封装了有关频道隐私状态的信息。
    channel status.privacyStatus string 频道的隐私状态。有效值为 private 和 public。
    playlist contentDetails object 此对象包含有关播放列表内容的元数据。
    playlist contentDetails.itemCount unsigned integer 播放列表中的视频数量。
    playlist player object 此对象包含您在嵌入式播放器中播放播放列表时会用到的信息。
    playlist player.embedHtml string 用于嵌入播放播放列表的视频播放器的 <iframe> 标记。
    video recordingDetails object 此对象封装了用于标识或描述视频录制地点和时间的信息。
    video recordingDetails.location object 此对象包含与视频相关联的地理定位信息。
    video recordingDetails.location.latitude double 纬度（以度为单位）。
    video recordingDetails.location.longitude double 经度（以度为单位）。
    video recordingDetails.location.elevation double 地球上空的高度（以米为单位）。
    video recordingDetails.locationDescription string 视频录制地点的文字说明。
    video recordingDetails.recordingDate datetime 视频的录制日期和时间。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。

  • 现在，许多 API 方法的文档都指明了必须在请求正文中指定的属性，或根据请求正文中的值更新的属性。下表列出了这些方法以及必需或可修改的属性。

    注意：其他方法的文档可能已列出必需属性和可修改的属性。

    方法 属性
    activities.insert 必需属性：
    • snippet.description
    可修改的属性：
    • snippet.description
    • contentDetails.bulletin.resourceId
    playlists.update 必需属性：
    • id
    playlistItems.update 必需属性：
    • id
    videos.update 必需属性：
    • id

  • 如果您尝试创建或更新的播放列表与同一频道中已有的播放列表具有相同的标题，该 API 不再报告 playlistAlreadyExists 错误。

  • 多个 API 方法支持新的错误类型。下表列出了相应的方法和新支持的错误：

    方法 错误类型 错误详情 说明
    guideCategories.list notFound notFound 找不到 id 参数所标识的指南类别。使用 guideCategories.list 方法检索有效值列表。
    playlistItems.delete forbidden playlistItemsNotAccessible 相应请求未获得适当授权，无法删除指定的播放列表项。
    videoCategories.list notFound videoCategoryNotFound 找不到 id 参数所标识的视频类别。使用 videoCategories.list 方法检索有效值的列表。