Обзор документации
Справочник API
YouTube Download API
Загрузите видео или аудио YouTube в облачное хранилище. Выберите разрешение, формат и продолжительность клипа, а затем отследите асинхронную работу через завершение.
API скачивания видео YouTube — примеры на Python
Создать запрос
11-символ ID из видео URL, а не полный URL.
Расширенные медиа-варианты
Селектор формата перевешивает качество, частоту кадров и выбор аудиоязыка. Формат вывода и границы клипов по-прежнему применяются. Конец клипа должен следовать за началом; любой из них может быть опущен.
Место хранения
Blank использует дату загрузки UTC (YYYYMMDD).
Добавьте свои учетные данные на сервер перед запуском кода. Им нужно разрешение для загрузки файлов.
Учетные данные поставщика и требования к хранениюЗавершение webhook
Полезная нагрузка Webhook, проверка и повторные попыткиMarkdown применяется к полученным результатам. Квитанции и статус работы сохраняют свои первоначальные поля.
https://data.flashdata.dev/v1/queriesПараметры
Отправить source и video_id на высшем уровне. Варианты источника принадлежат params. Факультативные поля можно опустить.
Тело запроса
sourcestring / Обязательно- Настройка на youtube_download.
video_idstring / Обязательно- 11-символ YouTube видео ID, например FUfGcZ092b0. Принимает буквы, цифры, подчеркивания и дефисы.Точно. 11 персонажиПо умолчанию:
Не установленПринятый формат
^[A-Za-z0-9_-]{11}$ paramsobject / Обязательно- Settings для этого запроса.
callback_urlstring · nullable / Необязательно- Async и пакетные. Публичный HTTPS завершает URL на порте 443, вплоть до символов 2,048. Никаких учетных данных пользователя или фрагмента URL. Omit, используйте null или пустую строку без уведомления. В партии, установите это на каждый запрос, вне парамов.По умолчанию:
Не установлен
Видео и аудио
params.download_typestring / Необязательно- audio_video объединяет видео и аудио; видео выбирает только видео; аудио выбирает только аудио.1 то 11 персонажиЦенности:
audio_video / video / audioПо умолчанию:"audio_video" params.video_qualitystring / Необязательно- Выбор разрешения видео. Omit для скачивания только аудио.1 то 40 персонажиЦенности:
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По умолчанию:"<=720" params.fpsstring / Необязательно- Ограничение частоты кадров: >=, <= или == с последующим значением от 1 до 240. Omit для скачивания только аудио.1 то 6 персонажиПо умолчанию:
Не установленПринятый формат
^(?:>=|<=|==)(?:[1-9]\d?|1\d\d|2[0-3]\d|240)$ params.audio_languagestring / Необязательно- Выбор звуковой дорожки. Применяется для audio_video и аудио.1 то 8 персонажиЦенности:
default / originalПо умолчанию:"default" params.audio_qualitystring / Необязательно- Аудио-только битрейт в kbps, или лучше. Численные варианты должны быть отправлены в виде строк. Omit для загрузки видео.1 то 10 персонажиЦенности:
best / 320 / 256 / 192 / 128По умолчанию:"best" params.output_formatstring / Необязательно- Видео: mp4, webm или mkv. Аудио: m4a, mp3 или opus.1 то 10 персонажиЦенности:
mp4 / webm / mkv / m4a / mp3 / opusПо умолчанию:mp4 (video) / m4a (audio) params.yt_dlp_formatstring / Необязательно- Расширенный селектор форматов, от 1 до символов 1,024 после обрезки белого пространства. Контрольные символы отвергаются. Переопределяет video_quality, fps и audio_language, значения которых затем игнорируются; выходной формат и обрезка все еще применяются.1 то 1 024 персонажиПо умолчанию:
Не установлен params.upload_metadataboolean / Необязательно- Загрузите файл метаданных JSON вместе с медиафайлом в хранилище.
trueилиfalseПо умолчанию:false
клиппинг
params.start_atstring / Необязательно- Запуск в формате 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$ params.end_atstring / Необязательно- Завершается нажатием в формате H:MM:SS или HH:MM:SS, вплоть до 12:00:00. Это должно быть позже, чем start_at.1 то 8 персонажиПо умолчанию:
Не установленПринятый формат
^\d{1,2}:[0-5]\d:[0-5]\d$
Место хранения
params.storageobject / Обязательно- Направление для заполненных медиафайлов. Принимаются только перечисленные поля хранения.
params.storage.storage_typestring / Обязательно- Поставщик хранения: s3, s3_compatible, oss, gcs, azure, cos, bos или tos.
params.storage.storage_urlstring / Обязательно- Непустое название ведра или контейнера, вплоть до символов 1,024. Окружающее белое пространство удаляется. Для s3 используйте действительное имя ведра AWS без URL или пути папки; папки принадлежат object_prefix.
params.storage.object_prefixstring / Необязательно- Префикс Object-key, 1 для символов 512. Каждый сегмент, разделенный на слэш, принимает буквы, цифры, точки, подчеркивания и дефисы ASCII; пустые сегменты, . и .. отклоняются. Никакого ведущего удара. Окружающее белое пространство и один следящий слэш удаляются. YYYYMMDD использует дату загрузки UTC, включая archive/YYYYMMDD.По умолчанию:
"YYYYMMDD" params.storage.access_keystring / Необязательно- Ключ доступа для S3, S3-совместимый, OSS, COS, BOS или TOS; в паре с secret_key.
params.storage.secret_keystring / Необязательно- Секретный ключ для S3, S3-совместимых, OSS, COS, BOS или TOS.
params.storage.endpoint_urlstring / Необязательно- Публичная конечная точка HTTPS для S3-совместимого хранилища или OSS. COS, BOS и TOS получают его из региона.
params.storage.regionstring / Необязательно- Требуется для COS, BOS и TOS, а также для S3 и S3-совместимых загрузок. Названия COS bucket включают APPID.
params.storage.service_accountobject / Необязательно- Сервисный аккаунт GCS: project_id, client_email и PEM private_key.
params.storage.account_namestring / Необязательно- Имя учетной записи Azure. Используйте имя контейнера в storage_url.
params.storage.sas_tokenstring / Необязательно- Azure контейнер SAS с истекающим сроком действия и подписью.
Ответ
Разработчик запроса отправляет загрузки с Async или Batch и требует params.storage. HTTP 200 с status: pending Подтверждает принятие, а не доставку. Batch возвращает одну квитанцию о работе за видео ID.
Представление usage.credits это 0. Загрузки оплачиваются по объему доставленных носителей после успешной доставки; дополнительные файлы метаданных не добавляют к плате за загрузку.
опрос job.status до тех пор пока completed, Затем вы получите результат JSON. Читайте подробности СМИ в results[0], в том числе и загруженного объекта file_url, Размер файла и контрольная сумма.
Прочитайте результат
После завершения работы сохраните JSON из ссылки результатов в виде response.json. Сохраните это как read-response.py и запустите python read-response.py. Он считывает данные файла без загрузки мультимедиа или другого запроса.
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))Статус может включать в себя информацию о СМИ job.result. По умолчанию рабочие процессы JSON используют их, когда они доступны, и в противном случае следуют за ними. rel: results Не думайте, что входящий результат всегда присутствует.
Все поля ответов на запросы
| Поле | Описание |
|---|---|
idstring | Скачать работу ID. |
sourcestring | youtube_download. |
statusstring | ожидая, когда работа будет принята. |
created_atstring | Время создания работы в формате ISO 8601. |
usage.creditsnumber | 0 по представлению. Загрузки взимаются за счет предоставленного объема данных после завершения. |
linksarray | Следуйте по ссылке «Я» для статуса работы и по ссылке «Результаты» для завершенной работы. |
links[].relstring | себя или результаты. |
links[].hrefstring | URL для запроса с тем же ключом API. |
links[].methodstring | GET. |
Заполненные медиафайловые поля
| Поле | Описание |
|---|---|
results[0].file_urlstring | Расположение медиафайла в вашем хранилище. |
results[0].file_sizeinteger | Размер медиафайла в байтах. |
results[0].downloaded_bytesinteger | Доставленные медиа байты, используемые для выставления счетов. |
results[0].md5string | MD5 контрольная сумма медиафайла. |
results[0].resolutionstring · nullable | Разрешение видео или null для аудио-только вывода или недоступной высоты. |
results[0].durationnumber · nullable | Длительность в секундах при наличии. |
results[0].output_formatstring | Формат выходного файла. |
results[0].fpsnumber · nullable | Каркас, когда он доступен. |
results[0].video_codecstring · nullable | Видеокодек, когда он доступен. |
results[0].audio_codecstring · nullable | Аудиокодекс, когда он доступен. |
results[0].dynamic_rangestring · nullable | Динамический диапазон видео при наличии. |
results[0].metadataobject · optional | Метаданные file_url, file_size и md5, когда upload_metadata является true. Байты метаданных исключаются из платы за загрузку. |
Вышеприведенные поля описывают ответ JSON по умолчанию. Варианты формата применяются к записи доставки, а не к медиафайлу. JSON, простой текст и форматы Markdown.
Async и пакетный жизненный цикл
Подача возвращает квитанцию, а не результаты. Async создает одну работу; партия возвращает отдельную работу в queries[] на каждый принятый запрос. Отслеживайте и извлекайте каждую работу самостоятельно.
Представить data.flashdata.dev; читать статус работы и результаты api.flashdata.dev С тем же X-API-Key. Связанные базовые примеры API используют Python и cURL.
1. Сохранить работу IDs
Отправьте одну загрузку с помощью Async или поместите несколько запросов на загрузку в массив запросов Batch. Для каждой записи нужен params.storage. Сохраните все возвращенные работы ID.
2. Проверьте статус
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: Опрос с задержкой и уважениемRetry-Afterкогда присутствует.completed: Принесите результаты.failed: Проверитьjob.error.Читайте job.status, а не статус квитанции о представлении.
Проверить статус: Python и cURL
Статус работы API ссылка3. Получить результаты
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsПосле завершения аутентификации считывайте результат, а затем возьмите хранилище 302 URL без ключа API. Сохраните JSON в течение часов завершения 24.
JSON описывает носители, доставленные на ваше хранилище. Доступ к медиафайлу.
Результаты поиска: Python и cURL · Форматы ответов
Результат скачивания ссылки API
Опросы и получение существующих результатов не потребляют кредиты запросов. Тайм-аут для голосования не отменяет работу: сохраняйте свой ID вместо того, чтобы подавать дубликат оплачиваемой работы. Коды ошибок и поведение retry.
Вебхуки завершения
Подписаться на запрос
Настройка callback_url на верхнем уровне асинхронного запроса, или Внутри каждого запроса в партии, снаружи params. Отдельного запроса на регистрацию webhook не требуется.
Используйте общедоступный HTTPS URL на порту 443. FlashData POST - уведомление для каждой работы completed или failed; Событие содержит ссылки, а не сам результат.
Признать и проверить
Возвращение 2xx После того, как он принял это событие. Дублировать через delivery_id, Также посланный как X-Delivery-Id. Переадресации не выполняются.
Неудачные поставки с экспоненциальным обратным откатом, вплоть до 8 - полная версия и в большинстве 24 часов после завершения. Продолжайте опросы как запасной вариант.
Обратные звонки не подписаны. Подтвердить работу ID, исходный и терминальный статус через аутентифицированная конечная точка статуса перед обработкой уведомления. Поставка ID предназначена для дедупликации, а не для подтверждения подлинности.
Пример события web-cook и полей
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_download",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Поле | Описание |
|---|---|
delivery_idstring | Стабильный идентификатор доставки. Дублировать уведомления с использованием этого значения; он также отправляется в заголовке X-Delivery-Id. |
idstring | Работать ID. |
sourcestring | Запрошенный источник данных. |
statusstring | завершены или не выполнены. |
linksarray | Статус и результат ссылки. Уведомления не включают контент результата или ключ API. |
links[].relstring | себя или результаты. |
links[].hrefstring | Абсолютный менеджмент API URL; аутентифицируйтесь с помощью ключа API. |
links[].methodstring | GET. |
Обработка файлов Bulk
Загрузите одно видео ID в строку и создайте задание Bulk с исходным кодом: youtube_download. Общие опции применяются к каждому ID в файле.
Поместите необходимое место хранения в options.storage Медиа-настройки в options. одиночная работа и Batch использование скачать params.storage Вместо этого.
Медиа-файлы доставляются в ваше облачное хранилище. Завершенный результат Bulk включает в себя манифест и части результатов, описывающие загрузку. Сохраняйте манифест и части внутри 24 Через несколько часов после всего Bulk Работа завершена.
Bulk Обработка API · Python и cURL · Запросы Batch JSON
Создайте рабочий процесс Bulk для этого источника · Пауза, возобновление и восстановление
Место хранения
Включать params.storage в каждом запросе на загрузку. Настройка storage_url к названию вашего ведра или контейнера и предоставить учетные данные с доступом к записи. Держите учетные данные хранения на своем сервере.
{
"storage_type": "s3_compatible",
"storage_url": "your-media-bucket",
"object_prefix": "archive/YYYYMMDD",
"endpoint_url": "https://your-s3-endpoint.example.com",
"region": "your-provider-region",
"access_key": "<storage-access-key>",
"secret_key": "<storage-secret-key>"
}object_prefix Дефолты для YYYYMMDD, замененный датой загрузки UTC. Используйте фиксированный каталог или шаблон, такой как archive/YYYYMMDD.
s3- Поставка access_key и secret_key с доступом к записи. Установите регион в регионе AWS вашего ведра.
s3 пример
{ "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 использует авто.
s3_compatible пример
{ "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.
azure пример
{ "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. Конечная точка получена из области, когда опущена. Используйте имя ведра без точек.
bos пример
{ "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, он получен из региона.
cos пример
{ "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.
gcs пример
{ "storage_type": "gcs", "storage_url": "your-media-bucket", "service_account": { "project_id": "your-project-id", "client_email": "[email protected]", "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n" } } oss- Поставка access_key, secret_key и публичного HTTPS endpoint_url.
oss пример
{ "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-. Конечная точка получена из области, когда опущена. Используйте имя ведра без точек.
tos пример
{ "storage_type": "tos", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "cn-beijing" }
Результат file_url Идентифицирует объект в вашем хранилище. Частные объекты требуют авторизации вашего провайдера хранения или подписанного URL; ключ FlashData API не предоставляет доступ к вашему ветру.
Для полного представления, опроса и загрузки рабочего процесса см. Скачать аудио YouTube в Amazon S3.
Доставка файлов
Работа rel: results По умолчанию конечная точка перенаправляет на Результат: JSONQ, И это не MP4 скачать. FlashData загружает фактические носители в ведро или контейнер, который вы поставили. Удержание средств массовой информации следует политике вашего ведра; результат работы JSON истекает 24 Через несколько часов после завершения.
results[0].file_url Идентифицирует объект, но не является автоматически общедоступным или подписанным URL. Получите доступ к частному носителю с вашим хранилищем SDK или создайте короткоживущий подписанный URL на своем собственном сервере. Не отправляйте ключ FlashData API поставщику услуг хранения данных.
Включать upload_metadata Чтобы загрузить a {video_id}_meta.json Компаньон в той же приставке. Местонахождение и контрольная сумма указаны под results[0].metadata.
Режим загрузки браузера консоли является отдельным. Публичные загрузки API используют собственное хранилище; не включают только консоль. browser_delivery настройки.
Восстановление ошибок
Для сбоев загрузки или хранения 403, проверьте провайдера, ведро, область, конечную точку и разрешения на запись объекта. Недоступный или частный file_url Сам по себе это не означает, что загрузка не удалась: проверьте объект через своего поставщика.
Удаленный или недоступный видео не может быть восстановлен путем опроса. Для недоступного формата, проверьте Форматы метаданных, Смягчить ограничения качества или удалить расширенный селектор. Требуются только аудиозапросы m4a, mp3 или opus; Видеозапросы требуют mp4, webm или mkv.
Если результат JSON истек, сначала проверьте ведро на доставленные носители. Повторная отправка создает новую загрузку и может повлечь за собой еще одну зарядку; она не восстанавливает старый результат JSON.
Для аутентификации, баланса, сбоев формата запроса и ограничения скорости используйте общую ссылку на ошибку. Тайм-аут может все еще создать работу; проверьте существующую работу перед повторным использованием.
Ошибки и коды состояния · Когда повторно · Ограничения по ставкам
Пошаговое руководство: Скачайте одно видео и проверьте доставку
Цены
| Планы | Ставки использованияза ГБ доставлено | Подписки | Включенные кредиты за расчетный период |
|---|---|---|---|
| Оплата по использованию | 0,10 $ | Без ежемесячной платы | Пополняйте по мере необходимости |
| Micro | 0,08 $ | 49,00 $ / месяц | 1 000 кредиты ()50,00 $ из API использование, включая |
| Starter | 0,07 $ | 199,00 $ / месяц | 4 000 кредиты ()200,00 $ из API использование, включая |
| Pro | 0,06 $ | 499,00 $ / месяц | 10 000 кредиты ()500,00 $ из API использование, включая |
| Scale | 0,05 $ | 999,00 $ / месяц | 20 000 кредиты ()1 000,00 $ из API использование, включая |
| Business | 0,04 $ | 1 999,00 $ / месяц | 40 000 кредиты ()2 000,00 $ из API использование, включая |
Один тариф аккаунта. Общие кредиты для трёх продуктов. Использование, покрытое включёнными кредитами, повторно не оплачивается.
Текущие цены и лимиты плана