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 – 系統不支援字幕音軌的格式。