# FlashData YouTube Download API

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

Каноническая ссылка: https://flashdata.dev/ru/docs/sources/youtube_download
Проверено: 2026-10-23

Конечная точка: POST https://data.flashdata.dev/v1/queries
Аутентификация: X-API-Key: YOUR_API_KEY
Режимы: [Async](https://flashdata.dev/ru/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/ru/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md)

Требуемое разрешение источника: youtube_download

Замените YOUR_API_KEY ключом API, который имеет это разрешение источника и доступные кредиты. Запустите запросы на вашем сервере или хосте-агенте.

[Настройка аутентификации](https://flashdata.dev/ru/docs/guides/headers-and-authentication/reference.md)

[Скачайте одно видео и проверьте доставку](https://flashdata.dev/ru/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-символ 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-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" | Аудио-только битрейт в 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, webm или 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 после обрезки белого пространства. Контрольные символы отвергаются. Переопределяет 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" | Префикс Object-key, 1 для символов 512. Каждый сегмент, разделенный на слэш, принимает буквы, цифры, точки, подчеркивания и дефисы ASCII; пустые сегменты, . и .. отклоняются. Никакого ведущего удара. Окружающее белое пространство и один следящий слэш удаляются. 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 | Нет | — | Публичная конечная точка HTTPS для S3-совместимого хранилища или OSS. COS, BOS и TOS получают его из региона.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Нет | — | Требуется для COS, BOS и TOS, а также для S3 и S3-совместимых загрузок. Названия COS bucket включают 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/ru/docs/guides/response-formats/reference.md#completed-results)

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

## Место хранения

Одноместные и 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 с разрешением на запись (sp включает w), ресурс sr=c, срок действия 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/ru/docs/reference/realtime-and-async/reference.md#async)

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

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

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

- [Восстановление завершенных результатов](https://flashdata.dev/ru/docs/reference/realtime-and-async/reference.md#results)
- [Запросы Batch JSON](https://flashdata.dev/ru/docs/reference/batch-and-bulk/reference.md#batch)
- [API обработки Bulk](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md)
- [Создайте рабочий процесс Bulk для этого источника](https://flashdata.dev/ru/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/ru/docs/guides/async-batch/reference.md#webhooks)

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

## устранение неполадок

- [Ошибки и коды состояния](https://flashdata.dev/ru/docs/errors/reference.md#status-codes)
- [Когда повторно](https://flashdata.dev/ru/docs/errors/reference.md#retries)

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

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

Download не поддерживается в режиме реального времени.

Медиа загружаются в настроенное хранилище; результат JSON описывает эти файлы. Частные носители используют аутентификацию вашего хранилища. JSON Результаты истекают 24 Через несколько часов после завершения; носители следуют вашей политике хранения.

## Связанные API

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