# FlashData YouTube Download API

Завантажити YouTube відео або аудіо на хмарне сховище. Виберіть роздільну здатність, формат і тривалість кліпу, потім відстежуйте синхронну роботу через завершення.

Канонічне посилання: https://flashdata.dev/uk/docs/sources/youtube_download
Відгук: 2026-10-23

Навігація: POST https://data.flashdata.dev/v1/queries
Автентифікація: X-API-Key: YOUR_API_KEY
Режими: [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_download

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

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

[Завантажити одне відео та перевірити доставку](https://flashdata.dev/uk/docs/guides/download-video-recipe/reference.md)

[API завантаження відео YouTube — приклади Python](https://github.com/flashdatadev/youtube-video-download-api)

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

## Надіслати запит

### Python

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

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    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" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "access_key": "YOUR_ACCESS_KEY",
      "secret_key": "YOUR_SECRET_KEY",
      "region": "us-east-1"
    }
  }
}
FLASHDATA_JSON
```

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

## Параметри

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

### Тіло запиту

| Параметр | Типи | Обов’язково | За замовчуванням | Опис |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | ТОЙ | — | Набір до youtube_download.  |
| <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-download_type"></a> params.download_type | string | Ні | "audio_video" | audio_video об'єднує відео і аудіо; відео вибирає відео тільки; аудіо вибирає аудіо тільки. Дозволено: "audio_video", "video", "audio". Мінімальна довжина: 1. Максимальна довжина: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Ні | "<=720" | Вибір дозволу відео. Omit для аудіо-тільки завантаження. Дозволено: "best", "worst", "<=144", "==144", ">=144", "<=360", "==360", ">=360", "<=480", "==480", ">=480", "<=720", "==720", ">=720", "<=1080", "==1080", ">=1080", "<=1440", "==1440", ">=1440", "<=2160", "==2160", ">=2160", "<=4320", "==4320", ">=4320". Мінімальна довжина: 1. Максимальна довжина: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Ні | Не встановити | Рама-рейтинг: >=, <= або == з подальшим значенням від 1 до 240. Omit для аудіо-тільки завантаження. Мінімальна довжина: 1. Максимальна довжина: 6. Візерунок: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Ні | "default" | Вибір аудіо доріжки. Додатки до audio_video та аудіо. Дозволено: "default", "original". Мінімальна довжина: 1. Максимальна довжина: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Ні | "best" | Audio-only бітрейт в kbps, або кращий. Чисельні вибірки повинні бути відправлені як рядки. Omit для завантаження відео. Дозволено: "best", "320", "256", "192", "128". Мінімальна довжина: 1. Максимальна довжина: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Ні | mp4 (video) / m4a (audio) | Відео: mp4, вебм або mkv. Аудіо: m4a, mp3 або opus. Дозволено: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Мінімальна довжина: 1. Максимальна довжина: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Ні | Не встановити | Розширений вибір формату, від 1 до 1,024 символів після підрізання білого простору. Символи керування відхиляються. На Overrides video_quality, fps і audio_language, значення яких потім ігноруються; формат виведення та затискання все ще застосовуються. Мінімальна довжина: 1. Максимальна довжина: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Ні | false | Завантажте файл метаданих JSON разом із файлами медіа у вашому пристрої.  |

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

### Кріплення

| Параметр | Типи | Обов’язково | За замовчуванням | Опис |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Ні | Не встановити | Запуск кліпу в H:MM:SS або HH:MM:SS формат, від 00:00:00 до 12:00:00. За замовчуванням до 00:00:00 при наявності тільки end_at. Мінімальна довжина: 1. Максимальна довжина: 8. Візерунок: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Ні | Не встановити | Кінець кліпу в H:MM:SS або HH:MM:SS формат, до 12:00:00. Повинен бути пізніше, ніж start_at. Мінімальна довжина: 1. Максимальна довжина: 8. Візерунок: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Місце зберігання

| Параметр | Типи | Обов’язково | За замовчуванням | Опис |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | ТОЙ | — | Призначення для заповнених медіа файлів. Приймаються тільки перераховані поля зберігання.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | ТОЙ | — | s3, s3_compatible, oss, gcs, azure, cos, bos або tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | ТОЙ | — | Неопимний відро або контейнерне ім'я, до 1,024 символів. Зняттям білого простору знімається. Для s3 використовуйте дійсне ім'я відра AWS без URL або шлях до папки; папки, що належать до object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Ні | "YYYYMMDD" | Префікс об'єктів, 1 до 512 символів. Кожен сегмент суспензії приймає букви ASCII, цифри, точки, носики та гіфени; порожні сегменти, . та .. відхилені. Ні провідний slash. Виводиться перекриття білого простору і одного причепа вії. YYYYMMDD використовує дату завантаження UTC, включаючи archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Ні | — | ключ доступу для S3, S3-сумісні, OSS, COS, BOS або TOS; паровані secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Ні | — | Таємний ключ для S3, S3-сумісні, OSS, COS, BOS або TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Ні | — | Public HTTPS кінцева точка для S3-сумісного зберігання або OSS. COS, BOS і TOS, що подають його з регіону.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Ні | — | Для COS, BOS і TOS, також постачання для S3 і S3-сумісних завантажень. Відро назви COS включають APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Ні | — | GCS сервісний рахунок: project_id, client_email і PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Ні | — | Назва облікового запису Azure. Використовуйте назву контейнера в storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Ні | — | Написання контейнера Azure SAS з витривалістю та підписом.  |

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

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

Після завершення роботи, збережіть JSON з посиланням на його результати як response.json. Збережіть це як read-response.py і запустіть python read-response.py. Він читає дані файлів без завантаження медіа або отримання іншого запиту.

### 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 = {name: result.get(name) for name in (
    "file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Зразок подання

Зареєстрований приклад; поля та підрахунки залежать від джерела та запитуваного введення.
```json
{
  "id": "job_d265c693-950e-40bf-a13e-a432044d99ba",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  },
  "created_at": "2026-09-16T07:51:13.139Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba/results",
      "method": "GET"
    }
  ]
}
```

## Поля зворотнього зв'язку

| Поле | Типи | Опис |
| --- | --- | --- |
| id | string | Завантажити роботу ID. |
| source | string | youtube_download. |
| status | string | прийняти роботу. |
| created_at | string | Час створення роботи в форматі ISO 8601. |
| usage.credits | number | 0 на подачі. Завантаження здійснюється за рахунок доставленого обсягу даних. |
| links | array | Дотримуйтесь свого посилання на статус роботи та посилання на результати для завершення виходу. |
| links[].rel | string | само або результати. |
| links[].href | string | URL до запиту з тим же ключем API. |
| links[].method | string | GET. |

- Завантаження в якості фонових робочих місць. Відповідь на подачу містить роботу ID; не містить медіа-файлу. Виконайте статус роботи до завершення, після чого отримайте результат, який описує файли, доставлені до вашого сховища. Завантажуйте завантаження до /v1/queries або /v1/queries/batch; /v1/queries/realtime не приймає запити завантаження.

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

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

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

Markdown формати завантаження проявляються; медіа файли зберігають свій оригінальний формат. Заявки та підтримка стану роботи Accept тільки.

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

[Приклади форматів запиту та відповіді](https://flashdata.dev/uk/docs/guides/response-formats/reference.md#completed-results)

<a id="storage"></a>

## Місце зберігання

Один-job і Batch скачати для завантаження params.storage; Bulk завантажує використання options.storage. storage_url є відро або назва контейнера. Поставка облікових даних з доступом до запису та збереження їх на сервері.

### s3

Постачання access_key і secret_key з доступом до запису. Встановити область до області AWS відра.

```json
{
  "storage_type": "s3",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### s3_compatible

Поставка access_key, secret_key і громадська HTTPS endpoint_url. Настроювання регіону, що вимагається вашим постачальником; Cloudflare R2 використовує авто.

```json
{
  "storage_type": "s3_compatible",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
  "region": "auto"
}
```

### azure

Поставка account_name і sas_token, контейнер SAS з письмовим дозволом (сп включає в себе w), ресурсний sr=c, expiry se, версія sv і підпису sig. storage_url - назва контейнера. Не надсилайте endpoint_url, access_key або secret_key.

```json
{
  "storage_type": "azure",
  "storage_url": "your-media-container",
  "account_name": "yourstorageaccount",
  "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE"
}
```

### bos

Постачання access_key, secret_key та області: bj, su або hkg. Кінцева точка виводиться з регіону при в'язанні. Використовуйте назву відра без точок.

```json
{
  "storage_type": "bos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "bj"
}
```

### cos

Постачання access_key, secret_key і ap-* область, такі як ap-hongkong. storage_url повинна включати в себе застосунок APPID. Не надсилайте endpoint_url; він виходить з регіону.

```json
{
  "storage_type": "cos",
  "storage_url": "your-media-bucket-1234567890",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "ap-hongkong"
}
```

### gcs

Поставка service_account з project_id, client_email (адреса .gserviceaccount.com), і PEM private_key з вашого облікового запису служби. Враховуйте доступ до відро. Не надсилайте access_key, secret_key, регіон або endpoint_url.

```json
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "uploader@your-project-id.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
  }
}
```

### oss

Поставка access_key, secret_key та громадська HTTPS endpoint_url.

```json
{
  "storage_type": "oss",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com"
}
```

### tos

Постачання access_key, secret_key та області з cn-, ap-, eu- або us- префіксом. Кінцева точка виводиться з регіону при в'язанні. Використовуйте назву відра без точок.

```json
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}
```

<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_download#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)

<a id="delivery"></a>

## Доставка файлів

Завантажити не підтримує в режимі реального часу.

Media завантажується на налаштоване сховище; результат JSON описує ці файли. Приватні ЗМІ використовують автентифікацію вашого зберігання. JSON завершує роботу 24 після завершення роботи; ЗМІ слідують політиці зберігання даних.

## Схожі API

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