Captions

注意:YouTube 於 2024 年 3 月 13 日宣布,將淘汰 captions.insertcaptions.update API 端點的 sync 參數。你仍可在 YouTube 創作者工作室中使用字幕自動同步功能。詳情請參閱 API 修訂版本記錄: 瞭解詳情

caption 資源代表 YouTube 字幕軌。字幕軌只能與一部 YouTube 影片建立關聯。

方法

API 支援下列 captions 資源方法:

list
擷取與特定影片相關聯的字幕軌清單。請注意,API 回應不含實際的字幕,而 captions.download 方法則可用來擷取字幕音軌。立即試用
插入
上傳字幕軌。
更新
更新字幕軌。更新字幕軌時,您可以變更字幕軌的草稿狀態和/或上傳新的字幕檔案。
刪除
刪除指定的字幕軌。立即試用
download
下載字幕軌。除非要求指定 tfmt 參數的值 (除非要求指定了 tlang 參數值),否則字幕軌會以原始格式傳回。

資源表示法

以下 JSON 結構顯示 captions 資源的格式:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

屬性

下表定義了這個資源中顯示的屬性:

屬性
kind string
識別 API 資源的類型。值為 youtube#caption
etag etag
這項資源的 Etag。
id string
YouTube 用來識別字幕軌的 ID。
snippet object
snippet 物件包含說明文字的基本詳細資料。
snippet.videoId string
YouTube 用來識別字幕軌相關影片的專屬 ID。
snippet.lastUpdated datetime
字幕軌上次更新的日期和時間。這個值採用 ISO 8601 格式指定。
snippet.trackKind string
字幕軌的類型。

這個屬性的有效值如下:
  • ASR:使用自動語音辨識功能產生的字幕軌。
  • forced:在播放器中未選取其他音軌時,播放的字幕軌。舉例來說,如果影片中的外星人用外星語言說話,系統可能會強制啟用字幕軌,只顯示外星語人士的字幕。
  • standard:一般字幕軌。這是預設值。
snippet.language string
字幕音軌的語言。屬性值是 BCP-47 語言標記。
snippet.name string
字幕軌的名稱。系統在播放過程中會向使用者顯示這個名稱選項。支援的名稱長度上限為 150 個半形字元。
snippet.audioTrackType string
與字幕軌相關聯的音軌類型。

這個屬性的有效值如下:
  • commentary:字幕軌對應至包含評論的替代音軌,例如目錄評論。
  • descriptive:字幕軌對應至包含其他描述性音訊的替代音軌。
  • primary:字幕軌對應影片的主要音軌,也就是一般的影片音軌。
  • unknown:這是預設值。
snippet.isCC boolean
指出字幕軌是否包含失聰和聽障使用者提供的隱藏式輔助字幕。預設值為 false
snippet.isLarge boolean
指出字幕軌是否使用大型文字輔助視障使用者。預設值為 false
snippet.isEasyReader boolean
指出字幕軌是否採用「簡易閱讀」的格式意思是語言學習者的 3 年級預設值為 false
snippet.isDraft boolean
指出字幕軌是否為草稿。如果值為 true,則該曲目不會公開顯示。預設值為 false
snippet.isAutoSynced boolean
指出 YouTube 是否讓字幕軌與影片音軌同步。如果在字幕軌上傳時明確要求同步,這個值會是 true。舉例來說,呼叫 captions.insertcaptions.update 方法時,您可以將 sync 參數設為 true,指示 YouTube 將上傳的音軌同步到影片。如果值為 false,YouTube 會使用已上傳字幕軌中的時間碼來判斷顯示字幕的時間。
snippet.status string
字幕軌狀態。

這個屬性的有效值如下:
  • failed
  • serving
  • syncing
snippet.failureReason string
YouTube 無法處理字幕軌的原因。只有在 state 屬性的值為 failed 時,才會出現這個屬性。

這個屬性的有效值如下:
  • processingFailed:YouTube 無法處理已上傳的字幕軌。
  • unknownFormat:系統無法辨識字幕軌的格式。
  • unsupportedFormat:不支援字幕軌格式。