# FlashData YouTube Captions API

YouTubeのキャプションをテキストと完全なトランスクリプトとして取得します。 デフォルトでは、アップローダーが証明されたキャプションが選択されます。

キャニシニカル参照: https://flashdata.dev/ja/docs/sources/youtube_captions
レビュー: 2026-10-23

エンドポイント: POST https://data.flashdata.dev/v1/queries/realtime
認証: X-API-Key: YOUR_API_KEY
モード: [Realtime](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md)

必要なソース権限: youtube_captions

YOUR_API_KEYをAPIキーに置き換え、このソースの許可と利用可能なクレジットを持っています。 サーバやエージェントホストのリクエストを実行します。

[認証の設定](https://flashdata.dev/ja/docs/guides/headers-and-authentication/reference.md)

[タイムスタンプされたキャプションを取得する](https://flashdata.dev/ja/docs/guides/timestamped-captions-recipe/reference.md)

<a id="quickstart"></a>

## リクエストを送信

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_captions",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": False,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_captions",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": false
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## パラメーター

<a id="parameters-group-0"></a>

### リクエストボディ

| パラメータ | 種類 | 必須 | 既定値 | 説明: |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | はい はい | — | youtube_captionsに設定します。  |
| <a id="parameter-video_id"></a> video_id | string | はい はい | 設定なし | 11-character YouTubeビデオID、FUfGcZ092b0などの。 手紙、数字、アンダースコア、ハイフンを受け入れる。 最少の長さ: 11。 最高長さ: 11。 パターン:^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | ノーザン | {} | この要求のためのSettings。  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | ノーザン | 設定なし | Asyncとバッチだけ。 パブリック HTTPS エントリーフォーム URL 港に 443まで、 2,048 文字。 ユーザーの資格情報や URL フラグメントはありません。 Omit は、通知なしの null または空の文字列を使用します。 バッチでは、各クエリで、外部のパラメータで設定します。  |

<a id="parameters-group-1"></a>

### キャプションの選択

| パラメータ | 種類 | 必須 | 既定値 | 説明: |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | ノーザン | en-orig → en | 英語(en-orig, then en)の省略。 auto=true では、各コードは -orig のトラックを最初に試み、要求されたコード。 Explicit -orig コードと auto=false は正確です。 配列は、1–10の異なる言語を要求します。 入退役希望を優先し、入退去を認める。 auto=true では、各コードは -orig のトラックを最初に試み、要求されたコード; explicit -orig のコードおよび auto=false の滞在の厳密な。 1–10のコードの配列は要求された言語を試し、要求の順序でトラックおよび言語の間違いを戻します。languageCodeは選択されたトラックを識別します;要求されたコードと異なっているときrequestedLanguageCodeは含まれています。 |
| <a id="parameter-params-auto"></a> params.auto | boolean | ノーザン | false | true は YouTube 生成されたキャプションを選択します。false は、アップローダーで提供されるキャプションを選択します。 これは、言語の検出や新しい転写ではなく、キャプションの起源を選択します。  |

<a id="response"></a>

## 結果を読む

response.jsonとして成功するJSON応答を保存します。 これをread-response.pyとして保存し、python read-response.pyを実行します。 Pythonの標準ライブラリのみを使用し、新しいリクエストは使用しません。

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## レスポンスの例

記録された例; フィールドとカウントは、ソースと要求された入力に依存します。
```json
{
  "source": "youtube_captions",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 1.36,
          "end": 3.04,
          "text": "[♪♪♪]"
        },
        {
          "start": 18.64,
          "end": 21.880000000000003,
          "text": "♪ We're no strangers to love ♪"
        },
        {
          "start": 22.64,
          "end": 26.96,
          "text": "♪ You know the rules\nand so do I ♪"
        },
        {
          "start": 27.04,
          "end": 31.04,
          "text": "♪ A full commitment's\nwhat I'm thinking of ♪"
        },
        {
          "start": 31.12,
          "end": 35.08,
          "text": "♪ You wouldn't get this\nfrom any other guy ♪"
        },
        {
          "start": 35.16,
          "end": 39.52,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 40.52,
          "end": 42.92,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 43,
          "end": 45.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 45.2,
          "end": 47.080000000000005,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 47.32,
          "end": 51.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 51.48,
          "end": 53.48,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 53.6,
          "end": 55.52,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 55.72,
          "end": 59.36,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 60.8,
          "end": 64.8,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 64.88,
          "end": 69.03999999999999,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 69.12,
          "end": 72.96000000000001,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 73.36,
          "end": 77.2,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 77.4,
          "end": 82.04,
          "text": "♪ And if you ask me\nhow I'm feeling ♪"
        },
        {
          "start": 82.4,
          "end": 85.24000000000001,
          "text": "♪ Don't tell me\nyou're too blind to see ♪"
        },
        {
          "start": 85.32,
          "end": 87.27999999999999,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 87.36,
          "end": 89.32,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 89.44,
          "end": 93.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 93.8,
          "end": 95.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 95.76,
          "end": 98,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 98.08,
          "end": 102.04,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 102.2,
          "end": 104.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 104.28,
          "end": 106.36,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 106.48,
          "end": 110.08,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 110.76,
          "end": 112.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 112.8,
          "end": 114.68,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 114.96,
          "end": 118.76,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 119.84,
          "end": 122.96,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 123.72,
          "end": 127.36,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 128.48,
          "end": 130.11999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 130.24,
          "end": 131.56,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 132.48,
          "end": 134.23999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 134.36,
          "end": 135.92000000000002,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 136.76,
          "end": 141.07999999999998,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 141.2,
          "end": 145.2,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 145.28,
          "end": 149.12,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 149.52,
          "end": 153.20000000000002,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 153.36,
          "end": 158.04000000000002,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 158.64,
          "end": 161.32,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 161.4,
          "end": 163.36,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 163.44,
          "end": 165.64,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 165.72,
          "end": 169.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 169.8,
          "end": 171.64,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 171.8,
          "end": 173.96,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 174.04,
          "end": 177.6,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 178.2,
          "end": 180.24,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 180.32,
          "end": 182.44,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 182.52,
          "end": 186.64,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 186.72,
          "end": 188.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 188.84,
          "end": 190.72,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 190.84,
          "end": 195.2,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 195.28,
          "end": 197.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 197.2,
          "end": 199.24,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 199.4,
          "end": 203.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 203.36,
          "end": 205.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 205.68,
          "end": 207.84,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 207.92,
          "end": 211.32,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        }
      ],
      "fullText": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules\nand so do I ♪ ♪ A full commitment's\nwhat I'm thinking of ♪ ♪ You wouldn't get this\nfrom any other guy ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ And if you ask me\nhow I'm feeling ♪ ♪ Don't tell me\nyou're too blind to see ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ (Ooh, give you up) ♪ ♪ (Ooh, give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪"
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:46.290Z"
}
```

## 複数の言語

追跡と言語のエラーを受け取るために言語配列を送信します。 この例では、英語が利用でき、スペイン語が利用できなくなったりします。

```json
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": false,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Uploader-provided subtitles not available for language: es"
    }
  ]
}
```

## 応答分野

| フィールド | 種類 | 説明: |
| --- | --- | --- |
| source | string | 要求されたAPIの源。 |
| status | string | リアルタイムリクエストが成功したときに行われる。 |
| created_at | string | ISO 8601 形式の応答作成時間。 |
| usage.credits | number | リクエストに応じて請求されるクレジットは、プランに基づいて行われます。 |
| results[0].videoId | string | 要求されたビデオID。 |
| results[0].languageCode | string | 実際の選択されたキャプション・トラック コード、例えば en-orig のような。 |
| results[0].languageName | string · nullable | 利用できる場合の言語表示名。 |
| results[0].requestedLanguageCode | string · optional | リクエストされたコードは、languageCodeと異なる場合、例えば en-orig が選択されたとき。 |
| results[0].isAutoGenerated | boolean | 選択したキャプションが自動的に生成されるかどうか。 |
| results[0].segments | array | 慢性的な順序のキャプションの区分。 |
| results[0].segments[].start | number | 秒単位の開始時間。 |
| results[0].segments[].end | number | 秒単位で終了時刻をセグメント化します。 |
| results[0].segments[].text | string | キャプションテキスト。 |
| results[0].fullText | string | すべてのセグメントのテキストは、トランスクリプトに結合しました。 |
| results[0].tracks | array · optional | 言語配列のみ。 リクエスト順に利用可能なトラック。それぞれに上記のシングルトラックフィールドがあります。 |
| results[0].errors | array · optional | 言語配列のみ。 リクエストの注文で失敗した言語。 すべてのトラックが成功すると空に。 |
| results[0].errors[].languageCode | string | 失敗した要求された言語。 |
| results[0].errors[].code | string | language_unavailable 選択したトラックが存在しない場合。 retrieval_failed ダウンロードや解析ができない場合。 |
| results[0].errors[].message | string | 言語障害の説明。 |

- APIは、YouTubeで既に利用可能なキャプションを読み込みます。 自動およびアップローダーによって証明されるキャプション間で新しいトランスクリプトを生成したり、フォールバックしたりしません。
- 文字列の言語は、単一トラックの応答を保持します。 languageCode、セグメント、fullTextの代わりに、配列、 ["en"]、リターントラックとエラー。 各トラックにはこれらのフィールドが含まれます。各言語に自動適用されます。
- 言語の配列を指定した場合は、errors で取得に失敗したトラックを確認してください。トラックを 1 件も取得できない場合、リクエストは失敗し、確保済みのクレジットは返還されます。動画の抽出エラーやリクエストの期限切れでも失敗します。
- リアルタイム、非同期、バッチ、一括で利用できます。 Bulkエクスポートは、トラックやエラーを含むビデオごとの1レコードでJSONLを維持します。 Accept と X-Respond-With は、通常どおり適用されます。

## レスポンス形式

応答はデフォルトでJSONを使用します。 これらのオプションヘッダーで別の形式を選択します。

- Accept: application/json (デフォルト) または text/plain. プレーンテキストは、読みやすいレイアウトで同じフィールドを提示します。
- X-Respond-With: markdown. 元のフィールドにアンセットを残します。 Markdownは、応答形式のいずれかで動作します。

Markdownはリアルタイムの問い合わせと完了した結果に利用できます。

下のフィールドは、デフォルトのJSON応答を記述します。

[リクエストとレスポンスの形式例](https://flashdata.dev/ja/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## API の基本

上記のビルダーと例は、このソースのパラメーターを使用します。 Python と cURL の例を以下に使用して、共有の投稿、ステータス、結果の手順を実行します。 Batch ボディは、クエリを含む JSON オブジェクトです。各項目は独自のジョブ ID を返します。

- [Asyncリクエストとレシート](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [ジョブステータスの確認](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [完了した結果を取得する](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON リクエスト](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md#batch)
- [Bulk 処理 API](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md)
- [Bulkのワークフローをこのソースにビルドする](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md?source=youtube_captions#playground)
- [顧客OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## 完了通知

- [完了のWebhooksを受信し、確認する](https://flashdata.dev/ja/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## トラブルシューティング

- [エラーとステータスコード](https://flashdata.dev/ja/docs/errors/reference.md#status-codes)
- [再試行するとき](https://flashdata.dev/ja/docs/errors/reference.md#retries)

## 関連API

- [YouTube Transcript API](https://flashdata.dev/ja/docs/sources/youtube_transcript/reference.md)
- [YouTubeビデオメタデータAPI](https://flashdata.dev/ja/docs/sources/youtube_metadata/reference.md)
