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 上執行的動作相關資訊。活動動態消息中回報的動作包括：為影片評分、分享影片、將影片標示為我的最愛、上傳影片等。每個 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 更新頻道的 metadata。這個方法僅支援更新 channel 資源的 brandingSettings 和 invideoPromotion 物件及其子項屬性。

CommentThreads

commentThread 資源包含 YouTube 留言討論串的相關資訊，包括頂層留言和該留言的回覆 (如有)。commentThread 資源可代表影片或頻道的留言。

頂層留言和回覆實際上都是巢狀結構，位於 commentThread 資源內。commentcommentThread 資源不一定會包含所有留言回覆，如要擷取特定留言的所有回覆，請使用 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 網站頁尾手動選取 UI 語言。

每個 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 等) 是指縮圖大小。
  • 不同類型的資源可能支援不同大小的縮圖。
  • 不同類型的資源可能會為同名縮圖定義不同大小。舉例來說，default video 資源的縮圖通常為 120 x 90 像素，default channel 資源的縮圖通常為 88 x 88 像素。
  • 視上傳至 YouTube 的原始圖片或內容解析度而定，相同類型的資源仍可能出現不同大小的縮圖。舉例來說，HD 影片支援的縮圖解析度可能比非 HD 影片更高。
  • 每個包含縮圖大小資訊的物件都有 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 刪除頻道的浮水印圖片。