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

Captions: insert

上傳字幕軌。

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

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

常見用途

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

這項要求需要至少具備下列其中一個範圍的授權。如要進一步瞭解驗證和授權，請參閱「實作 OAuth 2.0 授權」。

範圍
`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`。

請在要求主體中提供 caption 資源。針對該資源：

您必須為下列屬性指定值：

您可以為這些屬性設定值：

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

下表列出 API 在回應對此方法的呼叫時可能傳回的錯誤訊息。詳情請參閱「YouTube Data 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 要求和回應。