API Reference

YouTube Data API 可讓您將一般在 YouTube 網站上執行的功能,整合至您的網站或應用程式。以下清單列出您可以使用 API 擷取的各種資源類型。這個 API 也支援插入、更新或刪除這類資源的方法。

本參考指南將說明如何使用 API 執行所有這些作業。本指南會依資源類型整理內容。「資源」代表構成 YouTube 體驗的一部分項目,例如影片、播放清單或訂閱項目。針對每個資源類型,指南會列出一或多個資料表示法,且資源會以 JSON 物件表示。本指南也會針對每種資源類型列出一或多個支援的方法 (LISTPOSTDELETE 等),並說明如何在應用程式中使用這些方法。

呼叫 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 傳回符合要求條件的 0 或多個 channel 資源集合。
update PUT /channels 更新頻道的中繼資料。請注意,這個方法目前僅支援更新 channel 資源的 brandingSettingsinvideoPromotion 物件及其子項屬性。

留言串

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.listguideCategories.list 等 API 方法時,語言代碼可以用作 hl 參數值。

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

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

I18nRegions

i18nRegion 資源可識別 YouTube 使用者可將哪些地理區域做為偏好內容地區。內容地區也可稱為內容語言代碼。如果是 YouTube 網站,系統會根據 YouTube 網域或使用者的 IP 位置等經驗法則,自動選取內容地區。使用者也可以從 YouTube 網站頁尾手動選取想觀看的內容區域。

每項 i18nRegion 資源都會標示一個區碼和一個名稱。當您呼叫 search.listvideos.listactivities.listvideoCategories.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 要求的管道擁有的 0 或多個 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.insertplaylistItems.delete 方法,在這些清單中新增或移除項目。

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

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

搜尋結果包含的 YouTube 影片、頻道或播放清單的相關資訊,符合 API 要求中指定的搜尋參數。雖然搜尋結果指向可以明確識別的資源 (例如影片),卻沒有專屬的永久資料。

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

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

個訂閱項目

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 資源包含一系列的物件。每個物件的名稱 (defaultmediumhigh 等) 是指縮圖尺寸。
  • 不同類型的資源可以支援不同的縮圖大小。
  • 不同的資源類型可能會為同名的縮圖定義不同大小。舉例來說,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 擷取可用於檢舉違規影片的原因清單。

影片類別

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