YouTube Live Streaming API - 修訂版本記錄

本頁列出 YouTube 直播串流 API 的變更和說明文件更新。訂閱這份變更記錄。訂閱

2026 年 8 月 18 日

這次更新的修改如下：

  • liveBroadcasts.update 方法的說明文件已更新，新增與營利相關的錯誤：preconditionFailed (412) (原因：videoNotEligibleForAdsMonetization) 和 backendError (503) (原因：backendError)。

2026 年 8 月 17 日

這次更新的修改如下：

  • liveBroadcast 資源的新 snippet.categoryId 屬性可讓您設定、更新和擷取與直播關聯的影片類別。

2026 年 7 月 20 日

這次更新的修改如下：

2026 年 7 月 9 日

這次更新的修改如下：

2026 年 6 月 1 日

這次更新的修改如下：

2026 年 3 月 26 日

這次更新的修改如下：

2026 年 1 月 12 日

API 現在支援為直播啟用中途廣告和自動插入中途廣告。

只要符合中途廣告資格，廣播擁有者就能選擇啟用中途廣告。擁有者也可以隨時關閉節目中的插播廣告。

如果廣播已啟用片中廣告，廣播擁有者可以選擇啟用自動插入片中廣告。他們也可以隨時關閉廣播的自動廣告。

廣播擁有者啟用自動廣告後，可以選擇下列其中一個選項：

  • 讓 YouTube 優化影片插播。這個選項支援三種模式：
    • 低：收益潛力較低，觀看時比較不受干擾
    • 中：收益潛力中等，兼顧觀看體驗和收益潛力
    • 高：收益潛力較高，觀看時較容易出現中斷
  • 手動設定片中廣告插播策略和間隔。在這種情況下，所有者必須設定兩個參數：
    1. 廣告提示點的調度策略。提示點可以同時插入到所有觀眾的螢幕上，也可以因觀眾而異地插入提示點。後者策略使 YouTube 能夠以更高的頻率安排提示點，讓觀眾在符合條件時收到提示點。
    2. 插播廣告之間的間隔時間。

為支援這項功能，文件已反映下列 API 變更：

  • liveBroadcast 資源的 monetizationDetails 物件包含用於啟用插播廣告和自動廣告配置的欄位。
  • 您可以使用 update 方法啟用或停用片中廣告。您也可以使用該方法，為現場直播設定自動廣告。這份文件列出更新現場直播的營利和自動廣告設定時，可能會發生的幾種新錯誤。

2025 年 7 月 14 日

更新 liveChatMessages.streamList 方法的說明，提供 streamList API 用法指南。

2023 年 10 月 9 日

如需參考，您可以在這個 CSV 檔案中，查看哪些貼圖 ID 與哪些超級貼圖相關。 liveChatMessage 資源的 snippet.superStickerDetails.superStickerMetadata.stickerId 屬性和 superChatEvent 資源的 snippet.superStickerMetadata.stickerId 屬性定義都已更新，反映這項資訊。

2023 年 9 月 15 日

API 現在支援一種在直播中插入廣告的新方法。除了liveCuepoints，YouTube 現在也支援自動在直播中以固定間隔插入片中廣告插播時間點，

如果廣播擁有者啟用自動廣告，就能查看廣告行為的下列層面：

  • 插播廣告之間的間隔時間。
  • 廣告提示點的調度策略。你可以為所有觀眾同時插入提示點，也可以讓不同觀眾看到不同時間的提示點。後者策略使 YouTube 能夠以更高的頻率安排提示點，讓觀眾在符合條件時收到提示點。
  • 一段不播放插播廣告的時期；對於此功能，廣播擁有者指定暫停插播廣告，直到特定時間。

為支援這項功能，文件已反映下列 API 變更：

  • liveBroadcast 資源現在包含一個 monetizationDetails 物件。該物件的欄位指示是否為廣播啟用自動廣告插入，並指定安排提示點的附加資訊。
  • liveBroadcast.list 方法的 part 參數支援 monetizationDetails 值。
  • update 方法可用於暫停現場直播的片中廣告插入作業一段時間。此外，文件現在也列出更新現場直播營利詳細資料時可能發生的幾種錯誤。

2023 年 8 月 1 日

這次更新的修改如下：

  • liveBroadcasts.update 方法不再需要為下列欄位指定值：

    • snippet.title
    • status.privacyStatus

    如果要求中省略這些欄位，系統就不會變更這些欄位。

2022 年 11 月 1 日

  • 新的 liveBroadcasts.cuepoint 方法允許任何在 YouTube 上進行直播的頻道擁有者在直播中插入提示點，從而觸發廣告插播。此方法取代了 liveCuepoints.insert 方法，該方法僅允許 YouTube 內容合作夥伴在直播中插入提示點。

    我們已更新多份指南，反映這項新方法的適用情形。

  • 注意：這是淘汰公告。

    liveCuepoints.insert 方法現已淘汰。將於 2023 年 5 月 1 日或之後移除對 liveCuepoints.insert 方法的支援。API 使用者應更新其應用程序，改為呼叫 liveBroadcasts.cuepoint 方法。

  • liveBroadcasts.control 方法的文檔已移除。我們已在 2020 年 9 月發布該方法的淘汰通知。

2022 年 10 月 1 日

這次更新的修改如下：

  • liveBroadcasts.update 方法不再需要為下列欄位指定值：

    • contentDetails.enableContentEncryption
    • contentDetails.enableDvr
    • contentDetails.enableEmbed
    • contentDetails.recordFromStart
    • contentDetails.startWithSlate

    如果要求中省略這些欄位，系統就不會變更這些欄位。

  • 移除過時 liveBroadcast 欄位的說明文件：

    • contentDetails.enableContentEncryption
    • contentDetails.startWithSlate

2022 年 4 月 1 日

這次更新的修改如下：

2021 年 9 月 15 日

這次更新的修改如下：

2020 年 12 月 1 日

API 的 liveBroadcasts.transition 方法支援新的 403 (Forbidden) 錯誤，表示使用者在特定時間範圍內傳送的請求過多。錯誤原因為 userRequestsExceedRateLimit。

2020 年 9 月 21 日

  • liveBroadcast 資源的 status.madeForKids 屬性定義已更新，明確指出該屬性為唯讀。這不代表 API 功能有所變更。

    如要將現場直播指定為針對兒童的內容，請在呼叫 liveBroadcasts.insert 方法建立直播時，將 status.selfDeclaredMadeForKids 屬性設為 true。

  • 注意：這項變更包括淘汰聲明，以及先前淘汰聲明的更新。

    liveBroadcasts.control 方法將於 2020 年 10 月 1 日當天或之後淘汰。之後，所有對這個方法的呼叫都會傳回禁止 (403) 錯誤，且這個方法稍後會完全移除。 客戶仍可自行實作片頭，方法是在傳送至 YouTube 擷取伺服器的影片中加入疊加層。

    2020 年 4 月 16 日發布的淘汰公告原定於 2020 年 9 月 1 日生效，現已延後至 2020 年 10 月 1 日當天或之後。因此，淘汰公告中列出的功能和 liveBroadcasts.control 方法都會同時淘汰。

2020 年 7 月 17 日

注意：這是先前淘汰公告的更新。

liveStream 資源的 cdn.format 欄位已於 2016 年 4 月淘汰，並將於 2020 年 8 月 17 日起停止支援。自該日期起，仍使用該欄位的要求將會失敗。

如果程式碼仍使用 cdn.format 欄位，則必須更新，分別使用 cdn.frameRate 和 cdn.resolution 屬性指定影格率和解析度。

2020 年 7 月 6 日

「透過 HLS 傳送 YouTube 直播內容」指南已更新，異動如下：

此外，新的擷取通訊協定比較會列出 YouTube 支援的擷取通訊協定、各通訊協定支援的轉碼器，以及各通訊協定的適用用途等額外資訊。

2020 年 4 月 16 日

本次更新包含一項新屬性和一項棄用公告：

  • liveBroadcast 資源現在支援 contentDetails.enableAutoStop 屬性。這個屬性表示廣播是否應在頻道擁有者停止在繫結的影片串流中串流影片後，自動停止約一分鐘。

    這廣播的生命週期document has been updated to explain how the step-by-step process of creating and managing a live YouTube event changes if you set thecontentDetails.enableAutoStart或者contentDetails.enableAutoStop屬性true。

  • 注意：這是淘汰公告。這些異動將於 2020 年 9 月 1 日當天或之後生效。下方將變更生效的實際日期稱為淘汰日期。

    本次更新說明可能發生的破壞性變更。這項異動會影響使用頻道預設 liveStream 和 liveBroadcast 資源在 YouTube 上直播內容的 API 用戶端應用程式。具體來說，與永久直播和串流相關聯的廣播 ID和串流 ID將無法再用於啟動新的廣播。

    如果符合下列任一條件，應用程式就會受到影響：

    • 檢查 liveBroadcast 資源的 isDefaultBroadcast 屬性值。淘汰日期過後，系統不會再傳回這項屬性。
    • 檢查 liveStream 資源的 isDefaultStream 屬性值。淘汰日期過後，系統不會再傳回這項屬性。
    • 這個方法會呼叫 liveBroadcasts.list 方法，並將 broadcastType 參數值設為 persistent 或 all。這項參數將在這些異動中淘汰。自淘汰日期起：
      • 如果 broadcastType 參數值為 persistent，liveBroadcasts.list 方法就不會傳回任何結果。
      • 如果 broadcastType 參數值為 all，則 liveBroadcasts.list 方法不會傳回該時間之前存在的持續性廣播。

    背景資訊：過去幾年來，只要頻道啟用直播功能，YouTube 就會自動為該頻道建立預設直播和預設廣播。預設串流會無限期存在，不會有相關聯的開始或結束時間，也無法刪除。同樣，預設廣播被認為是 持久的。這項屬性一直存在，且不與特定事件繫結。

    淘汰日期起：

    • YouTube 不再建立預設直播和廣播。API 用戶端必須能夠建立及管理 liveBroadcast 和 liveStream 資源，並將這些資源繫結在一起，而不是依賴預設資源。
    • 如果頻道預設廣播和預設串流正在直播，也就是說，頻道在淘汰生效時正在使用這些項目進行直播，則正在進行的廣播不會受到影響。不過，該場直播結束後，頻道就無法再使用預設直播和預設串流。
    • 如果頻道的預設廣播和預設串流並未處於直播狀態，則在淘汰作業生效後，YouTube 會忽略使用這些資源廣播影片的嘗試。

    如果您的應用程式受到影響，請參閱下列文件，瞭解如何更新應用程式，確保在異動後仍能正常運作：

    • 新的 遷移指南 試圖解釋開發人員在目前使用預設廣播和串流的 API 用戶端中可能需要採取的步驟。
    • 廣播生命週期指南會逐步說明如何在 YouTube 建立及管理直播活動。每個步驟都解釋了完成特定操作所需的 API 呼叫或其他事項，當 YouTube 停止支援預設串流和廣播時，您的應用程式需要遵循該流程。

2020 年 3 月 31 日

注意：這是淘汰公告。

sponsor 資源和 sponsors.list 方法已淘汰，並由 member 資源和 members.list 方法取代。

2020 年 9 月 30 日當天或之後，系統將不再支援 sponsors.list 方法。 API 用戶端應更新對 sponsors.list 方法的呼叫，改用 members.list 方法。請參閱 YouTube 資料 API 修訂歷史 以瞭解有關新資源的更多資訊。

2020 年 3 月 11 日

透過 HLS 傳送 YouTube 直播內容指南的「擷取端點」一節已更新，說明編碼器在形成主要和備份擷取網址時，應使用哪個程序完成 file= 參數值。

2020 年 2 月 4 日

我們已更新「透過 HTTP 即時串流傳送 YouTube 直播內容」指南，指出 DELETE 要求為選用項目，且 YouTube 的 HTTP 即時串流端點會忽略這些要求。基於效能考量，YouTube 建議用戶端不要傳送 DELETE 要求。

2020 年 1 月 10 日

該 API 現在支援識別針對兒童的內容，YouTube 稱之為「兒童專屬」。如要進一步瞭解「為兒童打造」的內容，請前往 YouTube 說明中心。

  • liveBroadcast 資源 支援兩項新屬性，方便內容創作者和觀眾識別「兒童專屬」內容：
    • 內容創作者可透過 selfDeclaredMadeForKids 屬性，指定現場直播是否為針對兒童的內容。透過 liveBroadcasts.insert 方法建立廣播時，可以設定這項屬性。請注意，只有在頻道擁有者授權 API 要求時，這個屬性才會納入包含 liveBroadcast 資源的 API 回應中。
    • madeForKids 屬性允許任何 API 使用者擷取廣播的「兒童專屬」狀態。舉例來說，狀態可能會根據 selfDeclaredMadeForKids 屬性的值來判斷。如要進一步瞭解如何設定頻道、影片或直播的目標觀眾，請前往 YouTube 說明中心。
  • 在 YouTube Data API 中，channel 資源也支援新的 selfDeclaredMadeForKids 和 madeForKids 屬性。

我們也更新了 YouTube API 服務的《服務條款》和《開發人員政策》。如需更多資訊，請參閱《YouTube API 服務條款 - 修訂記錄》。《YouTube API 服務條款》和《開發人員政策》的異動將於 2020 年 1 月 10 日 (太平洋時間) 生效。

2019 年 8 月 20 日

「透過 HTTP 即時串流傳送 YouTube 直播內容」指南的「需求條件」專區已更新兩項內容：

  • 該文件說明最佳做法是在每個媒體播放清單中，同時納入已確認和未結的區隔。如果伺服器端遺失媒體播放清單，這種做法可降低區隔遭略過的機率。舉例來說，每個媒體播放清單最多可包含兩個已確認的片段，以及最多五個待處理的片段。
  • 現在，每個媒體片段都必須傳送媒體播放清單。這樣一來，伺服器就能在媒體播放清單遺失時快速復原。這項做法先前列為建議。

2019 年 6 月 28 日

YouTube 現已支援 HLS 擷取。因此，liveStream 資源的 ingestionType 屬性支援新值 hls，可識別使用 HLS 擷取至 YouTube 的串流。

新的「透過 HTTP 即時串流傳送 YouTube 直播內容」指南提供相關指引，說明如何使用 HTTP 即時串流，從編碼器將直播內容串流至 YouTube。本指南旨在協助編碼器供應商在產品中新增 HLS 傳送支援。

2019 年 4 月 4 日

這次更新的修改如下：

  • 我們已更新 API 參考文件，更清楚說明各個方法的常見用途，並透過 API Explorer 小工具提供動態的高品質程式碼範例。如需範例，請參閱 liveBroadcasts.list 方法的說明文件。描述 API 方法的頁面現在有兩個新元素：

    • 您可以使用 APIs Explorer 小工具選取授權範圍、輸入範例參數和屬性值，然後傳送實際的 API 要求並查看實際的 API 回應。這個小工具也提供全螢幕檢視畫面，顯示完整的程式碼範例，並動態更新以使用您輸入的範圍和值。

    • 「常見用途」一節說明本頁面所介紹方法的一或多個常見用途。舉例來說，您可以呼叫 liveBroadcasts.list 方法來擷取特定廣播的資料，或擷取目前使用者廣播的資料。

      您可以點選該部分的連結，在 API Explorer 中填入您用途的範例值，或開啟全螢幕 API Explorer，並預先填入這些值。我們進行這些變更的目的是要讓您更輕鬆地查看直接適用於您想在自家應用程式中實作的用途的程式碼範例。

    目前支援 Java、JavaScript、PHP、Python 和 curl 的程式碼範例。

  • 「程式碼範例」頁面也採用新版 UI，提供上述所有功能。您可以使用這項工具探索不同方法的用途、將值載入 APIs Explorer，以及開啟全螢幕的 APIs Explorer，取得 Java、JavaScript、PHP 和 Python 的程式碼範例。

    配合這項異動，我們已移除先前列出 Java、PHP 和 Python 適用程式碼範例的頁面。

2019 年 2 月 25 日

liveChatMessage 和 superChatEvent 資源的說明文件已更新，現在這兩種資源都可包含超級貼圖的相關資訊。超級貼圖是超級留言訊息的一種，會顯示圖片。與其他超級留言一樣，超級貼圖訊息也是粉絲在 YouTube 直播期間購買。

  • 在 liveChatMessage 資源中，snippet.type 屬性現在會設為 superStickerEvent，表示資源包含超級貼紙的相關資訊。在這種情況下，資源也會包含 snippet.superStickerDetails 物件，其中含有超級貼圖的其他資訊。
  • 在 superChatEvent 資源中，布林值 snippet.isSuperStickerEvent 會指出超級留言訊息是否也包含超級貼圖。如果是，則 snippet.superStickerMetadata 物件會包含超級貼圖的額外詳細資料。

2018 年 4 月 5 日

superChatEvents.list 方法的說明已更新，反映 API 回應不再包含 fanFundingEvents (已於 2017 年初淘汰)。

2017 年 4 月 3 日

我們新增了 Java 程式碼範例，說明如何列出、插入及刪除即時通訊訊息。範例會呼叫下列方法：

2017 年 2 月 13 日

這次更新的修改如下：

  • 現有資源和方法的更新

    • liveCuepoints.insert 方法已更新，反映目前需要 onBehalfOfContentOwner 參數。此外，我們也更新了方法說明，指出呼叫該方法時，必須使用與 YouTube 內容擁有者相關聯的帳戶授權。

2017 年 2 月 9 日

這次更新的修改如下：

  • 現有資源和方法的更新

    • superChatEvents.list 方法的新 hl 參數可讓您指定 snippet.displayString 屬性值應根據特定語言的慣例格式化。該屬性的定義也已相應更新。

      參數值必須是 i18nLanguages.list 方法傳回清單中的語言代碼。預設值為 en，也就是說，預設行為是將顯示字串格式化為英文。舉例來說，字串預設會格式化為 $1.00，而不是 $1,00。

2017 年 2 月 1 日

這次更新的修改如下：

  • 新資源和方法

    • 新的 superChatEvent 資源代表粉絲在 YouTube 直播期間購買的超級留言訊息。在 YouTube 直播聊天室中，超級留言會以兩種方式與其他訊息區別：

      • 超級留言會以顏色醒目顯示。
      • 超級留言會在超級留言顯示區持續顯示一段時間。

      超級留言的顏色、在超級留言顯示區置頂的時間長度，以及訊息長度上限，都取決於購買金額。如要進一步瞭解超級留言，請參閱 YouTube 說明中心。

      API 支援一種方法，可列出頻道過去 30 天直播的超級留言事件。該方法也會傳回頻道上次直播的 Fan Funding 事件 (fanFundingEvents) 資料。

  • 現有資源和方法的更新

    • snippet.type 屬性現在支援 superChatEvent 值，表示資源說明的是超級留言。

      此外，liveChatMessage 資源的新 snippet.superChatDetails 屬性和其子項包含超級留言活動的相關資訊。

    • liveStream 資源的 cdn.resolution 屬性現在支援 2160p 值。

  • 新增和更新的錯誤

    • 這個 API 支援下列新錯誤：

      錯誤詳細資料
      liveBroadcasts.insert、liveBroadcasts.update liveBroadcasts.insert 和 liveBroadcasts.update 方法會傳回 400 (Bad Request) 錯誤，指出要插入或更新的 liveBroadcast 資源包含 contentDetails.enableEmbed 屬性或 contentDetails.projection 屬性的無效值。這兩個新錯誤的錯誤原因分別是 invalidEmbedSetting 和 invalidProjection。

2017 年 1 月 12 日

注意：這是淘汰公告。

YouTube 推出全新超級留言功能後，已淘汰粉絲贊助功能，並將於 2017 年 2 月 28 日停用粉絲贊助 API。自該日期起：

2016 年 8 月 11 日

這次更新的修改如下：

  • 新發布的《YouTube API 服務條款》(下稱「新版條款」) 詳述了現行《服務條款》的更新內容，詳情請參閱 YouTube 工程和開發人員網誌。除了 2017 年 2 月 10 日生效的修訂版條款，本次更新也包含多份輔助文件，協助說明開發人員必須遵守的政策。

    如要查看完整的新文件，請參閱更新版條款的修訂版本記錄。此外，修訂版本記錄也會說明日後對更新版條款或支援文件所做的變更。您可以透過文件中的連結，訂閱列出修訂記錄變更的 RSS 動態消息。

2016 年 5 月 20 日

YouTube 現在支援 DASH 擷取。因此，liveStream 資源的 ingestionType 屬性支援新值 dash，可識別使用 DASH 擷取至 YouTube 的串流。

全新的「透過 DASH 傳送 YouTube 直播內容」指南提供相關規範，說明如何使用 DASH 傳送格式，透過編碼器在 YouTube 上串流直播資料。編碼器供應商可藉此在產品中新增 DASH 傳送支援。

2016 年 4 月 18 日

這次更新的修改如下：

  • 現有資源和方法的更新

    • liveStream 資源更新

      • YouTube 現在支援解析度為 1440p 的直播，每秒 30 或 60 個影格。

        此外，liveStream 資源還包含新屬性，可指定傳入影片資料的影格速率和解析度：

        屬性
        cdn.frameRate 傳入影片資料的畫面更新率。有效值為 30fps 和 60fps。
        cdn.resolution 傳入視訊資料的解析度。有效屬性值為：1440p、1080p、720p、480p、360p 和 240p。

      • 隨著 liveStream 資源的 cdn.frameRate 和 cdn.resolution 屬性推出，資源的 cdn.format 現已淘汰。cdn.format 屬性會以單一值指定解析度和影格率。

        建議您改用新支援的欄位。在此期間，cdn.format仍可正常運作。此外，只要為 cdn.format 屬性或 cdn.frameRate 和 cdn.resolution 屬性指定值，插入直播的請求目前都會成功。如果您為這三項屬性都提供值，但這些值不一致，API 可能會傳回錯誤。

        請注意，雖然 cdn.format 屬性已淘汰，但現在支援兩個新值 1440p 和 1440p_hfr，可反映 API 對 30 或 60 FPS 1440p 串流的支援。

    • liveBroadcast 資源更新
    • liveChatMessage 資源更新

      • snippet.type 屬性支援兩個新值：messageDeletedEvent 和 userBannedEvent，分別對應於下一個項目符號所述的新屬性。此外，我們也更新了 snippet.authorChannelId 屬性的定義，說明屬性值會識別這些新訊息類型。

      • liveChatMessage 資源包含下列新屬性：

        屬性
        snippet.messageDeletedDetails 這個物件包含聊天室版主刪除的訊息相關資訊。只有在 snippet.type 屬性值為 messageDeletedEvent 時，才會顯示這個物件。
        snippet.userBannedDetails 這個物件包含遭禁止參與對話的使用者資訊。這個物件也包含禁令本身的相關資訊，也就是禁令是永久還是暫時。如果禁令是暫時性的，物件的其中一個屬性會指定禁令的期限。

        只有在 snippet.type 屬性值為 userBannedEvent 時，才會出現這個物件。

  • 新增和更新的錯誤

    • 這個 API 支援下列新錯誤：

      錯誤詳細資料
      liveBroadcasts.bind liveBroadcasts.bind 方法會傳回 403 (Forbidden) 錯誤，表示使用者在指定時間範圍內傳送過多要求。錯誤原因是 userRequestsExceedRateLimit。

      liveBroadcasts.insert 和 liveBroadcasts.update 方法已支援相同的錯誤。
      liveStreams.insert liveStreams.insert 方法支援四種新的 400 (Bad Request) 錯誤，可識別要求嘗試插入的 liveStream 資源中無效的屬性值。以下清單列出錯誤原因，以及與這些原因相關聯的屬性：
      liveStreams.insert liveStreams.insert 方法支援兩個新的 400 (Bad Request) 錯誤，分別表示要求嘗試插入的 liveStream 資源中缺少必要值。以下清單列出錯誤原因，以及與這些原因相關聯的屬性：
      具體來說，插入 liveStream 資源時，您必須為 cdn.format 屬性或 cdn.frameRate 和 cdn.resolution 屬性指定值。
      • 如果您未指定這三項屬性的值，API 會傳回 formatRequired 錯誤。
      • 如果您指定 cdn.resolution 的值，但未指定 cdn.frameRate 的值，API 會傳回 frameRateRequired 錯誤。
      • 如果您指定 cdn.frameRate 的值，但未指定 cdn.resolution 的值，API 會傳回 resolutionRequired 錯誤。
      liveStreams.update 如果要求嘗試修改下列任何不可變更的屬性值，liveStreams.update 方法會傳回 403 (Forbidden) 錯誤： 錯誤回應中的 reason 為 liveStreamModificationNotAllowed。

2015 年 12 月 18 日

根據歐盟 (EU) 法律規定，您必須向歐盟境內的使用者揭露特定資訊，並徵得同意聲明。因此，如果使用者位於歐盟地區，您必須遵守《歐盟地區使用者同意授權政策》。我們已在《YouTube API 服務條款》中新增這項規定的通知。

2015 年 12 月 17 日

這次更新的修改如下：

  • 新資源和方法

    • 這個 API 支援多項新資源，可支援直播的即時通訊功能。YouTube 在直播期間支援即時通訊功能，這些資源和方法也支援擷取即時通訊訊息，以及管理即時通訊。

      資源
      liveChatMessage 這個資源代表 YouTube 聊天室中的訊息。YouTube 支援多種訊息類型，包括文字訊息和粉絲贊助活動。部分訊息類型會標示聊天室的特定階段，例如僅限贊助者參與的階段開始或聊天室結束。這個 API 支援列出、插入及刪除聊天室訊息的方法。
      liveChatModerators 這項資源會識別聊天室版主。管理員可以執行部分管理功能，例如禁止使用者在聊天室中發言或移除訊息。這個 API 支援列出、插入及刪除聊天室管理員的方法。
      liveChatBans 這個資源會找出遭禁止在特定聊天室中發布訊息的使用者。禁令可能是暫時性或永久性。API 支援插入和刪除聊天室禁令的方法。
      fanFundingEvents 這項資源代表 YouTube 頻道的粉絲贊助活動。粉絲贊助功能可讓觀眾自願性捐款，以一次性付款的方式支持 YouTube 創作者。

      API 的 fanFundingEvents.list 方法會列出頻道的 Fan Funding 事件。如果觀眾在頻道現場直播期間透過聊天室發起粉絲贊助活動，直播聊天室也會顯示 fanFundingEvent 訊息。

      如要進一步瞭解粉絲贊助功能，請前往 YouTube 說明中心。
      sponsors sponsor 資源會識別 YouTube 頻道的贊助者。贊助者會按月支付頻道費用。贊助者在頻道聊天室中發布的訊息旁會顯示徽章，如果頻道舉辦贊助者專屬聊天室，贊助者也能參與。

      API 的 sponsors.list 方法會列出頻道的贊助者。當使用者在頻道擁有的現場直播期間註冊贊助頻道時，API 也會將 newSponsorEvent 訊息新增至直播的聊天室。

      瞭解更多關於贊助的資訊，請前往 YouTube 說明中心。

  • 現有資源和方法的更新

    • liveBroadcast 資源包含下列新屬性：

      屬性
      snippet.liveChatId YouTube 廣播直播聊天室的 ID。有了這個 ID，您就能使用 liveChatMessage 資源的方法，擷取、插入或刪除即時通訊訊息。你也可以新增或移除聊天室管理員、禁止使用者參與聊天室，或移除現有的禁令。
      contentDetails.closedCaptionsType 注意：這項屬性會取代 contentDetails.enableClosedCaptions 屬性。

      這項屬性會指出是否為廣播啟用隱藏式輔助字幕，以及提供的隱藏式輔助字幕類型：
      • closedCaptionsDisabled：現場直播已停用隱藏式輔助字幕。
      • closedCaptionsHttpPost：您將透過 HTTP POST，將字幕傳送至與直播相關聯的擷取網址。
      • closedCaptionsEmbedded：系統會使用 EIA-608 和/或 CEA-708 格式，將字幕編碼至影片串流中。
      contentDetails.enableClosedCaptions 這項屬性已於 2015 年 12 月 17 日淘汰。請改用 contentDetails.closedCaptionsType 屬性。如果 API 用戶端已使用這項資源：
      • 將屬性值設為 true，等同於將 contentDetails.closedCaptionsType 屬性設為 closedCaptionsHttpPost。
      • 將屬性值設為 false，等同於將 contentDetails.closedCaptionsType 屬性設為 closedCaptionsDisabled。

    • liveBroadcasts.list 方法的新 broadcastType 參數可讓您篩選 API 回應，只納入活動廣播、持續性廣播或所有廣播。

      永久廣播是指持續存在且未綁定特定活動的廣播。具體來說，頻道的預設廣播是持續性廣播，可透過 YouTube 創作者工作室的直播資訊主頁存取。頻道其他直播則為活動直播。

  • liveStream 資源的 status.healthStatus.configurationIssues[].type 欄位會回報下列新的健康狀態錯誤：

    錯誤
    audioTooManyChannels 音訊有超過兩個聲道，但系統只支援一個聲道 (單聲道) 或兩個聲道 (立體聲)。請修改音訊聲道數量。
    frameRateHigh 目前的影格速率過高，請將畫面更新率設為 %(framerate)s FPS 以下。

  • 先前文件更新的發布日期已更正。

  • 新增和更新的錯誤

    • 除了上述新資源定義的錯誤外，API 還支援下列新錯誤：

      錯誤詳細資料
      liveBroadcasts.update
      HTTP 回應代碼forbidden (403)
      原因closedCaptionsTypeModificationNotAllowed
      說明只有在廣播處於 created 或 ready 狀態時，才能修改 contentDetails.closedCaptionsType 值。
      liveBroadcasts.update
      HTTP 回應代碼invalidValue (400)
      原因invalidEnableClosedCaptions
      說明在liveBroadcast 資源中，「contentDetails.enableClosedCaptions」屬性的值與「contentDetails.closedCaptionType」設定的值不相容。修改資源，只包含這兩個屬性的其中之一，然後重新提交要求。

2015 年 8 月 19 日

這次更新的修改如下：

  • 新資源和方法

    • 注意：liveChat 資源及其方法的說明文件屬於機密資訊，只有特定 YouTube 合作夥伴才能查看。

      新的 liveChat 資源包含在 YouTube 現場直播期間發布的留言。這個 API 支援兩種資源方法：

      方法
      liveChats.list 列出廣播的聊天室訊息。
      liveChats.insert 建立新的即時通訊訊息。

      只有在直播進行期間才能檢索和發布即時聊天訊息。

  • 現有資源和方法的更新

    • liveStream 資源包含下列新屬性：

      屬性
      snippet.isDefaultStream 指出這個串流是否為頻道的預設串流。頻道的預設直播會無限期存在，沒有相關聯的開始或結束時間，也無法刪除。如要進一步瞭解預設資料串流的運作方式，請參閱資源的定義。
      status.healthStatus 這個物件包含可用於識別、診斷及解決串流問題的資訊。這個物件包含多個子項屬性，可協助您評估即時影像串流的健康狀態。

      特別是 status.healthStatus.configurationIssues[] 物件，會列出影響影片串流的問題。新文件「LiveStream 資源的設定問題」列出 API 報告的所有問題。
      contentDetails.isReusable 指出串流是否可重複使用，也就是說，串流是否可繫結至多個廣播。如果廣播時間不同，廣播主通常會重複使用同一個串流進行多場廣播。

    • liveBroadcast 資源包含下列新屬性：

      屬性
      snippet.isDefaultBroadcast 指出這項廣播是否為頻道的預設廣播。啟用 YouTube 頻道的直播功能後，YouTube 會為該頻道建立預設直播和預設廣播。串流是指頻道擁有者將即時影像傳送至 YouTube 的方式，而廣播則是觀眾觀看預設串流的方式。如要進一步瞭解預設廣播的運作方式，請參閱屬性的定義。
      contentDetails.enableLowLatency 指出是否應編碼此廣播，以進行低延遲串流。低延遲串流可縮短影片顯示給廣播觀眾的時間，但也會影響串流觀眾的解析度。
      statistics.totalChatCount 與廣播相關的聊天室訊息總數。如果使用者可以觀看廣播，且廣播已啟用即時通訊功能，就會顯示這項屬性和值。請注意，廣播結束後，這項屬性不會指定值。因此，這項屬性不會識別已完成現場直播的封存影片即時通訊訊息數。

  • 新增和更新的錯誤

    • 除了為新 liveChat 資源定義的錯誤之外，API 還支援下列新錯誤：

      錯誤詳細資料
      liveStreams.update
      HTTP 回應代碼forbidden (403)
      原因liveStreamModificationNotAllowed
      說明API 不允許您將可重複使用的串流變更為不可重複使用，反之亦然。詳情請參閱「瞭解廣播和串流」

2015 年 5 月 21 日

這次更新的修改如下：

  • YouTube 現在支援每秒 60 畫格數 (fps) 的直播影片，因此播放遊戲和其他快速動作影片時會更加流暢。在 YouTube 上以 60 FPS 開始直播時，YouTube 也會在尚不支援高影格率觀看的裝置上，以 30 FPS 提供直播。

    liveStream 資源的 cdn.format 屬性支援這項功能的兩個新值：720p_hfr 和 1080p_hfr。

    如要進一步瞭解這項功能，請參閱 YouTube 創作者網誌。

2014 年 8 月 21 日

這次更新的修改如下：

  • liveBroadcasts.control 方法的 walltime 參數定義已更新，指出屬性值是以 ISO 8601 格式 (YYYY-MM-DDThh:mm:ss.sssZ) 指定。

  • 這個 API 現在支援下列錯誤：

    錯誤類型 錯誤詳細資料 說明
    insufficientPermissions liveStreamingNotEnabled 如果授權 API 要求的使用者未啟用 YouTube 即時影像功能，liveBroadcast 和 liveStream 資源的所有方法都會傳回這項錯誤。如要瞭解使用者無法直播即時影像的原因，請前往 https://www.youtube.com/features 查看頻道設定。
    rateLimitExceeded userRequestsExceedRateLimit liveBroadcasts.insert 和 liveStreams.insert 方法都會傳回這項錯誤，表示使用者在指定時間範圍內傳送過多要求。

2014 年 5 月 2 日

這次更新的修改如下：

  • liveStream 資源和 liveBroadcasts.bind 方法的說明已更新，指出一個廣播只能繫結至一個影片串流，但一個影片串流可以繫結至多個廣播。這項異動只會修正說明文件，基礎 API 功能並未變更。

  • liveBroadcast 資源的 contentDetails.monitorStream.enableMonitorStream 屬性已更新，說明如果屬性值為 true，則必須先將廣播轉換為 testing 狀態，才能轉換為 live 狀態。(如果屬性的值為 false，廣播就不能有 testing 階段，因此你可以直接將廣播轉換為 live 狀態。

  • liveCuepoint 資源的 settings.offsetTimeMs 屬性已更新，指出如果廣播沒有監控串流，就不應為該屬性指定值。

  • liveBroadcast 和 liveStream 資源的所有方法現在都支援 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 參數。您可以使用這些參數，透過相同的授權憑證，為與同一位內容擁有者相關聯的不同頻道完成 API 要求。

  • liveCuepoints.insert 方法的說明文件已更新，指出您可以在呼叫該方法時設定 settings.walltime 屬性的值。

  • 錯誤說明文件現在會針對每種錯誤類型指定 HTTP 回應代碼。

  • API 現在支援下列錯誤：

    錯誤類型 錯誤詳細資料 說明
    insufficientPermissions livePermissionBlocked 如果授權要求的使用者無法在 YouTube 上直播即時影像，liveBroadcasts.insert、liveBroadcasts.transition 和 liveStreams.insert 方法會傳回這項錯誤。如要瞭解使用者無法直播即時影像的原因，請前往 https://www.youtube.com/features 查看頻道設定。

  • liveBroadcasts.insert 方法的 invalidScheduledStartTime 錯誤已更新，明確指出排定的開始時間必須與目前日期相近，才能在該時間可靠地排定廣播。

2013 年 12 月 13 日

這次更新的修改如下：

  • liveBroadcast 資源的新 status.recordingStatus 屬性會指明廣播的目前狀態。

  • liveBroadcast 資源的新 contentDetails.enableClosedCaptions 屬性會指出是否可擷取廣播的隱藏式輔助字幕。插入或更新直播時可以設定屬性值，但直播處於 testing 或 live 狀態時，就無法更新屬性值。如果將這項屬性設為 true，則繫結至廣播的 liveStream 資源會指定用於廣播隱藏式輔助字幕的擷取網址。

  • liveBroadcast 資源的 snippet.scheduledEndTime 屬性現在支援預定無限期持續播送的節目。這項異動生效後，liveBroadcasts.insert 和 liveBroadcasts.update 請求就不再需要這個屬性。

    如果擷取的 liveBroadcast 資源未指定這個屬性的值，廣播就會無限期持續排定。同樣地，如果您呼叫 liveBroadcasts.insert 或 liveBroadcasts.update 方法，但未指定這項屬性的值，系統就會排定無限期繼續播放廣播。

  • 如果廣播頻道可以停用直播錄製功能，則 liveBroadcast 資源的 contentDetails.recordFromStart 屬性 (預設值為 true) 現在只能設為 false。

    如果您的頻道沒有停用錄製的權限，並且您嘗試插入一個廣播，並將 recordFromStart 屬性設為 false，則 API 將傳回 Forbidden 錯誤。此外，如果頻道沒有這項權限，且您嘗試更新直播，將 recordFromStart 屬性設為 false，API 會傳回 modificationNotAllowed 錯誤。

  • liveBroadcast 資源不再包含 enableArchive 屬性，該屬性已在 contentDetails.enableDvr 和 contentDetails.enableEmbed 屬性的說明中提及。

  • liveBroadcast 資源的 status.lifeCycleStatus 屬性有效值清單已更新，現在會說明每個狀態。

  • liveCuepoint 資源的新 settings.walltime 屬性指定了提示點應插入的日期和時間。如果要求嘗試插入指定這個屬性和 settings.offsetTimeMs 屬性值的提示點，API 就會傳回錯誤。

  • liveStream 資源中的新 contentDetails 物件包含串流相關資訊。目前物件的唯一屬性是 contentDetails.closedCaptionsIngestionUrl，用於指定與影片串流相關聯的隱藏式輔助字幕擷取網址。

  • liveStream 資源的 status.streamStatus 屬性有效值清單已更新，現在會說明每個狀態。

  • liveBroadcasts.control 方法的新 walltime 參數可讓您指定節目表變更的日期和時間。如果要求同時為這個參數和 offsetTimeMs 參數指定值，API 就會傳回錯誤。

  • 在 liveBroadcasts.list 要求的 API 回應中，kind 屬性的值已從 youtube#liveBroadcastList 變更為 youtube#liveBroadcastListResponse。

  • 在 liveStreams.list 要求的 API 回應中，kind 屬性的值已從 youtube#liveStreamList 變更為 youtube#liveStreamListResponse。

  • eventId 屬性已從 liveBroadcastListResponse 和 liveStreamListResponse 中淘汰。

  • 這個 API 支援下列新錯誤：

    錯誤類型 錯誤詳細資料 說明
    invalidValue conflictingTimeFields 如果要求為 offsetTimeMs 和 walltime 參數指定值，liveBroadcasts.control 方法就會傳回這項錯誤。請求可以省略兩個參數，也可以為其中一個參數指定值。
    invalidValue invalidWalltime 如果 walltime 參數的值無效，liveBroadcasts.control 方法就會傳回這項錯誤。
    forbidden enableClosedCaptionsModificationNotAllowed 如果您嘗試更新 contentDetails.enableClosedCaptions 值，但廣播狀態不是 created 或 ready，liveBroadcasts.update 方法就會傳回這項錯誤。
    invalidValue conflictingTimeFields 如果您的請求為 settings.offsetTimeMs 和 settings.walltime 屬性指定了值，則 liveCuepoints.insert 方法會傳回此錯誤。請求可以省略這兩個屬性，也可以為其中一個屬性指定值。

    此外，liveStreams.update 方法不再支援與 liveStreams.insert 方法支援的錯誤類似的 cdnRequired 錯誤。

2013 年 5 月 10 日

這次更新的修改如下：

2013 年 5 月 2 日

這次更新的修改如下：

2013 年 3 月 27 日

這次更新的修改如下：

  • liveBroadcast 資源的下列屬性已變更：

    • startWithSlateCuepoint 屬性已重新命名為 startWithSlate。
    • enableArchive 屬性已重新命名為 recordFromStart。
    • slateSettings 物件已淘汰，並從說明文件中移除。與 slateSettings 物件或其屬性相關的錯誤訊息也已移除。最後，我們移除了「開始使用」指南的「顯示 Slate」部分。

  • API 不再支援使用 liveCuepoints.insert 方法插入串流內廣告字卡。為反映本次異動，我們更新了下列文件：

    • 索引頁面、「開始使用」指南和「廣播的生命週期」教學課程不再提及這項功能。

    • liveCuepoint 資源的 settings.cueType 屬性不再支援 slate 做為屬性值。(目前唯一支援的值是 ad。

    • liveCuepoint 資源的 settings.eventState 屬性已被棄用，並從文件中移除。

2013 年 3 月 18 日

這次更新的修改如下：

  • 所有 API 的錯誤訊息都已更新，可更清楚地說明可能發生的錯誤，並盡可能提供修正指引。

  • API 現在可能會傳回數個新錯誤。下表列出錯誤和可能傳回該錯誤的 API 方法：

  • liveStream 資源文件已更新，以反映多播和 WebM 不是先前所指的支援的攝取方法。cdn.format 屬性的格式清單已相應更新，且 cdn.multicastIngestionInfo 物件及其子項屬性已從資源的說明文件中移除。此外，系統已從支援的 cdn.ingestionType 值清單中移除 http。