# FlashData YouTube Download API

Scarica il video o l'audio YouTube sul tuo storage cloud. Scegliere risoluzione, formato e durata della clip, quindi monitorare il lavoro asincrono attraverso il completamento.

Riferimento canonico: https://flashdata.dev/it/docs/sources/youtube_download
Recensito: 2026-10-23

Punto di arrivo: POST https://data.flashdata.dev/v1/queries
Autenticazione: X-API-Key: YOUR_API_KEY
Modalità: [Async](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md)

Permesso di origine richiesto: youtube_download

Sostituisci YOUR_API_KEY con una chiave API che ha questo permesso di origine e crediti disponibili. Eseguire le richieste sul server o sul server host dell'agente.

[Impostare l'autenticazione](https://flashdata.dev/it/docs/guides/headers-and-authentication/reference.md)

[Scarica un video e verifica la consegna](https://flashdata.dev/it/docs/guides/download-video-recipe/reference.md)

[API per scaricare video YouTube — esempi Python](https://github.com/flashdatadev/youtube-video-download-api)

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

## Invia una richiesta

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

## Parametri

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

### Corpo della richiesta

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Sì | — | Impostare su youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Sì | Non impostato | Il video 11-character YouTube video ID, come FUfGcZ092b0. Accetta lettere, numeri, sottolineature e trattini. Lunghezza minima: 11. Lunghezza massima: 11. Modello: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Sì | — | Settings per questa richiesta.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No | Non impostato | Async e solo lotto. Completamento HTTPS pubblico URL sulla porta 443, fino a caratteri 2,048. Nessuna credenziali utente o frammentazione URL. Omit, utilizzare null o una stringa vuota per nessuna notifica. In un lotto, impostare questo su ogni query, param esterni.  |

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

### Video e audio

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | No | "audio_video" | audio_video unisce video e audio; il video seleziona solo video; l'audio seleziona solo l'audio. Consentito: "audio_video", "video", "audio". Lunghezza minima: 1. Lunghezza massima: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | No | "<=720" | Selezione della risoluzione video. Omit per i download audio-solo. Consentito: "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". Lunghezza minima: 1. Lunghezza massima: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | No | Non impostato | Limiti di frame-rate: >=, <= o == seguito da un valore da 1 a 240. Omit per i download audio-solo. Lunghezza minima: 1. Lunghezza massima: 6. Modello: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | No | "default" | Selezione audio. Riguarda audio_video e audio. Consentito: "default", "original". Lunghezza minima: 1. Lunghezza massima: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | No | "best" | Solo bitrate audio in kbps, o meglio. Le scelte numeriche devono essere inviate come stringhe. Omit per i download video. Permesso: "best", "320", "256", "192", "128". Lunghezza minima: 1. Lunghezza massima: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | No | mp4 (video) / m4a (audio) | Video: mp4, webm o mkv. Audio: m4a, mp3 o opus. Consentito: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Lunghezza minima: 1. Lunghezza massima: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | No | Non impostato | Selettore di formato avanzato, da 1 a caratteri 1,024 dopo la rifilatura dello spazio bianco. I caratteri di controllo sono respinti. Sovrascrive video_quality, fps e audio_language, i cui valori vengono quindi ignorati; il formato di output e la clipping si applicano ancora. Lunghezza minima: 1. Lunghezza massima: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | No | false | Caricare un file di metadati JSON accanto al file multimediale nel vostro storage.  |

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

### Clipping

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | No | Non impostato | Avvio clip in H:MM:SS o HH:MM:SS formato, da 00:00:00 a 12:00:00. Predefinisce 00:00:00 quando viene fornito solo end_at. Lunghezza minima: 1. Lunghezza massima: 8. Modello: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | No | Non impostato | Clip end in H:MM:SS o HH:MM:SS formato, fino a 12:00:00. Deve essere più tardi di start_at. Lunghezza minima: 1. Lunghezza massima: 8. Modello: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Destinazione di stoccaggio

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Sì | — | Destinazione per i file multimediali completati. Sono accettati solo i campi di stoccaggio elencati.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Sì | — | Fornitore di stoccaggio: s3, s3_compatible, oss, gcs, azure, cos, bos o tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Sì | — | Secchio non vuoto o nome contenitore, fino a caratteri 1,024. Lo spazio bianco circostante è rimosso. Per s3, utilizzare un nome di secchio AWS valido senza un percorso URL o cartella; le cartelle appartengono a object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | No | "YYYYMMDD" | Prefisso chiave degli oggetti, caratteri 1 a caratteri 512. Ogni segmento separato da slitta accetta lettere, cifre, punti, sottoscore e trattini; segmenti vuoti, . e .. sono respinti. Non c'e' nessun guinzaglio. Circondare lo spazio bianco e uno slash trailing sono rimossi. YYYYMMDD utilizza la data di caricamento UTC, incluso in archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | No | — | Chiave di accesso per S3, compatibile con S3, OSS, COS, BOS o TOS; abbinata a secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | No | — | Chiave segreta per S3, compatibile con S3, OSS, COS, BOS o TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | No | — | endpoint HTTPS pubblico per lo storage compatibile S3 o OSS. COS, BOS e TOS lo derivano dalla regione.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | No | — | Richiesto per COS, BOS e TOS; anche fornire per i download compatibili S3 e S3. I nomi dei benne COS includono l'APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | No | — | account di servizio GCS: project_id, client_email e PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | No | — | Nome dell'account di archiviazione Azure. Utilizzare il nome del contenitore in storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | No | — | Azure contenitore SAS con scadenza e firma.  |

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

## Leggi il risultato

Dopo il completamento del lavoro, salvare la JSON dal suo link di risultati come response.json. Salvare questo come read-response.py ed eseguire pitone read-response.py. Legge i dettagli del file senza scaricare i supporti o fare un'altra richiesta.

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

## Presentazione del campione

Esempio registrato; i campi e i conti dipendono dalla fonte e dall'ingresso richiesto.
```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"
    }
  ]
}
```

## Campi di risposta

| Campo di applicazione | Tipologia | Designazione |
| --- | --- | --- |
| id | string | Scaricare il lavoro ID. |
| source | string | youtube_download. |
| status | string | in attesa di accettare il lavoro. |
| created_at | string | Tempo di creazione di lavoro in formato ISO 8601. |
| usage.credits | number | 0 alla presentazione. I download vengono caricati dal volume dei dati consegnato dopo il completamento. |
| links | array | Seguire l'auto link per lo stato del lavoro e il link dei risultati per l'output completato. |
| links[].rel | string | auto o risultati. |
| links[].href | string | URL per eseguire query con la stessa chiave API. |
| links[].method | string | GET. |

- I download vengono eseguiti come lavori di sfondo. La risposta di presentazione contiene un lavoro ID; non contiene il file multimediale. Seguire lo stato del lavoro fino al completamento, quindi recuperare il risultato descrivendo i file consegnati al vostro storage. Invia download a /v1/queries o /v1/queries/batch; /v1/queries/realtime non accetta le richieste di download.

## Formati di risposta

Le risposte usano JSON per impostazione predefinita. Scegli un altro formato con queste intestazioni opzionali.

- Accept: application/json (predefinito) o text/plain. Testo normale presenta gli stessi campi in un layout leggibile e indentato.
- X-Respond-With: markdown. Lasciare unset per i campi originali. Markdown funziona con il formato di risposta.

Markdown formatta il manifesto di download; i file multimediali mantengono il loro formato originale. Ricevimenti e supporto per lo stato di lavoro Accept solo.

I campi sottostanti descrivono la risposta predefinita JSON.

[Esempi di formato di richiesta e risposta](https://flashdata.dev/it/docs/guides/response-formats/reference.md#completed-results)

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

## Destinazione di stoccaggio

I download di single-job e Batch richiedono params.storage; I download Bulk utilizzano options.storage. storage_url è il nome del secchio o del contenitore. Fornire le credenziali con l'accesso di scrittura e tenerle sul server.

### s3

Fornire access_key e secret_key con accesso a scrittura. Impostare la regione nella regione AWS del vostro secchio.

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

Fornitura access_key, secret_key e un pubblico HTTPS endpoint_url. Impostare la regione come richiesto dal vostro fornitore; Cloudflare R2 utilizza auto.

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

Fornire account_name e sas_token, un contenitore SAS con permesso di scrittura (sp include w), sr=c delle risorse, scadenza se, versione sv e firma sig. storage_url è il nome del contenitore. Non inviare endpoint_url, access_key o 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

Alimentazione access_key, secret_key e regione: bj, su o hkg. Il punto finale è derivato dalla regione quando omesso. Utilizzare un nome di secchio senza punti.

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

### cos

Fornire access_key, secret_key e una regione ap-*, come ap-hongkong. storage_url deve includere il suffisso APPID. Non inviare endpoint_url; è derivato dalla regione.

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

### gcs

Fornire service_account con project_id, client_email (un indirizzo .gserviceaccount.com), e PEM private_key dal tuo account di servizio. L'account deve avere accesso al secchio. Non inviare access_key, secret_key, regione o 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

Fornire access_key, secret_key e la regione di secchiello 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

Fornire access_key, secret_key e la regione con un cn-, ap-, eu- o noi- prefisso. Il punto finale è derivato dalla regione quando omesso. Utilizzare un nome di secchio senza punti.

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

## Nozioni di base sulle API

Il costruttore di richieste ed esempi sopra usano i parametri di questa fonte. Utilizzare gli esempi Python e cURL qui sotto per la presentazione condivisa, lo stato e i passaggi di risultato. Un corpo Batch è un oggetto JSON contenente query; ogni elemento restituisce il proprio lavoro ID.

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

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

- [Controllare lo stato del lavoro](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#status)

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

- [Recuperare i risultati completati](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#results)
- [richieste Batch JSON](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#batch)
- [API di elaborazione Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md)
- [Costruire un flusso di lavoro Bulk per questa sorgente](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Clienti OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notifiche di completamento

- [Ricevi e verifica il completamento webhooks](https://flashdata.dev/it/docs/guides/async-batch/reference.md#webhooks)

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

## Risoluzione dei problemi

- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md#status-codes)
- [Quando riprova](https://flashdata.dev/it/docs/errors/reference.md#retries)

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

## Consegna dei file

Il download non supporta in tempo reale.

I supporti vengono caricati sull'archiviazione configurata; il risultato JSON descrive questi file. I media privati utilizzano l'autenticazione di archiviazione. I risultati di JSON scadono a 24 ore dopo il completamento; i media seguono la politica di conservazione.

## API correlate

- [YouTube Video Metadati API](https://flashdata.dev/it/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/it/docs/sources/youtube_transcript/reference.md)
