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 年 9 月 1 日發布的淘汰公告 (2020 年 4 月 16 日) 的淘汰日期現已延後，現在將於 2020 年 10 月 1 日當天或之後推送。因此，該淘汰公告中包含的功能和 liveBroadcasts.control 方法都會同時淘汰。

2020 年 7 月 17 日

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

自 2020 年 8 月 17 日起，我們將停止支援 liveStream 資源的 cdn.format 欄位 (已於 2016 年 4 月停用)。自該日期起，使用該欄位的請求就會失敗。

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

2020 年 7 月 6 日

我們已更新透過 HTTP 即時串流技術提供 YouTube 直播內容指南，並做出以下幾項異動：

此外，新的擷取通訊協定比較會列出 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 日

透過 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 日

透過 HLS 提供 YouTube 直播內容指南的「必要條件」部分已更新，新增兩項變更：

  • 解釋是最佳做法，在每個媒體播放清單中同時納入已確認的片段和主要區段。這樣一來，如果伺服器端遺失媒體播放清單，就比較不會跳過某個片段。舉例來說，您最多可在每個媒體播放清單中加入兩個已確認的區隔，以及最多五個待確認的區隔。
  • 每個媒體區段現在都必須傳送媒體播放清單。這樣一來，如果媒體播放清單遺失，伺服器就能快速復原。這項做法先前列為建議做法。

2019 年 6 月 28 日

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

全新的「透過 HLS 串流播放 YouTube 直播內容」指南提供使用 HLS 從編碼器串流播放直播內容至 YouTube 的規範。本指南旨在協助編碼器廠商為產品新增 HTTP 即時串流放送支援功能。

2019 年 4 月 4 日

這次更新的修改如下：

  • 我們已更新 API 參考文件，以便更詳細說明各個方法的常見用途，並透過 API Explorer 小工具提供動態且品質優良的程式碼範例。詳情請參閱 liveBroadcasts.list 方法的說明文件。說明 API 方法的頁面現在有兩個新元素：

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

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

      您可以使用該部分中的連結，為 API Explorer 填入用例的範例值，或是開啟已填入這些值的全螢幕 API Explorer。這些變更的目的，是讓您更輕鬆地查看程式碼範例，這些範例可直接套用至您嘗試在應用程式中導入的用途。

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

  • 程式碼範例頁面也採用了新的使用者介面，提供上述所有功能。透過該工具，您可以探索不同方法的用途、將值載入 APIs Explorer，以及開啟全螢幕 API 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 天內頻道直播影片的超級留言事件。這個方法也會傳回頻道上次直播的粉絲贊助事件資料 (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 上串流直播資料。這項 API 旨在協助編碼器供應商在產品中加入 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 張影格的速度，串流傳送 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 方法會列出頻道的粉絲贊助活動。在頻道直播期間透過聊天室發起的粉絲贊助活動，也會觸發系統傳送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 上以 60fps 開始直播時，如果裝置尚未支援高幀率觀看，YouTube 也會以 30fps 播放直播。

    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 屬性會指定應插入 Cue Point 的日期和時間。如果要求嘗試插入的提示點為這個屬性和 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 方法不再支援 cdnRequired 錯誤，這類錯誤與 liveStreams.insert 方法支援的錯誤類似。

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 資源說明文件已更新，反映出 multicast 和 WebM 並非如先前所述的擷取方法。cdn.format 屬性的格式清單已相應更新，且資源說明文件已移除 cdn.multicastIngestionInfo 物件及其子項屬性。此外，系統已從支援的 cdn.ingestionType 值清單中移除 http。