Channels

API 現已支援將頻道或影片標示為「兒童專屬」。此外，channel 和 video 資源現在也包含屬性，可識別頻道或影片的「兒童專屬」狀態。我們也於 2020 年 1 月 10 日更新了《YouTube API 服務條款》和《開發人員政策》。詳情請參閱 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 像素。
  • 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

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

自 2025 年 3 月 31 日起，如果是頻道上的 Shorts，觀看次數將更新為 Shorts 開始播放或重播的次數。

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
此屬性已淘汰。

1x1 像素追蹤像素的網址，可用於收集頻道或影片頁面觀看次數的統計資料。
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
本地化的頻道說明。