YouTube 上傳失敗可能會回傳錯誤代碼 453(逾時)或 454
(服務無法使用),並附上
retryAvailable: true。你的整合可以依此旗標
自動以退避(backoff)重試暫時性失敗。完整清單請參閱
錯誤代碼參考。發布到 YouTube
發布概觀
使用 YouTube API 發布內容時,需要在youTubeOptions 物件中至少提供 title 參數 — 最多 100 個字元。
title 是唯一的必填欄位,且可透過 transcribe 端點 自動產生。
例如,使用預設設定發布 YouTube 影片:
YouTube Post
private,但可將可見性設為 public 或 unlisted。
可選欄位的詳細說明請參閱下方。
YouTube 貼文的可選欄位
下方列出了其他多個可選欄位,包含影片的visibility、tags 與 publishAt 日期。詳細需求與說明請參閱各欄位的註解。
YouTube Post Optional Fields
title必須為 100 個字元以下。post必須為 5,000 個字元以下。post與title可包含任何字元,但不允許 < 與 >。- Playlist ID 可透過在瀏覽器中開啟該播放清單、複製
list=後的值取得。已驗證的使用者與 channel 必須是該播放清單的擁有者才能加入影片。 - 如果你的影片副檔名不是常見的影片格式(例如 mp4),請使用
isVideo參數。詳情請參閱 /post 端點。 publishAt欄位讓 YouTube 控制發布時間。 在該發布時間之前,影片會維持為 private,到達發布時間後才會轉為公開。 如果發布時間為過去時間,影片會立即被設為公開。 使用publishAt欄位時,不要同時使用貼文的scheduleDate欄位。containsSyntheticMedia欄位用來揭露該影片包含逼真的 Altered 或 Synthetic(A/S)內容:讓真實人物看起來說了或做了他們實際上並沒有說或做的事、竄改真實事件或地點的畫面,或產生實際上並未發生的擬真場景。license— 設定影片的授權類型。可接受的值:"youtube"(Standard YouTube License,預設)或"creativeCommon"(Creative Commons - Attribution)。embeddable— Boolean(或字串"true"/"false")。控制影片是否可以嵌入到第三方網站。預設:true。publicStatsViewable— Boolean(或字串"true"/"false")。控制影片觀看頁上的擴充統計面板是否可公開檢視。基本的觀看次數與按讚數不論此設定為何都會維持公開可見。預設:true。詳情請參閱 YouTube Data API 參考中的status.publicStatsViewable。- 更多資訊請參閱 YouTube 媒體指南。
營利與內容控制
madeForKids、license、embeddable 與 publicStatsViewable 這些欄位可在上傳時透過 Ayrshare API 設定。然而,直接的營利開關(啟用/停用廣告)、廣告類型選擇(pre-roll、mid-roll、post-roll)、收益分成與 Content ID 都需要 YouTube CMS 憑證 — 這些僅提供給 MCN 與企業內容擁有者 — 因此無法透過標準的 YouTube OAuth 或 Ayrshare API 進行設定。YouTube Shorts
YouTube Short 是一種短影音直式影片,長度最多可達三分鐘。 它類似於 TikTok 影片,以及 Instagram 或 Facebook Reels。發布 YouTube Shorts
在youTubeOptions 物件中加入 shorts 參數,即可發布最長 3 分鐘的 YouTube Shorts 影片。
YouTube Shorts Post
YouTube Shorts 的重要資訊
- 將影片以 Short 發送只是向 YouTube 表明你希望該影片以 Short 呈現,但並不保證 一定會以 Short 呈現。該影片必須符合 Short 影片的需求(例如 3 分鐘以內、9:16 直式比例), YouTube 才會將其視為 Short。
- YouTube Shorts 不支援縮圖。
- 更多關於使用 API 發布 YouTube Shorts 的資訊。
YouTube 縮圖
自訂縮圖需要已驗證的 YouTube channel。縮圖套用失敗(但影片仍成功發布)最常見的原因就是 channel 未經驗證 — 請至 https://www.youtube.com/verify(電話驗證)進行驗證。你的
thumbNail 也必須是 PNG 或 JPG/JPEG 格式、2MB 以下,並來自可存取的 URL;Ayrshare 會在可能的情況下於發布前驗證這些條件。當影片發布成功但縮圖套用失敗時,YouTube 結果仍會維持 status: "success",並加上一個 warnings 陣列(feature: "thumbnail"、code: 307)描述失敗原因。完整解法請參閱 YouTube 縮圖未套用(Channel 未驗證)。加入 YouTube 縮圖
YouTube 縮圖以及其他功能(例如上傳 15 分鐘影片),都需要驗證你的電話號碼。thumbNail 是 JPEG 或 PNG 檔案的 URL,且大小需小於 2MB。副檔名必須為 png、jpg 或 jpeg。
YouTube Thumbnail
在 YouTube Studio 中啟用縮圖
你必須取得 YouTube 權限才能發布縮圖。在 YouTube Studio 中前往 Settings->Channel。選擇「Feature Eligibility」並點擊「Features that require phone verification」,輸入你的電話號碼即可啟用。
影片:透過 API 發布到 YouTube
上傳限制
YouTube 透過 YouTube API 限制每個 channel 在 24 小時內能上傳的影片數量。- 依創作者的所在地不同,channel 可能可以透過取得進階功能來提高每日的上限。 詳情請參閱這篇 文章。
- 上限可能會因國家/地區或 channel 歷史而有所不同。著作權違規可能會影響 channel 歷史的資格,而 社群規範 違規 則會影響 channel 可上傳的數量。
描述連結
你必須在 YouTube Studio 中啟用 Advanced Features,YouTube 影片描述中的連結才能點擊。 前往 YouTube Studio -> Settings -> Channel -> Feature Eligibility -> Advanced Features -> Access Features 來啟用進階功能。
播放清單
透過在youTubeOptions 物件中加入 playListId,可以將影片加入 YouTube 播放清單。
請確認已驗證的使用者與 channel 是該播放清單的擁有者。
YouTube Playlist
影片字幕
你可以透過在youTubeOptions 物件中提供 SRT 檔案 或 YouTube SBV 檔案 為影片加上 YouTube 字幕(YouTube captions)。使用 subTitleUrl 欄位指定你的 SRT 或 SBV 檔案的 URL。
YouTube Subtitles
subTitleUrl:有效的 SRT 或 SBV 檔案。URL 必須以https://開頭並以.srt或.sbv結尾,且為有效的 SRT 或 SBV 檔案。檔案大小必須小於 100 MB。subTitleLanguage:選填:字幕的語言。必須是有效的 語言 代碼。預設:“en”。subTitleName:選填:字幕軌道的名稱。此名稱在播放時會顯示給 使用者作為選項。最多可支援 150 個字元。 預設:“English”。
什麼是 SRT 與 SBV 檔案?SRT(SubRip Subtitle)與 SBV(YouTube SubViewer)是字幕檔案格式,用於在影片中顯示
帶有時間軸的文字。兩者主要差異在於 SRT 使用 HH:MM:SS,MS 格式的時間戳並以箭頭分隔,
而 SBV 則使用 HH:MM:SS.MS 格式並以逗號分隔。
Tags
透過在youTubeOptions 物件中加入 tags 陣列,即可為影片加上 YouTube 標籤。
每個標籤至少須有 2 個字元,且所有標籤合計長度須為 500 個字元以下。
YouTube Tags
YouTube 提及
雖然你可以在 YouTube 貼文中加入@handle,但 YouTube 不會解析貼文文字中的提及。
@handle 將保持為純文字顯示。
