API Reference

YouTube Data API 可讓您將在 YouTube 網站上執行的功能，整合到自己的網站或應用程式中。以下清單列出您可以使用 API 擷取的不同資源類型。這個 API 也支援插入、更新或刪除許多這些資源的方法。

這份參考指南說明如何使用 API 執行上述所有操作。本指南是依據資源類型進行分類。資源代表構成 YouTube 體驗的項目類型，例如影片、播放清單或訂閱項目。針對每個資源類型，指南會列出一或多個資料表示法，資源則以 JSON 物件表示。這份指南也針對每種資源類型列出一或多個支援的方法 (LIST、POST、DELETE 等)，並說明如何在應用程式中使用這些方法。

呼叫 API

下列規定適用於 YouTube Data API 要求：

  1. 每個要求都必須指定 API 金鑰 (含 key 參數) 或提供 OAuth 2.0 權杖。您可以在 Developer Console 的「API Access」(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 傳回符合要求條件的頻道活動事件清單。例如，您可以擷取與特定頻道或使用者自有頻道相關的事件。
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 要求 說明
相對於 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 方法。
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 網站支援的應用程式語言。應用程式語言也可以稱為 UI 語言。在 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 傳回零或多個 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 播放清單。播放清單是一組可以依序觀看的影片，並且可以與其他使用者分享。一份播放清單最多可包含 200 部影片，YouTube 並限制每位使用者建立的播放清單數量。預設情況下，其他使用者能看到播放清單，但播放清單可以是公開或私人。

YouTube 也會利用播放清單來識別頻道的特殊影片集合，例如：

  • 上傳的影片
  • 評分良好 (喜歡) 的影片
  • 觀看記錄
  • 稍後觀看。
具體而言，這類清單會與頻道建立關聯，也就是一組使用者、團體或公司的影片、播放清單和其他 YouTube 資訊。您可以從特定頻道的 channel resource 擷取這些清單的播放清單 ID。

接著，您可以使用 playlistItems.list 方法擷取任一清單。您也可以呼叫 playlistItems.insert 和 playlistItems.delete 方法，在這些清單中新增或移除項目。

如要進一步瞭解這項資源，請參閱其資源表示法和屬性清單。

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
delete DELETE /playlists 刪除播放清單。
list GET /playlists 傳回符合 API 要求參數的播放清單集合。例如，您可以擷取已驗證使用者擁有的所有播放清單，或依照專屬 ID 擷取一或多個播放清單。
insert POST /playlists 建立播放清單。
update PUT /playlists 修改播放清單。例如，您可以變更播放清單的標題、說明或隱私設定。

搜尋結果會包含與 API 要求中指定的搜尋參數相符的 YouTube 影片、頻道或播放清單的相關資訊。雖然搜尋結果指向的是明確識別資源 (例如影片)，但其並沒有持續性資料。

如要進一步瞭解這項資源，請參閱其資源表示法和屬性清單。

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
list GET /search 傳回一組與 API 要求中指定的查詢參數相符的搜尋結果。根據預設，搜尋結果集會識別相符的 video、channel 和 playlist 資源，但您也可以設定查詢，僅擷取特定類型的資源。

訂閱項目

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 縮圖圖片通常為 120 x 90 像素，channel 資源的 default 縮圖圖片則通常為 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 刪除頻道的浮水印圖片。