# FlashData YouTube Captions API

Увімкніть підписки YouTube як часовий текст і повну трафарет. Вибрані за замовчуванням підписки навантажувача.

Канонічне посилання: https://flashdata.dev/uk/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/uk/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md)

Обов'язковий дозвіл на джерело: youtube_captions

Замініть YOUR_API_KEY з ключем API, який має дозвіл на джерело та доступні кредити. Виконайте запити на сервер або агент.

[Налаштування автентичності](https://flashdata.dev/uk/docs/guides/headers-and-authentication/reference.md)

[Зберігати часові підписи](https://flashdata.dev/uk/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 і партії тільки. Public 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, потім en). З автоматично=true кожен код намагається його -orig відстежувати спочатку, потім запитаний код. Витратити -orig коди і авто=false залишатися точним. Запит про Арраї 1–10 відмінні мови. Оміть віддати перевагу ен-оріг і опиніть назад, повертаємо один трек. З автоматично=true кожен код намагається його -orig відстежувати спочатку, потім запитаний код; явно -orig коди і auto=false залишатися точним. Араси 1–10 Визначені коди намагаються кожен запитаний мова і повернення треків і промовних помилок в порядку запиту. languageCode визначає обраний трек; requestedLanguageCode входить, коли він відрізняється від запитуваного коду. |
| <a id="parameter-params-auto"></a> params.auto | boolean | Ні | false | true вибирає YouTube-генерувані підписи; false вибирає завантажувачі-відхилені підписи. Це вибирає походження підписки, не мовне виявлення або новий транскрипція.  |

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

## Читати результат

Збережіть успішну відповідь JSON як response.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"
}
```

## Кілька мов

Відправте масив мови для отримання треків і помилок мови. Цей приклад показує англійський доступний і іспанський 1.00.

```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, наприклад, за умови, коли вибрано код. |
| 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 коли він не може бути завантажений або parsed. |
| results[0].errors[].message | string | Опис мовної недостатності. |

- API вже доступна на YouTube. Не генеруйте нові транскрипції або опадають між автоматичними та завантажувацькими запорами.
- Мова рядка зберігає відповідь однотрекінгу. масив, навіть ["en"], повертає треки та помилки замість верхнього рівня languageCode, сегменти та fullText. У кожному треку є ті поля. автоматично діє до кожної мови.
- Для масиву мов перевіряйте поле errors, щоб дізнатися, які доріжки не вдалося отримати. Якщо не отримано жодної доріжки, запит завершується помилкою, а зарезервовані кредити повертаються. Помилка видобування даних відео або вичерпання часу запиту також призводить до збою.
- Доступно для в режимі реального часу, асинхрону, партії та сипучих. Bulk експортується на JSONL з одним записом на відео, включаючи його треки та помилки. Accept і X-Respond-With застосовуються як звичайні.

## Формати відповідей

Відповіді використовуйте JSON за замовчуванням. Виберіть інший формат з цими заголовками.

- Accept: application/json (За замовчуванням) або text/plain. Плайн-фактура представляє ті ж поля, які можна прочитати, відступивши макет.
- X-Respond-With: markdown. Залиште заявку на оригінальні поля. Markdown працює з форматом відповіді.

Markdown доступна для запитів в режимі реального часу і завершених результатів.

На полях нижче описано відповідь JSON.

[Приклади форматів запиту та відповіді](https://flashdata.dev/uk/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/uk/docs/reference/realtime-and-async/reference.md#async)

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

- [Перевірити статус роботи](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#status)

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

- [Результати пошуку](https://flashdata.dev/uk/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON запитів](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#batch)
- [API обробки Bulk](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md)
- [Створіть робочий потік Bulk для цього джерела](https://flashdata.dev/uk/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>

## Повідомлення про видалення

- [Отримувати і перевірити завершення вебхуки](https://flashdata.dev/uk/docs/guides/async-batch/reference.md#webhooks)

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

## Виправлення несправностей

- [Помилки й коди стану](https://flashdata.dev/uk/docs/errors/reference.md#status-codes)
- [Коли птиця](https://flashdata.dev/uk/docs/errors/reference.md#retries)

## Схожі API

- [YouTube Transcript API](https://flashdata.dev/uk/docs/sources/youtube_transcript/reference.md)
- [YouTube Відео Метадані API](https://flashdata.dev/uk/docs/sources/youtube_metadata/reference.md)
