YouTube Live Streaming API - 修訂版本記錄

本頁面列出 YouTube Live Streaming 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 日

注意：這是先前淘汰的公告內容。

自 2020 年 4 月 17 日起，我們將不再支援 liveStream 資源的 cdn.format 欄位。但自該日期起，使用該欄位的要求都會失敗。

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

2020 年 7 月 6 日

我們更新了「透過 HLS 提交 YouTube 直播內容」指南，當中做出了幾項異動：

  • 媒體區隔的建議時間長度已更新為 1 到 4 秒。
  • 新章節將說明如何從 YouTube 工作室取得 HLS 擷取網址。
  • 用於設定 file 參數值格式的操作說明已移至新的「完成 HLS 擷取網址」一節。無論透過 YouTube API 或 YouTube 工作室取得 HLS 內容擷取網址，都適用這些操作說明。

此外，新的擷取通訊協定比較會列出 YouTube 支援的內容擷取通訊協定、每種通訊協定支援的轉碼器，以及各種通訊協定適用用途的其他相關資訊。

2020 年 4 月 16 日

本次更新包含新屬性和淘汰公告：

  • liveBroadcast 資源現在支援 contentDetails.enableAutoStop 屬性。這個屬性會指出頻道擁有者是否在繫結影片串流上停止串流影片後，是否要在一分鐘左右自動停止播送。

    將 contentDetails.enableAutoStart 或 contentDetails.enableAutoStop 屬性設為 true 時，廣播生命週期文件已更新，以說明建立和管理現場 YouTube 活動的逐步程序異動。

  • 注意：這是淘汰公告。這些變更將於 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 Data API 修訂版本記錄。

2020 年 3 月 11 日

我們更新了「透過 HLS 提交直播 YouTube 內容」指南的「擷取端點」一節，闡明編碼器在組成主要和備份內容擷取網址時，應使用何種程序完成 file= 參數值。

2020 年 2 月 4 日

更新透過 HLS 提交 YouTube 內容指南，說明 DELETE 要求為選用性質，YouTube 的 HLS 端點會予以忽略。基於效能考量，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 日

透過 HLS 提交 YouTube 直播內容指南的「相關規定」一節已更新，並有兩項異動：

  • 最佳做法是在各媒體播放清單中同時加入已確認的片段和優質區隔。這種做法可避免在伺服器端遺失媒體播放清單時，略過片段遭到略過的可能性。例如，您可以在每個媒體播放清單中加入最多兩個已確認的片段，以及五個未處理的區段。
  • 現在必須為每個媒體區隔傳送媒體播放清單。這可讓伺服器在媒體播放清單遺失時快速復原。這項做法先前已列為建議。

2019 年 6 月 28 日

YouTube 現已支援 HTTP 即時串流的內容攝入。因此，liveStream 資源的 ingestionType 屬性支援新的值 hls，以識別使用 HTTP 即時串流擷取到 YouTube 的串流。

新版透過 HLS 提交 YouTube 直播內容指南提供了相關指南，說明如何使用 HTTP 即時串流，將直播內容從編碼器串流至 YouTube。這份指南旨在協助編碼器供應商在產品中加入 HTTP 即時串流 (HLS) 放送支援。

2019 年 4 月 4 日

這次更新的修改如下：

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

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

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

      您可以使用該部分的連結，在 APIs Explorer 中為您的用途填入範例值，或是開啟已填入這些值的全螢幕 APIs Explorer。這些異動旨在讓您更輕鬆地查看程式碼範例，以便直接適用於您在自己的應用程式中實作的用途。

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

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

    由於這項變更，先前列出的 Java、PHP 和 Python 程式碼範例網頁也已一併移除。

2019 年 2 月 25 日

更新 liveChatMessage 和 superChatEvent 資源的說明文件，指出這兩項資源現在可包含超級貼圖的相關資訊。超級貼圖是超級留言的其中一種訊息，當中會顯示圖片，如同其他超級留言，粉絲在 YouTube 直播期間購買了超級貼圖訊息。

2018 年 4 月 5 日

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

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 天內頻道直播影片的超級留言活動清單。這個方法也會傳回頻道上次直播的粉絲贊助活動 (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 目前支援每秒 30 或 60 個影格的 1440p 直播影片。

        此外，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 對 1440p 串流的支援，為每秒 30 或 60 個影格。

    • 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 這項資源會指出使用者遭到停權，因此無法在特定聊天室中發布訊息。Bans 可能是臨時性或永久性的。這個 API 支援插入及刪除聊天室禁用方法。
      fanFundingEvents 這項資源代表 YouTube 頻道上的粉絲贊助活動。粉絲贊助功能可讓觀眾自由地支持 YouTube 創作者並提供一次性的金錢支援。

      API 的 fanFundingEvents.list 方法會列出頻道的粉絲贊助活動。在頻道擁有的現場直播期間，透過聊天室啟動的粉絲贊助活動也會觸發 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。

  • liveBroadcastListResponse 和 liveStreamListResponse 已淘汰 eventId 屬性。

  • 這個 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 物件或其屬性相關的錯誤訊息也已移除。最後，《入門指南》的「顯示插入畫面」部分已遭到移除。

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

    • 索引頁面、入門指南和廣播生命週期教學課程不再提及這項功能。

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

    • liveCuepoint 資源的 settings.eventState 屬性已淘汰，並從說明文件中移除。

2013 年 3 月 18 日

這次更新的修改如下：

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

  • API 現在可能會傳回數個新的錯誤。以下清單列出錯誤，以及可能傳回該錯誤的 API 方法：

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