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 傳回符合要求條件的頻道活動事件清單。舉例來說，您可以擷取與特定管道或使用者自有管道相關聯的事件。
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 更新字幕軌。更新字幕軌時，您可以變更播放軌的「草稿狀態」、上傳新曲目的新字幕檔案，或同時上傳兩者。

頻道橫幅

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 中取得的網址。

頻道版面

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 物件及其子項屬性。

註解串

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 修改留言。

指南類別

guideCategory 資源用於識別 YouTube 根據頻道內容或其他指標 (例如頻道熱門程度) 進行演算法指派的類別。這份清單與影片類別相似，差別在於影片上傳者可以指派影片類別，但只有 YouTube 可以指派頻道類別。

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

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
list GET /guideCategories 傳回與 YouTube 頻道相關聯的類別清單。

I18nLanguages

i18nLanguage 資源可識別 YouTube 網站支援的應用程式語言。應用程式語言也稱為 UI 語言。如果是 YouTube 網站，系統可能會根據 Google 帳戶設定、瀏覽器語言或 IP 位置，自動選取應用程式語言。使用者也可以從 YouTube 網站頁尾手動選取所需的 UI 語言。

每個 i18nLanguage 資源都有一組語言代碼和名稱，呼叫 videoCategories.list 和 guideCategories.list 等 API 方法時，語言代碼可用於 hl 參數的值。

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

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
list GET /i18nLanguages 傳回 YouTube 網站支援的應用程式語言清單。

18 個地區

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 要求必須獲得頻道擁有者的授權。

會員等級

membershipsLevel 資源可識別授權 API 要求的建立者。

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

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
list GET /membershipsLevels 傳回已獲授權 API 要求的管道所擁有的零或多個 membershipsLevel 資源集合。層級會以隱含顯示順序傳回。

播放清單項目

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 縮圖尺寸通常為 120px x 90px，channel 資源的 default 縮圖圖片通常為 88px x 88px。
  • 視原始圖片或影片上傳至 YouTube 的解析度而定，同類型的資源可能還是會有不同的縮圖大小。舉例來說，如果 HD 高畫質影片的解析度比 HD 高畫質影片來得高，
  • 每個包含縮圖圖片大小相關資訊的物件都有 width 屬性和 height 屬性。不過，系統可能不會傳回該圖片的寬度和高度屬性。
  • 如果上傳的縮圖與規定尺寸不符，系統會將圖片大小調整為正確大小，而不會變更長寬比。圖片不會被裁剪，但可以包含黑色長條，確保尺寸正確。

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

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
set POST /thumbnails/set 將自訂影片縮圖上傳至 YouTube 並設為影片。

影片濫用原因

videoAbuseReportReason 資源包含因檢舉內容含有不當內容而遭到檢舉的原因。當應用程式呼叫 videos.reportAbuse 方法來檢舉騷擾他人的影片時，該要求會使用 videoAbuseReportReason 資源中的資訊識別影片遭到檢舉的原因。

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

方法 HTTP 要求 說明
相對於 https://www.googleapis.com/youtube/v3 的 URI
list GET /videoAbuseReportReasons 擷取可檢舉濫用影片的原因清單。

影片類別

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 刪除頻道的浮水印圖片。