# YouTube Scarica le migliori pratiche

Scegliere l'output dei media giusto, controllare quello che si scarica, e trasformare un lavoro completato in un file privato utilizzabile.

Riferimento canonico: https://flashdata.dev/it/docs/guides/youtube-download-guide
Recensito: 2026-11-04 da FlashData

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

## Iniziare con ciò che il vostro compito ha bisogno

| Il tuo obiettivo | Uso |
| --- | --- |
| Sommarizzare il contenuto parlato o costruire un indice di testo | Leggi prima una trascrizione esistente. Scarica l'audio solo quando il flusso di lavoro ha bisogno dell'audio stesso, come un passo vocale-to-text separato. |
| Discorso di processo o audio | Uscita solo audio. Evitare di portare un video traccia la vostra applicazione non utilizza. |
| Mostra un breve estratto | Impostare start_at e end_at. Controllare che entrambi sono entro la durata del video di origine. |
| Giocare o elaborare video | MP4 con audio e un tappo di risoluzione adatto alla vostra applicazione; l'esempio utilizza <=720. |

- [Sommari da didascalie](https://flashdata.dev/it/docs/guides/youtube-summary/reference.md)
- [Ispezione dei metadati video](https://flashdata.dev/it/docs/guides/youtube-data-guide/reference.md#metadata)

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

## Salva l'output che vuoi

Scegliere una scheda e salvare la sua intera richiesta come download-request.json. Cambia video_id per la tua fonte. I comandi di presentazione qui sotto leggere questo file, quindi la scelta di audio o di una clip cambia la richiesta reale.

### MP4 / 720p

Un video completo con audio, incappucciato a 720p.

#### download-request.json

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


### MP3

Un file audio per l'ascolto o l'ulteriore elaborazione audio.

#### download-request.json

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


### 5 secondo clip

Un estrattore MP4 da 00:00:05 a 00:00:10. Utilizza i tempi che corrispondono al tuo video selezionato.

#### 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"
  }
}
```


- [Tutte le opzioni di formato](https://flashdata.dev/it/docs/sources/youtube_download/reference.md#parameters)

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

## Controllare l'accesso del proprietario e i prezzi basati su byte

Utilizzare Bash e jq, oltre a un profilo CLI salvato o FLASHDATA_API_KEY per HTTP. La chiave ha bisogno del permesso youtube_download. Il download richiede l'accesso del proprietario; l'accesso temporaneo alla prova non lo include. Gli esempi di CLI utilizzano il profilo predefinito; aggiungi --profile NAME ad ogni comando se il tuo viene chiamato.

| Decisione | Applicare in questo modo |
| --- | --- |
| Costo stimato | Utilizzare il creditsPerTb e bytesPerUnit restituiti con i byte di output stimati. Scarica i prezzi non è una tassa fissa per richiesta. |
| Campo di controllo | Scegliere l'audio, una clip o un tappo di risoluzione prima della presentazione. Applicare le regole di lavoro e di spesa nella tua applicazione. |
| Registrare la carica effettiva | Leggi l'utilizzo dalla consegna completata. L'ammissione può contenere crediti prima che il caricamento si stabilisca; l'equilibrio corrente non è un tappo di spesa per lavoro. |

### Controlli gratuiti · CLI

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

- [Configurazione chiave del proprietario](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md)
- [HTTP equilibrio e prezzi](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md#balance)

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

## Utilizzare una destinazione privata per ogni uscita

Salva storage.json in privato con i tuoi valori di destinazione reali. Tienilo fuori dal controllo sorgente. Utilizzare una object_prefix distinta per ogni versione video/output; riutilizzare un prefisso per diverse uscite rende i record di applicazione più difficili da conciliare.

| Credenziali | Oggetto |
| --- | --- |
| Chiave FlashData | Inviare il download e leggere il suo lavoro e la consegna JSON. |
| Archiviazione delle credenziali di upload | Scrivere i supporti al secchio e prefisso previsto. |
| Identità dell'archivio di applicazione | Leggi l'oggetto privato o rilascia l'accesso a un utente autorizzato. |

### 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 · file privato

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

- [autorizzazioni di file Windows](https://flashdata.dev/it/docs/guides/cli-automation/reference.md#storage)
- [Altri fornitori di storage](https://flashdata.dev/it/docs/sources/youtube_download/reference.md#storage)

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

## Inviare la richiesta salvata una volta

Eseguire una scheda dopo aver salvato entrambi i file. Il comando inietta storage.json tramite stdin e salva download-submission.json. Tieni la ricevuta. Con CLI, mantenere lo stesso run ID per una riprova; utilizzare una nuova ID solo per una nuova uscita intenzionale. Le sottomissioni HTTP non utilizzano la rivista locale di gestione di CLI.

### CLI

#### Inviare l'output scelto

```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

#### Inviare l'output scelto

```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
)
```


- [contratto di richiesta Async](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#async)

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

### Convalida prima con CLI

Aspettatevi ok: true e data.dryRun: true. Questo verifica l'ingresso e l'accesso FlashData senza presentare un lavoro; non dimostra che le credenziali di upload possono scrivere al tuo secchio.

#### Corsa a secco gratuita

```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>

### Attendere il lavoro esistente

La ricevuta di presentazione non è il file multimediale. CLI aspetta; il comando HTTP legge lo stato una volta. Ripeti la lettura entro la tua scadenza fino a completata o fallita. Un timeout locale non cancella il lavoro del server.

#### CLI

##### Attendere il lavoro salvato

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


#### HTTP / cURL

##### Leggi lo stato una volta

```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>

## Leggi il record di consegna, quindi accedi ai media

Dopo aver completato, recuperare delivery.json utilizzando lo stesso percorso che hai usato per inviare. Il risultato firmato URL recupera JSON; risultati[0].file_url identifica i supporti nella memorizzazione. Un file_url privato ha bisogno della vostra identità di lettura di archiviazione o di un link rilasciato dalla vostra applicazione.

### CLI

#### Salvare 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

#### Consegna del prezzo JSON · mantenere il tasto API le richieste di archiviazione

```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>

### Controllare cosa è stato consegnato

Aspettatevi una posizione del file, un file_size positivo, un MD5 e l'uso. Registrare file_size per l'oggetto consegnato; downloaded_bytes è un campo di trasferimento, non un sostituto per la carica finale in uso.

#### Ispezione 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
)
```

- [Verificare e servire un oggetto privato](https://flashdata.dev/it/docs/guides/media-delivery-pipeline/reference.md#verify)

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

### Verificare una copia locale da S3

Impostare OBJECT_KEY alla chiave multimediale consegnata da file_url, incluso il suo prefisso. Utilizzare AWS CLI con accesso a lettura, jq e OpenSSL. Questo consente di salvare media.mp4 o media.mp3 in base alla richiesta selezionata e di controllare le sue dimensioni e checksum senza sovrascrivere un file locale esistente.

#### S3 leggere · nessuna nuova query 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'
)
```

- [Ritenzione dei risultati e supporti memorizzati](https://flashdata.dev/it/docs/guides/save-results/reference.md#media)

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

## Recuperare dal palco che non è riuscito

| Che cosa è successo? | Prossima azione |
| --- | --- |
| Presentazione time out senza lavoro confermato ID | Ispezionare la cronologia di esecuzione o richiesta CLI salvato. Mantenere l'ingresso originale e non inviare automaticamente di nuovo. |
| Lavoro accettato; aspettare tempo fuori | Leggere o recuperare lo stesso lavoro. Non creare un altro download per continuare ad aspettare. |
| Caricamento fallito | Leggere l'errore di lavoro e correggere le impostazioni di destinazione o scrivere l'accesso prima di riprovare intenzionalmente. |
| Media letto aggiunto 403 | Controllare le autorizzazioni di lettura di storage o il link di applicazione-stampato. La chiave FlashData API non sblocca S3. |
| Risultato firmato JSON scaduto | Leggi il risultato del lavoro endpoint di nuovo mentre il risultato viene mantenuto. I supporti archiviati seguono il ciclo di vita del tuo secchio. |

### CLI · ispezionare l'esecuzione salvata

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

- [Decisioni di recupero](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)
- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md)
- [Attività ricorrenti](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)

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

## Dare al vostro agente i criteri di uscita e consegna

### Attività agente · fornire il video, la destinazione e il budget

```text
Utilizzare l'accesso del mio proprietario salvato e lo storage privato configurato.
Leggi download-request.json per il video e l'output; non cambiarli silenziosamente.
Controllare Scarica i prezzi e i crediti disponibili contro il budget delle attività approvate.
Inviare una volta, salvare il run/job ID, quindi leggere quel lavoro al completamento.
Risparmia il record di consegna. Verificare le dimensioni dell'oggetto memorizzato e MD5 prima di elaborarlo.
Segnala la posizione dell'oggetto, il formato scelto, il risultato di verifica e l'utilizzo effettivo.
Se la presentazione è incerta, ispezionare il lavoro salvato; non creare l'accesso sostitutivo o un altro download.
Tenere le credenziali di archiviazione private. Condividere i media solo attraverso i controlli di accesso configurati dell'applicazione.
```

- [Costruisci la pipeline di applicazione](https://flashdata.dev/it/docs/guides/media-delivery-pipeline/reference.md)
