# Лучшие практики YouTube Download

Выберите правильный вывод медиафайла, управляйте тем, что вы загружаете, и превратите завершенную работу в полезный частный файл.

Каноническая ссылка: https://flashdata.dev/ru/docs/guides/youtube-download-guide
Разработчик: 2026-11-04 by FlashData

<a id="choose"></a>

## Начните с того, что нужно вашей задаче

| Ваша цель | Использовать |
| --- | --- |
| Обобщайте разговорный контент или создайте текстовый индекс | Сначала прочитайте существующую стенограмму. Скачайте аудио только тогда, когда ваш рабочий процесс нуждается в самом аудио, например, в отдельном шаге от речи к тексту. |
| Процессная речь или аудио | Аудио-только выход. Избегайте просмотра видео, которое ваше приложение не использует. |
| Показать короткий отрывок | Установите start_at и end_at. Убедитесь, что оба находятся в пределах продолжительности исходного видео. |
| Играть или обрабатывать видео | MP4 с аудио и разрешением, подходящим для вашего приложения; пример использует <=720. |

- [Резюме из подписей](https://flashdata.dev/ru/docs/guides/youtube-summary/reference.md)
- [Проверить видео метаданные](https://flashdata.dev/ru/docs/guides/youtube-data-guide/reference.md#metadata)

<a id="formats"></a>

## Сохраните выход, который вы хотите

Выберите одну вкладку и сохраните весь ее запрос как download-request.json. Измените video_id для вашего источника. Приводимые ниже команды представления читают этот файл, поэтому выбор аудио или клипа изменяет фактический запрос.

### MP4 / 720p

Полное видео с аудио, ограниченное 720p.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720"
  }
}
```


### MP3

Аудиофайл для прослушивания или дальнейшей обработки звука.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio",
    "output_format": "mp3"
  }
}
```


### 5 второй клип

Выдержка из MP4 от 00:00:05 до 00:00:10. Используйте время, которое соответствует выбранному вами видео.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720",
    "start_at": "00:00:05",
    "end_at": "00:00:10"
  }
}
```


- [Все варианты форматов](https://flashdata.dev/ru/docs/sources/youtube_download/reference.md#parameters)

<a id="prepare"></a>

## Проверьте доступ владельца и цены на основе байтов

Используйте Bash и jq, а также сохраненный профиль CLI или FLASHDATA_API_KEY для HTTP. Ключ должен иметь разрешение youtube_download. Загрузка требует доступа владельца; временный пробный доступ не включает его. Примеры CLI используют ваш профиль по умолчанию; добавьте имя --profile в каждую команду, если ваша команда называется.

| Решение | Применять таким образом |
| --- | --- |
| Оценочная стоимость | Используйте возвращенные creditsPerTb и bytesPerUnit с расчетными выходными байтами. Цена загрузки не является фиксированной платой за запрос. |
| Контрольный охват | Выберите аудио, клип или ограничение разрешения перед отправкой. Примените правила учета вакансий и расходов в своем приложении. |
| Запись фактического заряда | Прочитайте использование от завершенной доставки. Прием может удерживать кредиты до того, как загрузка оседает; текущий баланс не является ограничением расходов на работу. |

### Бесплатные чеки · CLI

```bash
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json
```

- [Настройка ключа владельца](https://flashdata.dev/ru/docs/guides/api-keys-and-permissions/reference.md)
- [Баланс HTTP и цены](https://flashdata.dev/ru/docs/guides/credits-and-billing/reference.md#balance)

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

## Используйте частный пункт назначения для каждого вывода

Сохраните storage.json в частном порядке с вашими реальными значениями назначения. Держите его вне контроля источника. Используйте отдельный object_prefix для каждой версии video/output; повторное использование префикса для разных выходов затрудняет согласование записей приложений.

| Полномочия | Цель |
| --- | --- |
| Ключ FlashData | Отправьте загрузку и прочитайте его работу и доставку JSON. |
| Удостоверение на загрузку хранилища | Напишите медиа на предполагаемое ведро и приставку. |
| Идентификатор хранения данных | Прочитайте частный объект или выдайте доступ авторизованному пользователю. |

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1",
  "object_prefix": "media/video-001/mp4-720p-v1"
}
```

### Linux / macOS · частный файл

```bash
chmod 600 storage.json
```

- [Разрешения на файл Windows](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md#storage)
- [Другие поставщики услуг хранения](https://flashdata.dev/ru/docs/sources/youtube_download/reference.md#storage)

<a id="submit"></a>

## Отправьте сохраненный запрос один раз

Запустите одну вкладку после сохранения обоих файлов. Команда впрыскивает storage.json через stdin и сохраняет download-submission.json. Сохрани эту квитанцию. С CLI сохраняйте тот же самый запуск ID для повторного использования; используйте новый ID только для преднамеренного нового вывода. В материалах HTTP не используется локальный журнал CLI.

### CLI

#### Предоставить выбранный результат

```bash
(
set -eu
umask 077
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async \
  --run-id download-001 --output download-submission.json
)
```


### HTTP / cURL

#### Предоставить выбранный результат

```bash
(
set -eu
umask 077
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Content-Type: application/json' \
  --data-binary @- --output download-submission.json
)
```


- [Async запрашивает контракт](https://flashdata.dev/ru/docs/reference/realtime-and-async/reference.md#async)

<a id="dry-run"></a>

### Валидировать сначала с CLI

Ожидайте ok: true и data.dryRun: true. Это проверяет вход и доступ FlashData без отправки работы; это не доказывает, что учетные данные загрузки могут писать в ваше ведро.

#### Бесплатный сухой курс

```bash
(
set -eu
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async --dry-run --json
)
```


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

### Дождитесь существующей работы

Квитанция о представлении не является медиафайлом. CLI ждет; команда HTTP читает статус один раз. Повторите чтение в течение срока до завершения или неудачи. Местный тайм-аут не отменяет работу сервера.

#### CLI

##### Дождитесь спасенной работы

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)
```


#### HTTP / cURL

##### Прочитать статус один раз

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
STATUS_URL=$(jq -er '.links[] | select(.rel == "self") | .href' download-submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  "$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)
```



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

## Прочитайте запись доставки, а затем получите доступ к СМИ

После завершения, извлеките delivery.json, используя тот же путь, который вы использовали для отправки. Подписанный результат URL извлекает JSON; results[0].file_url идентифицирует носитель в вашем хранилище. Частный file_url нуждается в вашей идентификационной информации или ссылке, выпущенной вашим приложением.

### CLI

#### Скачать delivery.json

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs result "$JOB_ID" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```


### HTTP / cURL

#### Доставка JSON · отключите ключ API от запросов на хранение

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
jq -e '.job.status == "completed"' job.json >/dev/null
RESULTS_URL=$(jq -er '.links[] | select(.rel == "results") | .href' download-submission.json)
# Get the signed JSON URL without forwarding the API key to storage.
STORAGE_URL=$(curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  --output /dev/null --write-out '%{redirect_url}' "$RESULTS_URL")
: "${STORAGE_URL:?No signed result URL was returned}"
curl --fail-with-body --silent --show-error --compressed --max-time 70 \
  "$STORAGE_URL" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```



<a id="inspect"></a>

### Проверьте, что было доставлено

Ожидайте одно местоположение файла, положительный file_size, MD5 и использование. Запись file_size для поставленного объекта; downloaded_bytes является передаточным полем, а не заменой конечной зарядки при использовании.

#### Проверка delivery.json

```bash
(
set -eu
jq -e '.source == "youtube_download" and .status == "done"
  and (.results | length == 1) and (.results[0].file_size > 0)
  and (.results[0].md5 | test("^[a-fA-F0-9]{32}$"))' delivery.json >/dev/null
jq '{file: (.results[0] | {file_url, file_size, md5, duration, output_format}), usage}' delivery.json
)
```

- [Проверять и обслуживать частный объект](https://flashdata.dev/ru/docs/guides/media-delivery-pipeline/reference.md#verify)

<a id="verify-media"></a>

### Проверьте локальную копию от S3

Установите OBJECT_KEY на доставляемый медиаключ от file_url, включая его префикс. Используйте AWS CLI с доступом к чтению, jq и OpenSSL. Это сохраняет media.mp4 или media.mp3 в соответствии с выбранным вами запросом и проверяет его размер и контрольную сумму без перезаписи существующего локального файла.

#### S3 читать · нет нового запроса FlashData

```bash
(
set -eu
# Requires AWS CLI configured for read access, jq and OpenSSL.
# Set OBJECT_KEY to the delivered media object's key from file_url.
: "${OBJECT_KEY:?Set the delivered S3 object key}"
BUCKET=$(jq -er '.storage_url' storage.json)
REGION=$(jq -er '.region' storage.json)
FORMAT=$(jq -er '.params.output_format' download-request.json)
case "$FORMAT" in mp4|mp3) ;; *) echo 'Choose a filename for this format.' >&2; exit 1 ;; esac
LOCAL_FILE="media.$FORMAT"
test ! -e "$LOCAL_FILE" || { echo 'Keep the existing local file.' >&2; exit 1; }
EXPECTED_BYTES=$(jq -er '.results[0].file_size' delivery.json)
EXPECTED_MD5=$(jq -er '.results[0].md5 | ascii_downcase' delivery.json)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "$LOCAL_FILE" --region "$REGION" --only-show-errors
ACTUAL_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
ACTUAL_MD5=$(openssl dgst -md5 "$LOCAL_FILE" | awk '{print $NF}')
test "$ACTUAL_BYTES" = "$EXPECTED_BYTES"
test "$ACTUAL_MD5" = "$EXPECTED_MD5"
echo 'Delivery verified'
)
```

- [Результат хранения и хранимые носители](https://flashdata.dev/ru/docs/guides/save-results/reference.md#media)

<a id="operations"></a>

## Восстановление со сцены, которая провалилась

| Что случилось? | Следующее действие |
| --- | --- |
| Заявка отложена без подтвержденной работы ID | Проверьте сохраненный запуск CLI или историю запросов. Сохраняйте исходный ввод и не отправляйте автоматически снова. |
| Работа принята; ожидание отложено | Прочитайте или восстановите ту же работу. Не создавайте очередную загрузку, чтобы продолжить ожидание. |
| Загрузить не удалось | Прочитайте ошибку в работе и исправьте настройки назначения или напишите доступ перед преднамеренной повторной попыткой. |
| СМИ вернули 403 | Проверить хранилище считывать разрешения или ссылку, выпущенную приложением. Ключ FlashData API не открывает S3. |
| Подписанный результат JSON истек | Прочитайте конечную точку результата работы снова, пока результат сохраняется. Хранимые медиа следуют жизненному циклу вашего ведра. |

### CLI · проверка сохраненного пробега

```bash
flashdata runs show download-001 --json
```

- [Решения о восстановлении](https://flashdata.dev/ru/docs/guides/agent-recovery/reference.md)
- [Ошибки и коды состояния](https://flashdata.dev/ru/docs/errors/reference.md)
- [Регулярные задачи](https://flashdata.dev/ru/docs/guides/recurring-tasks/reference.md)

<a id="agent"></a>

## Дайте своему агенту критерии вывода и доставки

### Задача агента · предоставить видео, пункт назначения и бюджет

```text
Воспользуйтесь сохраненным доступом владельца и настроенным частным хранилищем.
Прочитайте download-request.json для видео и вывода; не меняйте их молча.
Проверьте цены загрузки и доступные кредиты по утвержденному бюджету задач.
Отправьте один раз, сохраните run/job ID, а затем прочитайте эту работу до завершения.
Сохраните запись доставки. Проверяйте размер хранимого объекта и MD5 перед его обработкой.
Сообщите о местоположении объекта, выбранном формате, результатах проверки и фактическом использовании.
Если представление неопределенно, проверьте сохраненную работу; не создавайте доступ к замене или другую загрузку.
Держите учетные данные хранения в секрете. Делитесь мультимедиа только через настроенные средства управления доступом приложения.
```

- [Создайте трубопровод приложений](https://flashdata.dev/ru/docs/guides/media-delivery-pipeline/reference.md)
