本頁面由 Cloud Translation API 翻譯而成。

API Reference

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

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

呼叫 API

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

每個要求都必須指定 API 金鑰 (含 key 參數) 或提供 OAuth 2.0 權杖。您可以在 Developer Console 的「API Access」(API 存取權)窗格中找到 API 金鑰。
每次插入、更新及刪除要求時，您都必須傳送授權權杖。如果請求會擷取已驗證使用者的私人資料，您也必須傳送授權權杖。

此外，部分用於擷取資源的 API 方法可能支援需要授權的參數，或是在要求取得授權後可能包含額外的中繼資料。例如，要求擷取使用者上傳的影片時，如果要求已獲得特定使用者授權，要求中也可能會包含私人影片。
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 要求說明

方法	HTTP 要求	說明
相對於 `https://www.googleapis.com/youtube/v3` 的 URI
`insert`	`POST /channelBanners/insert`	將頻道橫幅圖片上傳到 YouTube。這個方法代表在三個步驟中更新頻道橫幅圖片的前兩個步驟：呼叫 `channelBanners.insert` 方法，將二進位圖片資料上傳至 YouTube。圖片的長寬比必須為 16:9，尺寸至少 2048x1152 像素。建議上傳 2560 x 1440 像素的圖片。從 API 針對步驟 1 傳回的回應中擷取 `url` 屬性值。呼叫 `channels.update` 方法，更新頻道的品牌宣傳設定。將 `brandingSettings.image.bannerExternalUrl` 屬性的值設為步驟 2 中取得的網址。

相對於 https://www.googleapis.com/youtube/v3 的 URI

insert

POST /channelBanners/insert

將頻道橫幅圖片上傳到 YouTube。這個方法代表在三個步驟中更新頻道橫幅圖片的前兩個步驟：

呼叫 channelBanners.insert 方法，將二進位圖片資料上傳至 YouTube。圖片的長寬比必須為 16:9，尺寸至少 2048x1152 像素。建議上傳 2560 x 1440 像素的圖片。
從 API 針對步驟 1 傳回的回應中擷取 url 屬性值。
呼叫 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`	刪除頻道的浮水印圖片。