Captions

注: YouTube は 2024 年 3 月 13 日に、captions.insert および captions.update API エンドポイントの sync パラメータを廃止することを発表しました。字幕の自動同期は、引き続き YouTube Studio でご利用いただけます。詳しくは、API の変更履歴をご覧ください。

caption リソースは、YouTube の字幕トラックを表します。字幕トラックは 1 つの YouTube 動画とのみ関連付けられます。

Methods

API は、captions リソースに対して次のメソッドをサポートしています。

list

指定した動画に関連付けられている字幕トラックのリストを取得します。API レスポンスには実際の字幕が含まれません。また、captions.download メソッドには字幕トラックを取得する機能があることに注意してください。 こちらから今すぐお試しください。

insert

字幕トラックをアップロードします。

update

字幕トラックを更新する。字幕トラックを更新するときに、トラックのドラフト ステータスの変更、トラックの新しい字幕ファイルのアップロード、またはその両方を行うことができます。

delete

指定した字幕トラックを削除します。 今すぐ試す

ダウンロード

字幕トラックをダウンロードします。リクエストで 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
  }
}

Properties

次の表は、このリソースで使用されているプロパティの定義を示したものです。

Properties
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.insert メソッドや captions.update メソッドを呼び出すとき、sync パラメータを true に設定して、アップロードされたトラックを動画に同期するよう YouTube に指示できます。値が false の場合、YouTube はアップロードされた字幕トラックのタイムコードに基づいて、字幕を表示するタイミングを決定します。
snippet.status	string 字幕トラックのステータス。 このプロパティの有効な値は次のとおりです。 failed serving syncing
snippet.failureReason	string YouTube が字幕トラックを処理できなかった理由。このプロパティは、state プロパティの値が failed の場合にのみ指定します。 このプロパティで有効な値は次のとおりです。 processingFailed – YouTube がアップロードされた字幕トラックの処理に失敗しました。 unknownFormat – 字幕トラックの形式が認識されませんでした。 unsupportedFormat – 字幕トラックの形式がサポートされていません。