本頁面由 Cloud Translation API 翻譯而成。

Captions: insert

上傳字幕軌。

這個方法支援媒體上傳功能。上傳的檔案必須符合下列條件：

配額影響：呼叫這個方法的配額費用為 400 個單位。

常見用途

POST https://www.googleapis.com/upload/youtube/v3/captions

這項要求需要至少下列其中一個範圍的授權 (進一步瞭解驗證和授權)。

範圍
`https://www.googleapis.com/auth/youtube.force-ssl`
`https://www.googleapis.com/auth/youtubepartner`

下表列出此查詢支援的參數。這裡列出的參數全都是查詢參數。

參數
必要參數
`part`	`string` `part` 參數會指定 API 回應會包含的 `caption` 資源部分。將參數值設為 `snippet`。以下清單包含您可以加入參數值的 `part` 名稱： `id` `snippet`
選用參數
`onBehalfOfContentOwner`	`string` 這個參數只能在正確的授權要求中使用。注意：這個參數僅適用於 YouTube 內容合作夥伴。 `onBehalfOfContentOwner` 參數代表透過要求的授權憑證，代表 YouTube CMS 使用者，代表在參數值中指定的內容擁有者擔任代理人。這個參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要通過一次驗證，即可存取所有影片和頻道資料，不必分別提供各個頻道的驗證憑證。使用者用來驗證的實際 CMS 帳戶，必須連結至指定的 YouTube 內容擁有者。
`sync`	`boolean` 這個參數已淘汰。 `sync` 參數可指定 YouTube 是否應自動將字幕檔案與影片音軌同步處理。如果您將這個值設為 `true`，YouTube 就會忽略已上傳字幕檔案中的任何時間碼，並產生新的字幕時間碼。如果您要上傳的字幕記錄沒有時間碼，或您認為檔案中的時間碼不正確，且希望 YouTube 著手修正，請將 `sync` 參數設為 `true`。

在要求主體中提供字幕資源。針對該資源：

您必須指定下列屬性的值：
- snippet.videoId
- snippet.language
- snippet.name
您可以設定下列屬性的值：
- snippet.videoId
- snippet.language
- snippet.name
- snippet.isDraft

如果成功的話，這個方法會在回應內文中傳回字幕資源。

下表列出 API 回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息的說明文件。

錯誤類型	錯誤詳細資料	說明
`badRequest (400)`	`contentRequired`	要求中未包含字幕軌內容。
`conflict (409)`	`captionExists`	指定的影片已有字幕軌，內含指定的 `snippet.language` 和 `snippet.name`。一部影片可以有多個使用相同語言的音軌，但每個音軌的名稱不同。解決錯誤的方法有很多種。您可以先刪除現有音軌，再插入新的音軌或變更新音軌的名稱，然後再插入新音軌。
`forbidden (403)`	`forbidden`	要求的相關權限不足，無法上傳字幕軌。要求可能未獲適當授權。
`invalidValue (400)`	`invalidMetadata`	這項要求含有無效的中繼資料值，因此無法建立曲目。確認要求指定了 `snippet.language`、`snippet.name` 和 `snippet.videoId` 屬性的有效值。您也可以加入 `snippet.isDraft` 屬性，但並非必要。
`notFound (404)`	`videoNotFound`	找不到透過 `videoId` 參數辨識的影片。
`invalidValue (400)`	`nameTooLong`	要求中指定的 `snippet.name` 過長。支援的長度上限為 150 個半形字元。

使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。