Captions

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

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

方法

這個 API 支援 captions 資源的下列方法：

list
擷取與指定影片相關聯的字幕軌清單。請注意，API 回應不含實際的字幕，而 captions.download 方法則可用來擷取字幕音軌。立即試用。
插入
上傳字幕軌。立即試用。
update
更新字幕軌。更新字幕軌時，你可以變更軌道的草稿狀態，為軌道上傳新的字幕檔案，或同時執行這兩項操作。立即試用。
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
指出字幕音軌是否採用「易讀」格式，也就是語言學習者程度的第三級。預設值為 false。
snippet.isDraft boolean
指明字幕音軌是否為草稿。如果值為 true，則該曲目不會公開顯示。預設值為 false。
snippet.isAutoSynced boolean
指出 YouTube 是否已將字幕音軌與影片中的音訊音軌同步。如果在字幕軌上傳時明確要求同步，則值會是 true。舉例來說，呼叫 captions.insert 或 captions.update 方法時，您可以將 sync 參數設為 true，指示 YouTube 將已上傳的曲目同步至影片。如果值為 false，YouTube 會使用上傳字幕音軌中的時間碼，判斷何時顯示字幕。
snippet.status string
字幕音軌的狀態。

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

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