Channels

API 現在支援將頻道或影片標示為「兒童專屬」的功能。此外，channel 和 video 資源現在也包含一項屬性，可識別該頻道或影片的「兒童專屬」狀態。《YouTube API 服務條款》和《開發人員政策》也已於 2020 年 1 月 10 日更新。詳情請參閱 YouTube Data API 服務和 YouTube API 服務條款的修訂版本記錄。

channel 資源包含 YouTube 頻道的相關資訊。

方法

API 支援下列 channels 資源方法：

list
傳回符合要求條件的零或多個 channel 資源集合。立即試用。
update
更新頻道的中繼資料。請注意，這個方法目前僅支援更新 channel 資源的 brandingSettings 和 invideoPromotion 物件及其子項屬性。 立即試用。

資源表示法

下列 JSON 結構顯示 channels 資源的格式：

{
  "kind": "youtube#channel",
  "etag": etag,
  "id": string,
  "snippet": {
    "title": string,
    "description": string,
    "customUrl": string,
    "publishedAt": datetime,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "defaultLanguage": string,
    "localized": {
      "title": string,
      "description": string
    },
    "country": string
  },
  "contentDetails": {
    "relatedPlaylists": {
      "likes": string,
      "favorites": string,
      "uploads": string
    }
  },
  "statistics": {
    "viewCount": unsigned long,
    "subscriberCount": unsigned long,  // this value is rounded to three significant figures
    "hiddenSubscriberCount": boolean,
    "videoCount": unsigned long
  },
  "topicDetails": {
    "topicIds": [
      string
    ],
    "topicCategories": [
      string
    ]
  },
  "status": {
    "privacyStatus": string,
    "isLinked": boolean,
    "longUploadsStatus": string,
    "madeForKids": boolean,
    "selfDeclaredMadeForKids": boolean
  },
  "brandingSettings": {
    "channel": {
      "title": string,
      "description": string,
      "keywords": string,
      "trackingAnalyticsAccountId": string,
      "unsubscribedTrailer": string,
      "defaultLanguage": string,
      "country": string
    },
    "watch": {
      "textColor": string,
      "backgroundColor": string,
      "featuredPlaylistId": string
    }
  },
  "auditDetails": {
    "overallGoodStanding": boolean,
    "communityGuidelinesGoodStanding": boolean,
    "copyrightStrikesGoodStanding": boolean,
    "contentIdClaimsGoodStanding": boolean
  },
  "contentOwnerDetails": {
    "contentOwner": string,
    "timeLinked": datetime
  },
  "localizations": {
    (key): {
      "title": string,
      "description": string
    }
  }
}

屬性

下表定義這個資源中顯示的屬性：

屬性
kind string
識別 API 資源的類型。值為 youtube#channel。
etag etag
這項資源的 Etag。
id string
YouTube 用來識別頻道的專屬 ID。
snippet object
snippet 物件包含頻道的相關基本詳細資料，例如標題、說明和縮圖。
snippet.title string
頻道的名稱。
snippet.description string
頻道的說明。屬性值的長度上限為 1000 個半形字元。
snippet.customUrl string
頻道的自訂網址。如要瞭解自訂網址的資格規定和設定方式，請參閱 YouTube 說明中心。
snippet.publishedAt datetime
頻道的建立日期和時間。這個值是以 ISO 8601 格式指定。
snippet.thumbnails object
與頻道相關聯的縮圖圖片對應。地圖中的每個物件都有一個鍵，也就是縮圖圖片的名稱，而值則是包含縮圖其他資訊的物件。

在應用程式中顯示縮圖時，請務必確保程式碼使用的圖片網址與 API 回應中傳回的網址完全相同。舉例來說，在 API 回應傳回的網址中，應用程式不應使用 http 網域，而非 https 網域。

頻道縮圖網址僅適用於 https 網域，這也是網址在 API 回應中的顯示方式。如果應用程式嘗試從 http 網域載入 YouTube 圖片，可能會顯示損毀的圖片。新建立的頻道可能不會顯示縮圖，最多需要一天才會顯示。
snippet.thumbnails.(key) object
有效鍵值如下：
  • default：預設縮圖。影片的預設縮圖 (或參照影片的資源，例如播放清單項目或搜尋結果) 寬 120 像素，高 90 像素。頻道的預設縮圖寬度為 88 像素，高度為 88 像素。
  • medium：縮圖圖片的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 320 像素，高度為 180 像素。如果是頻道，這張圖片的寬度和高度都是 240 像素。
  • high：縮圖圖片的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 480 像素，高度為 360 像素。如果是頻道，這張圖片的寬度和高度為 800 像素。
snippet.thumbnails.(key).url string
圖片的網址。如要進一步瞭解如何在應用程式中使用縮圖網址，請參閱 snippet.thumbnails 屬性定義。
snippet.thumbnails.(key).width unsigned integer
圖片寬度。
snippet.thumbnails.(key).height unsigned integer
圖片的高度。
snippet.defaultLanguage string
channel 資源的 snippet.title 和 snippet.description 屬性中文字的語言。
snippet.localized object
snippet.localized 物件包含頻道本地化的標題和說明，或包含頻道中繼資料預設語言的頻道標題和說明。
  • 如果 channels.list 要求使用 hl 參數指定應傳回本地化文字的語言、hl 參數值識別 YouTube 應用程式語言，且本地化文字支援該語言，則資源片段會傳回本地化文字。
  • 如果未指定 hl 參數值，「或」已指定值，但指定語言沒有本地化中繼資料，系統會傳回預設語言的中繼資料。
屬性包含唯讀值。使用 localizations 物件新增、更新或刪除本地化中繼資料。
snippet.localized.title string
本地化的頻道名稱。
snippet.localized.description string
本地化的頻道說明。
snippet.country string
與頻道相關聯的國家/地區。如要設定這項屬性的值，請更新 brandingSettings.channel.country 屬性的值。
contentDetails object
contentDetails 物件會封裝頻道內容的相關資訊。
contentDetails.relatedPlaylists object
relatedPlaylists 物件是與頻道相關聯的播放清單，例如頻道上傳的影片或喜歡的影片。您可以使用 playlists.list 方法擷取任一播放清單。
contentDetails.relatedPlaylists.likes string
包含頻道喜歡的影片的播放清單 ID。使用 playlistItems.insert 和 playlistItems.delete 方法，在清單中新增或移除項目。
contentDetails.relatedPlaylists.favorites string
這項屬性已淘汰。

含有頻道最愛影片的播放清單 ID。使用 playlistItems.insert 和 playlistItems.delete 方法，在清單中新增或移除項目。

請注意，YouTube 已淘汰收藏影片功能。舉例來說，video 資源的 statistics.favoriteCount 屬性已於 2015 年 8 月 28 日淘汰。因此，基於歷史因素，這項屬性值可能包含參照空白播放清單的播放清單 ID，因此無法擷取。
contentDetails.relatedPlaylists.uploads string
包含頻道上傳影片的播放清單 ID。使用 videos.insert 方法上傳新影片，並使用 videos.delete 方法刪除先前上傳的影片。
statistics object
statistics 物件會封裝頻道的統計資料。
statistics.viewCount unsigned long

頻道中所有格式的所有影片觀看次數總和。

2026 年 8 月 24 日起，頻道所有格式的影片 (長篇影片、直播和 Shorts) 都將採用更新後的viewCount，只要開始播放 (包括自動播放、游標懸停和點按播放)，就會計入觀看次數。
statistics.commentCount unsigned long
這項屬性已淘汰。

頻道的留言數。
statistics.subscriberCount unsigned long
頻道的訂閱人數。這個值會無條件捨去至三位有效數字。如要進一步瞭解訂閱人數的四捨五入方式，請參閱修訂版本記錄或 YouTube 說明中心。
statistics.hiddenSubscriberCount boolean
指出頻道的訂閱人數是否公開顯示。
statistics.videoCount unsigned long
上傳到頻道的公開影片數量。請注意，即使是擁有者，這個值也只會反映頻道公開影片的數量。這項行為與 YouTube 網站上顯示的計數一致。
topicDetails object
topicDetails 物件會封裝與頻道相關聯的主題資訊。

重要事項：如要進一步瞭解主題 ID 相關異動，請參閱 topicDetails.topicIds[] 屬性定義和修訂版本記錄。
topicDetails.topicIds[] list
與頻道相關聯的主題 ID 清單。

這項屬性已於 2016 年 11 月 10 日淘汰。支援期限至 2017 年 11 月 10 日。

重要事項：由於 Freebase 和 Freebase API 已淘汰，自 2017 年 2 月 27 日起，主題 ID 的運作方式有所不同。當時，YouTube 開始傳回一小組精選主題 ID。
topicDetails.topicCategories[] list
列出說明頻道內容的維基百科網址。
status object
status 物件會封裝管道隱私權狀態的相關資訊。
status.privacyStatus string
頻道的隱私權狀態。

這個屬性的有效值如下：
  • private
  • public
  • unlisted
status.isLinked boolean
指出頻道資料是否能識別已連結至 YouTube 使用者名稱或 Google+ 帳戶的使用者。如果使用者有其中一個連結，表示他們已有公開的 YouTube 身分，這是上傳影片等幾項操作的必要條件。
status.longUploadsStatus string
指出頻道是否能上傳超過 15 分鐘的影片。只有在頻道擁有者授權 API 要求時，才會傳回這個屬性。如要進一步瞭解這項功能，請參閱 YouTube 說明中心。

這項屬性的有效值如下：
  • allowed - 這個頻道可以上傳長度超過 15 分鐘的影片。
  • disallowed - 這個頻道無法上傳或不符合上傳長度超過 15 分鐘影片的資格。頻道必須符合 YouTube《社群規範》 的「記錄良好」狀態，且內容未在全球遭到 Content ID 封鎖，才能上傳長片。

    頻道擁有者解決問題後，頻道就會恢復為 allowed 或 eligible 狀態。
  • eligible：這個頻道可以上傳長度超過 15 分鐘的影片。不過，頻道擁有者必須先完成電話驗證，才能上傳較長的影片。如要進一步瞭解這項功能，請參閱 YouTube 說明中心。
status.madeForKids boolean
這個值會指出頻道是否設為兒童導向，並包含頻道目前的「兒童專屬」狀態。舉例來說，狀態可能會根據 selfDeclaredMadeForKids 屬性的值決定。如要進一步瞭解如何為頻道、影片或直播設定目標觀眾，請參閱 YouTube 說明中心。
status.selfDeclaredMadeForKids boolean
在 channels.update 要求中，頻道擁有者可透過這項屬性將頻道指定為兒童導向。只有在頻道擁有者授權 API 要求時，才會傳回屬性值。
brandingSettings object
brandingSettings 物件會封裝頻道品牌宣傳的相關資訊。
brandingSettings.channel object
channel 物件會封裝頻道頁面的品牌屬性。
brandingSettings.channel.title string
頻道的名稱。標題長度上限為 30 個半形字元。
brandingSettings.channel.description string
頻道說明，會顯示在頻道頁面的頻道資訊方塊中。屬性值的長度上限為 1000 個字元。
brandingSettings.channel.keywords string
與頻道相關聯的關鍵字。值是以空格分隔的字串清單。如果頻道關鍵字超過 500 個半形字元的長度上限，或包含未逸出的引號 (")，系統可能會截斷關鍵字。請注意，500 個半形字元的限制並非針對個別關鍵字，而是所有關鍵字的總長度限制。
brandingSettings.channel.trackingAnalyticsAccountId string
Google Analytics 帳戶 ID，用於追蹤及評估頻道流量。
brandingSettings.channel.unsubscribedTrailer string
未訂閱觀眾在頻道頁面的瀏覽檢視中，精選影片模組應播放的影片。訂閱者可能會看到其他影片，當中會著重呈現頻道近期的活動。

如果指定，屬性值必須是頻道擁有者擁有的公開或不公開影片的 YouTube 影片 ID。
brandingSettings.channel.defaultLanguage string
channel 資源中 snippet.title 和 snippet.description 屬性的文字語言。
brandingSettings.channel.country string
與頻道相關聯的國家/地區。更新這個屬性，即可設定 snippet.country 屬性的值。
brandingSettings.watch object
注意：這個物件及其所有子項屬性已淘汰。

watch 物件會封裝頻道影片觀賞頁面的品牌宣傳屬性。
brandingSettings.watch.textColor string
注意：這項屬性已淘汰。

影片觀賞頁面品牌宣傳區域的文字顏色。
brandingSettings.watch.backgroundColor string
注意：這項屬性已淘汰。

影片觀賞頁面品牌區域的背景顏色。
brandingSettings.watch.featuredPlaylistId string
注意：這項屬性已淘汰。如果您嘗試設定其值，API 會傳回錯誤。
brandingSettings.image object
這項屬性及其所有子項屬性皆已淘汰。

image 物件會封裝頻道頁面或影片觀賞頁面中顯示的圖片相關資訊。
brandingSettings.image.bannerImageUrl string
這項屬性已淘汰。

YouTube 網站頻道頁面顯示的橫幅圖片網址。圖片大小為 1060 x 175 像素。
brandingSettings.image.bannerMobileImageUrl string
這項屬性已淘汰。

行動應用程式中頻道頁面顯示的橫幅圖片網址。圖片大小為 640 x 175 像素。
brandingSettings.image.watchIconImageUrl string
這項屬性已淘汰。

影片播放器上方顯示的圖片網址。這張圖片的高度為 25 像素，寬度可彈性調整，但不得超過 170 像素。如未提供這張圖片，系統會改為顯示頻道名稱。
brandingSettings.image.trackingImageUrl string
這項屬性已淘汰。

1 像素 x 1 像素追蹤像素的網址，可用於收集頻道或影片頁面觀看次數的統計資料。
brandingSettings.image.bannerTabletLowImageUrl string
這項屬性已淘汰。

低解析度橫幅圖片的網址，會顯示在平板電腦應用程式的頻道頁面。圖片大小上限為 1138 x 188 像素。
brandingSettings.image.bannerTabletImageUrl string
這項屬性已淘汰。

平板電腦應用程式中，頻道頁面顯示的橫幅圖片網址。圖片尺寸為 1707 x 283 像素。
brandingSettings.image.bannerTabletHdImageUrl string
這項屬性已淘汰。

高解析度橫幅圖片的網址，會顯示在平板電腦應用程式的頻道頁面。圖片大小上限為 2276 x 377 像素。
brandingSettings.image.bannerTabletExtraHdImageUrl string
這項屬性已淘汰。

超高解析度橫幅圖片的網址，會顯示在平板電腦應用程式的頻道頁面。圖片大小上限為 2560 x 424 像素。
brandingSettings.image.bannerMobileLowImageUrl string
這項屬性已淘汰。

低解析度橫幅圖片的網址，會顯示在行動應用程式的頻道頁面。圖片大小上限為 320 x 88 像素。
brandingSettings.image.bannerMobileMediumHdImageUrl string
這項屬性已淘汰。

中解析度橫幅圖片的網址，會顯示在行動應用程式的頻道頁面。圖片大小上限為 960 x 263 像素。
brandingSettings.image.bannerMobileHdImageUrl string
這項屬性已淘汰。

高解析度橫幅圖片的網址，會顯示在行動應用程式的頻道頁面。圖片大小上限為 1280 x 360 像素。
brandingSettings.image.bannerMobileExtraHdImageUrl string
這項屬性已淘汰。

超高解析度橫幅圖片的網址，會顯示在行動應用程式的頻道頁面。圖片大小上限為 1440 x 395 像素。
brandingSettings.image.bannerTvImageUrl string
這項屬性已淘汰。

超高解析度橫幅圖片的網址，會顯示在電視應用程式的頻道頁面。圖片大小上限為 2120 x 1192 像素。
brandingSettings.image.bannerTvLowImageUrl string
這項屬性已淘汰。

低解析度橫幅圖片的網址，會顯示在電視應用程式的頻道頁面。圖片大小上限為 854 x 480 像素。
brandingSettings.image.bannerTvMediumImageUrl string
這項屬性已淘汰。

電視應用程式頻道頁面顯示的中解析度橫幅圖片網址。圖片大小上限為 1280 x 720 像素。
brandingSettings.image.bannerTvHighImageUrl string
這項屬性已淘汰。

電視應用程式頻道頁面上顯示的高解析度橫幅圖片網址。圖片大小上限為 1920 x 1080 像素。
brandingSettings.image.bannerExternalUrl string
這項屬性會指定橫幅圖片的位置，YouTube 會使用這張圖片，為頻道產生各種大小的橫幅圖片。
brandingSettings.hints[] list
這項屬性和所有子項屬性已遭淘汰。

hints 物件會封裝其他品牌宣傳屬性。
brandingSettings.hints[].property string
這項屬性已淘汰。

屬性。
brandingSettings.hints[].value string
這項屬性已淘汰。

屬性的值。
auditDetails object
auditDetails 物件會封裝多頻道聯播網 (MCN) 評估的頻道資料，判斷是否接受或拒絕特定頻道。請注意，任何擷取這項資源部分的 API 要求，都必須提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit 範圍的授權權杖。此外，如果 MCN 決定接受或拒絕頻道，或是在權杖核發日期的兩週內，任何使用該範圍的權杖都必須撤銷。
auditDetails.overallGoodStanding boolean
這個欄位會指出管道是否有任何問題。目前，這個欄位代表對 communityGuidelinesGoodStanding、copyrightStrikesGoodStanding 和 contentIdClaimsGoodStanding 屬性執行邏輯 AND 運算的結果，也就是說，如果所有其他屬性的值也都是 true，則這個屬性的值為 true。不過，如果上述任一屬性的值為 false，則這項屬性的值會是 false。不過請注意，設定這項屬性值的方法可能會有變動。
auditDetails.communityGuidelinesGoodStanding boolean
指出頻道是否遵守 YouTube《社群規範》。
auditDetails.copyrightStrikesGoodStanding boolean
指出頻道是否收到著作權警告。
auditDetails.contentIdClaimsGoodStanding boolean
指出頻道是否有任何未解決的著作權聲明。
contentOwnerDetails object
contentOwnerDetails 物件會封裝頻道資料，只有將頻道連結至內容管理工具的 YouTube 合作夥伴才能查看。
contentOwnerDetails.contentOwner string
與頻道連結的內容擁有者 ID。
contentOwnerDetails.timeLinked datetime
頻道連結至內容擁有者的日期和時間。值以 ISO 8601 格式指定。
localizations object
localizations 物件會封裝頻道中繼資料的翻譯。
localizations.(key) object
與鍵值相關聯的本地化中繼資料語言。這個值是包含 BCP-47 語言代碼的字串。
localizations.(key).title string
本地化的頻道名稱。
localizations.(key).description string
本地化頻道說明。