# FlashData API de téléchargement YouTube

Téléchargez des vidéos ou de l’audio YouTube dans votre stockage cloud. Choisissez la résolution, le format et la durée de l’extrait, puis suivez la tâche asynchrone jusqu’à la fin.

Référence canonique : https://flashdata.dev/fr/docs/sources/youtube_download
Révisé le : 2026-10-23

Endpoint: POST https://data.flashdata.dev/v1/queries
Authentification: X-API-Key: YOUR_API_KEY
Modes: [Asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md)

Autorisation requise pour la source: youtube_download

Remplacez YOUR_API_KEY par une clé API disposant de la permission requise pour cette source et d’un solde de crédits disponible. Exécutez les requêtes sur votre serveur ou dans l’environnement de votre agent.

[Configurer l’authentification](https://flashdata.dev/fr/docs/guides/headers-and-authentication/reference.md)

[Télécharger une vidéo et vérifier la livraison](https://flashdata.dev/fr/docs/guides/download-video-recipe/reference.md)

[API de téléchargement de vidéos YouTube — exemples Python](https://github.com/flashdatadev/youtube-video-download-api)

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

## Envoyer une requête

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

## Paramètres

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

### Corps de la requête

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Oui | — | Définissez ce champ sur youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Oui | Non défini | Identifiant YouTube de la vidéo, composé de 11 caractères, par exemple FUfGcZ092b0. Les lettres, chiffres, tirets bas et traits d’union sont acceptés. Longueur minimale : 11. Longueur maximale : 11. Format : ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Oui | — | Paramètres de cette requête.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Non | Non défini | Async et Batch uniquement. URL HTTPS publique de notification sur le port 443, de 2 048 caractères maximum, sans identifiants ni fragment. Omettez ce champ, ou utilisez null ou une chaîne vide pour désactiver les notifications. Dans un Batch, définissez-le pour chaque requête, en dehors de params.  |

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

### Vidéo et audio

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Non | "audio_video" | audio_video fusionne la vidéo et l’audio ; video sélectionne uniquement la vidéo ; audio sélectionne uniquement l’audio. Valeurs acceptées : "audio_video", "video", "audio". Longueur minimale : 1. Longueur maximale : 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Non | "<=720" | Résolution vidéo souhaitée. Omettez ce champ pour un téléchargement audio seul. Valeurs acceptées : "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". Longueur minimale : 1. Longueur maximale : 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Non | Non défini | Contrainte de fréquence d’images : >=, <= ou == suivi d’une valeur de 1 à 240. Omettez ce champ pour un téléchargement audio seul. Longueur minimale : 1. Longueur maximale : 6. Format : ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Non | "default" | Sélection de la piste audio. S’applique à audio_video et audio. Valeurs acceptées : "default", "original". Longueur minimale : 1. Longueur maximale : 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Non | "best" | Débit de l’audio seul en kbps, ou best. Envoyez les valeurs numériques sous forme de chaînes. Omettez ce champ pour les téléchargements vidéo. Valeurs acceptées : "best", "320", "256", "192", "128". Longueur minimale : 1. Longueur maximale : 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Non | mp4 (video) / m4a (audio) | Vidéo : mp4, webm ou mkv. Audio : m4a, mp3 ou opus. Valeurs acceptées : "mp4", "webm", "mkv", "m4a", "mp3", "opus". Longueur minimale : 1. Longueur maximale : 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Non | Non défini | Sélecteur de format avancé, de 1 à 1 024 caractères après suppression des espaces en début et en fin. Les caractères de contrôle sont refusés. Remplace video_quality, fps et audio_language, dont les valeurs sont alors ignorées ; le format de sortie et les limites de l’extrait restent appliqués. Longueur minimale : 1. Longueur maximale : 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Non | false | Envoyez un fichier JSON de métadonnées avec le fichier multimédia dans votre stockage.  |

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

### Découpe

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Non | Non défini | Début de l’extrait au format H:MM:SS ou HH:MM:SS, de 00:00:00 à 12:00:00. Vaut 00:00:00 si seul end_at est fourni. Longueur minimale : 1. Longueur maximale : 8. Format : ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Non | Non défini | Fin de l’extrait au format H:MM:SS ou HH:MM:SS, jusqu’à 12:00:00. Doit être postérieure à start_at. Longueur minimale : 1. Longueur maximale : 8. Format : ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Destination de stockage

| Paramètre | Type | Obligatoire | Par défaut | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Oui | — | Destination des fichiers multimédias une fois le traitement terminé. Seuls les champs de stockage indiqués sont acceptés.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Oui | — | Fournisseur de stockage : s3, s3_compatible, oss, gcs, azure, cos, bos ou tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Oui | — | Nom de bucket ou de conteneur non vide, de 1 024 caractères maximum. Les espaces en début et en fin sont supprimés. Pour s3, utilisez un nom de bucket AWS valide, sans URL ni chemin de dossier ; indiquez les dossiers dans object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Non | "YYYYMMDD" | Préfixe des clés d’objet, de 1 à 512 caractères. Chaque segment séparé par une barre oblique accepte les lettres ASCII, chiffres, points, tirets bas et traits d’union ; les segments vides, . et .. sont refusés. Aucune barre oblique initiale. Les espaces en début et en fin ainsi qu’une barre oblique finale sont supprimés. YYYYMMDD représente la date UTC d’envoi vers le stockage, y compris dans archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Non | — | Clé d’accès pour S3, un stockage compatible S3, OSS, COS, BOS ou TOS ; à associer à secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Non | — | Clé secrète pour S3, un stockage compatible S3, OSS, COS, BOS ou TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Non | — | URL HTTPS publique du service de stockage compatible S3 ou OSS. Pour COS, BOS et TOS, cette URL est déterminée à partir de region.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Non | — | Obligatoire pour COS, BOS et TOS ; à fournir également pour les téléchargements vers S3 et les stockages compatibles S3. Les noms de bucket COS incluent l’APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Non | — | Compte de service GCS : project_id, client_email et private_key au format PEM.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Non | — | Nom du compte de stockage Azure. Utilisez le nom du conteneur dans storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Non | — | Jeton SAS du conteneur Azure autorisant l’écriture, avec date d’expiration et signature.  |

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

## Lire le résultat

Une fois la tâche terminée, enregistrez le JSON obtenu via son lien de résultats dans response.json. Enregistrez le script ci-dessous dans read-response.py, dans le même dossier, puis exécutez python read-response.py. Il lit les informations sur les fichiers sans télécharger de média ni envoyer de nouvelle requête.

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

## Exemple de soumission

Exemple enregistré ; les champs et les nombres de résultats dépendent de la source et des paramètres de la requête.
```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"
    }
  ]
}
```

## Champs de réponse

| Champ | Type | Description |
| --- | --- | --- |
| id | string | Identifiant de la tâche de téléchargement. |
| source | string | youtube_download. |
| status | string | pending lorsque la tâche est acceptée. |
| created_at | string | Date et heure de création de la tâche au format ISO 8601. |
| usage.credits | number | 0 à la soumission. Après la fin du traitement, les téléchargements sont facturés selon le volume de données livré. |
| links | array | Suivez le lien self pour consulter l’état de la tâche et le lien results pour récupérer le résultat une fois le traitement terminé. |
| links[].rel | string | self ou results. |
| links[].href | string | URL à appeler avec la même clé API. |
| links[].method | string | GET. |

- Les téléchargements s’exécutent en arrière-plan. La réponse à la soumission contient un identifiant de tâche, pas le fichier multimédia. Suivez l’état de la tâche jusqu’à la fin, puis récupérez le résultat décrivant les fichiers livrés dans votre stockage. Soumettez les téléchargements à /v1/queries ou /v1/queries/batch ; /v1/queries/realtime n’accepte pas les requêtes de téléchargement.

## Formats de réponse

Les réponses sont en JSON par défaut. Choisissez un autre format avec ces en-têtes facultatifs.

- Accept: application/json (par défaut) ou text/plain. Le texte brut présente les mêmes champs dans une disposition lisible avec indentation.
- X-Respond-With: markdown. Ne définissez pas cet en-tête pour conserver les champs d’origine. Markdown fonctionne avec les deux formats de réponse.

Markdown formate le manifeste de téléchargement ; les fichiers média conservent leur format d’origine. Les reçus et l’état des tâches prennent uniquement en charge Accept.

Les champs ci-dessous décrivent la réponse JSON par défaut.

[Exemples de formats de requête et de réponse](https://flashdata.dev/fr/docs/guides/response-formats/reference.md#completed-results)

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

## Destination de stockage

Les téléchargements individuels et Batch exigent params.storage ; les téléchargements Bulk utilisent options.storage. storage_url désigne le bucket ou le conteneur. Fournissez des identifiants disposant d’un accès en écriture et conservez-les sur votre serveur.

### s3

Fournissez access_key et secret_key avec des droits d’écriture. Définissez region sur la région AWS de votre bucket.

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

Fournissez access_key, secret_key et une endpoint_url HTTPS publique. Définissez region selon les exigences de votre fournisseur ; Cloudflare R2 utilise 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

Fournissez account_name et sas_token. Le SAS du conteneur doit autoriser l’écriture (sp inclut w) et contenir la ressource sr=c, l’expiration se, la version sv et la signature sig. storage_url est le nom du conteneur. N’envoyez pas endpoint_url, access_key ni 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

Fournissez access_key, secret_key et region : bj, su ou hkg. Si l’URL du service n’est pas fournie, elle est déterminée à partir de region. Utilisez un nom de bucket sans points.

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

### cos

Fournissez access_key, secret_key et une region de la forme ap-*, comme ap-hongkong. storage_url doit inclure le suffixe APPID. N’envoyez pas endpoint_url ; cette URL est déterminée à partir de region.

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

### gcs

Fournissez service_account avec project_id, client_email (une adresse en .gserviceaccount.com) et la private_key au format PEM de votre compte de service. Ce compte doit avoir un accès en écriture au bucket. N’envoyez pas access_key, secret_key, region ni 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

Fournissez access_key, secret_key et l’endpoint_url HTTPS publique correspondant à la région du bucket.

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

Fournissez access_key, secret_key et region avec un préfixe cn-, ap-, eu- ou us-. Si l’URL du service n’est pas fournie, elle est déterminée à partir de region. Utilisez un nom de bucket sans points.

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

## Bases de l’API

Le générateur de requêtes et les exemples ci-dessus utilisent les paramètres de cette source. Consultez les exemples Python et cURL ci-dessous pour les étapes communes de soumission, de suivi et de récupération des résultats. Le corps d’une requête Batch est un objet JSON contenant queries ; chaque élément renvoie son propre identifiant de tâche.

- [Requête Async et reçu de soumission](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async)

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

- [Vérifier l’état de la tâche](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#status)

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

- [Récupérer les résultats des tâches terminées](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#results)
- [Requêtes JSON Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch)
- [API de traitement Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md)
- [Préparer un traitement Bulk pour cette source](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Spécification OpenAPI publique](https://flashdata.dev/docs/openapi.json)

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

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

## Notifications d'achèvement

- [Recevoir et vérifier les webhooks de fin de traitement](https://flashdata.dev/fr/docs/guides/async-batch/reference.md#webhooks)

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

## Dépannage

- [Erreurs et codes d’état](https://flashdata.dev/fr/docs/errors/reference.md#status-codes)
- [Quand réessayer](https://flashdata.dev/fr/docs/errors/reference.md#retries)

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

## Livraison de fichiers

Download ne prend pas en charge le mode realtime.

Les médias sont envoyés vers le stockage que vous avez configuré ; les résultats JSON décrivent ces fichiers. Les médias privés nécessitent les identifiants de votre stockage. Les résultats JSON expirent 24 heures après la fin du traitement ; les médias suivent la politique de conservation de votre stockage.

## API associées

- [API de métadonnées vidéo YouTube](https://flashdata.dev/fr/docs/sources/youtube_metadata/reference.md)
- [API de transcription YouTube](https://flashdata.dev/fr/docs/sources/youtube_transcript/reference.md)
