本頁面由 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 權杖。您可以在開發人員控制台的專案 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，且尺寸至少為 2048 x 1152 像素。建議上傳 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，且尺寸至少為 2048 x 1152 像素。建議上傳 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` 資源集合 (0 個以上)。
`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 網站支援的應用程式語言。應用程式語言也稱為使用者介面語言。在 YouTube 網站上，應用程式語言會根據 Google 帳戶設定、瀏覽器語言或 IP 位置自動選取。使用者也可以在 YouTube 網站頁尾手動選取所需的 UI 語言。

每個 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`	傳回一組由授權 API 要求的頻道所擁有的 `membershipsLevel` 資源，其中資源數量為 0 或更多。系統會依隱含的顯示順序傳回層級。

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` 資源，但您也可以設定查詢，只擷取特定類型的資源。

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