本頁面列出 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 日
這次更新的修改如下:
-
snippet.type
屬性現在支援兩個新值:membershipGiftingEvent
giftMembershipReceivedEvent
-
liveChatMessage
資源的新snippet.membershipGiftingDetails
屬性及其子項包含會籍贈送活動的相關資訊。同樣地,新的snippet.giftMembershipReceivedDetails
屬性及其子項也包含「已收到贈送會籍」事件的相關資訊。
2021 年 9 月 15 日
這次更新的修改如下:
-
snippet.type
屬性現在支援兩個新值:newSponsorEvent
memberMilestoneChatEvent
-
liveChatMessage
資源的新snippet.memberMilestoneChatDetails
屬性及其子項包含會員里程碑即時通訊活動的相關資訊。同樣地,新的snippet.newSponsorDetails
屬性及其子項也包含新贊助商事件的相關資訊。
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 就會忽略嘗試使用這些資源來播送影片。
若您的應用程式受到影響,請參考下列文件,這有助於您更新應用程式,確保應用程式在本次異動後能正常運作:
- 並檢查
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 直播期間購買了超級貼圖訊息。
- 在
liveChatMessage
資源中,snippet.type
屬性現在會設為superStickerEvent
,表示資源包含超級貼圖相關資訊。在這種情況下,資源也會包含snippet.superStickerDetails
物件,其中包含超級貼圖的額外資訊。 - 在
superChatEvent
資源中,布林值snippet.isSuperStickerEvent
表示超級留言訊息是否為超級貼圖。如果是的話,snippet.superStickerMetadata
物件會包含超級貼圖的其他詳細資料。
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。截至上述日期為止:
liveChatMessages.list
方法不會再傳回snippet.type
為fanFundingEvent
的訊息。同樣地,liveChatMessage
資源將不再包含snippet.fanFundingEventDetails
物件。fanFundingEvents.list
方法不會再傳回資料。
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
資源更新-
liveBroadcast
資源包含下列新屬性:屬性 contentDetails.boundStreamLastUpdateTimeMs
廣播的 contentDetails.boundStreamId
屬性所參照的直播上次更新時間。contentDetails.projection
廣播的投影格式。屬性的預設值是 rectangular
。屬性的有效值包括360
和rectangular
。 -
已更新
liveBroadcast
資源的statistics.totalChatCount
屬性定義,請注意,只有在直播包含至少一則即時通訊訊息時,系統才會顯示屬性值。
-
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
資源中的無效屬性值。以下列出錯誤原因及相關的屬性:
invalidFormat
:cdn.format
invalidFrameRate
:cdn.frameRate
invalidIngestionType
:cdn.ingestionType
invalidResolution
:cdn.resolution
liveStreams.insert
liveStreams.insert
方法支援兩個新的400
(Bad Request
) 錯誤,每個錯誤都代表要求插入的liveStream
資源中沒有必要值。以下列出錯誤原因及相關的屬性:
frameRateRequired
:cdn.frameRate
resolutionRequired
:cdn.resolution
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
) 錯誤:cdn.format
cdn.frameRate
cdn.ingestionType
cdn.resolution
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
目前的影格速率過高。請將影格速率設為 fps 以下。%(framerate)s
-
上一次說明文件更新的發布日期已修正。
-
新錯誤和更新後的錯誤
-
除了針對上述新資源定義的錯誤以外,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 日
這次更新的修改如下:
-
YouTube 已不再識別實驗性 API 功能和服務。而現在我們改為提供受到廢止政策影響的 YouTube API 清單。
2013 年 5 月 2 日
這次更新的修改如下:
-
新的
liveBroadcasts.control
方法可讓您針對正在進行的廣播,切換在廣播串流中顯示的插入畫面顯示設定。如果廣播串流發生延遲,您也可以使用這個方法,指定系統要求插入畫面變更的時間偏移。 -
下列屬性的定義已更新,說明如果更新
liveBroadcast
資源的contentDetails
部分,則必須設定屬性值: -
liveStream
資源的status.streamStatus
不再支援deleted
值做為可能的串流狀態。 -
API 針對許多錯誤訊息傳回的資訊已經過修訂,以進一步說明發生特定錯誤的原因。另外,這個 API 也支援多種新錯誤。
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 方法:
liveBroadcasts.insert
:播送排定的結束時間必須晚於排定的開始時間。liveBroadcasts.insert
- 廣播指定了無效的隱私權狀態。liveBroadcasts.update
- 資源未包含或未設定contentDetails.enableArchive
屬性的值。liveBroadcasts.update
- 資源未包含或未設定contentDetails.enableContentEncryption
屬性的值。liveBroadcasts.update
- 資源未包含或未設定contentDetails.enableDvr
屬性的值。liveStreams.insert
:摘要標題長度必須介於 1 到 128 個字元之間。liveStreams.update
- 資源未包含或未設定snippet.title
屬性的值。
-
liveStream
資源說明文件已更新,以反映多播和 WebM 均不支援先前說明的擷取方法。cdn.format
屬性的格式清單已隨之更新,cdn.multicastIngestionInfo
物件及其子項屬性已從資源的說明文件中移除。此外,http
已從支援的cdn.ingestionType
值清單中移除。