# FlashData YouTube Download API

Laden Sie YouTube Video oder Audio auf Ihren Cloud-Speicher herunter. Wählen Sie Auflösung, Format und Clipdauer und verfolgen Sie dann den asynchronen Job bis zum Abschluss.

Kanonische Referenz: https://flashdata.dev/de/docs/sources/youtube_download
Überarbeitet: 2026-10-23

Endpunkt: POST https://data.flashdata.dev/v1/queries
Authentifizierung: X-API-Key: YOUR_API_KEY
Modi: [Async](https://flashdata.dev/de/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/de/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md)

Erforderliche Berechtigung für die Quelle: youtube_download

Ersetzen Sie YOUR_API_KEY durch einen API-Schlüssel, der über diese Quellberechtigung und verfügbare Credits verfügt. Führen Sie Anfragen auf Ihrem Server oder Agent-Host aus.

[Authentifizierung einrichten](https://flashdata.dev/de/docs/guides/headers-and-authentication/reference.md)

[Laden Sie ein Video herunter und überprüfen Sie die Lieferung](https://flashdata.dev/de/docs/guides/download-video-recipe/reference.md)

[YouTube-Video-Download-API — Python-Beispiele](https://github.com/flashdatadev/youtube-video-download-api)

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

## Senden Sie eine Anfrage

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

## Parameter

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

### Anfrageinhalt

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Ja | — | Setzen Sie auf youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Ja | Nicht eingestellt | Das 11-Charakter YouTube Video ID, wie FUfGcZ092b0. Akzeptiert Buchstaben, Zahlen, Unterstriche und Bindestriche. Min. Länge: 11. Maximale Länge: 11. Muster: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Ja | — | Settings für diese Anfrage.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Nein | Nicht eingestellt | Async und Batch nur. Öffentliche HTTPS Fertigstellung URL auf Port 443, bis zu 2,048 Zeichen. Keine Benutzeranmeldeinformationen oder URL-Fragment. Verwenden Sie null oder einen leeren String für keine Benachrichtigung. Setzen Sie dies in einem Batch auf jede Abfrage, außerhalb von Params.  |

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

### Video und Audio

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Nein | "audio_video" | audio_video verbindet Video und Audio; Video wählt nur Video aus; Audio wählt nur Audio aus. Erlaubt: "audio_video", "video", "audio". Min. Länge: 1. Maximale Länge: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Nein | "<=720" | Auswahl der Videoauflösung. Weglassen für Audio-only Downloads. Zulässig: "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". Min. Länge: 1. Maximale Länge: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Nein | Nicht eingestellt | Frame-Rate-Einschränkung: >=, <= oder == gefolgt von einem Wert von 1 zu 240. Weglassen für Audio-only Downloads. Min. Länge: 1. Maximale Länge: 6. Muster: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Nein | "default" | Auswahl von Audiospuren. Gilt für audio_video und Audio. Erlaubt: "default", "original". Min. Länge: 1. Maximale Länge: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Nein | "best" | Nur Audio-Bitrate in kbps oder am besten. Numerische Entscheidungen müssen als Strings gesendet werden. Weglassen für Video-Downloads. Erlaubt: "best", "320", "256", "192", "128". Min. Länge: 1. Maximale Länge: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Nein | mp4 (video) / m4a (audio) | Video: mp4, webm oder mkv. Audio: m4a, mp3 oder opus. Erlaubt: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Min. Länge: 1. Maximale Länge: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Nein | Nicht eingestellt | Erweiterte Formatauswahl, von 1 zu 1,024 Zeichen nach dem Schneiden von Whitespace. Kontrollzeichen werden abgelehnt. Überschreibt video_quality, fps und audio_language, deren Werte dann ignoriert werden; Ausgabeformat und Clipping gelten weiterhin. Min. Länge: 1. Maximale Länge: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Nein | false | Laden Sie eine Metadaten-Datei JSON neben der Mediendatei in Ihrem Speicher hoch.  |

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

### Clipping

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Nein | Nicht eingestellt | Der Clip beginnt im H:MM:SS- oder HH:MM:SS-Format, von 00:00:00 bis 12:00:00. Standardmäßig 00:00:00, wenn nur end_at geliefert wird. Min. Länge: 1. Maximale Länge: 8. Muster: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Nein | Nicht eingestellt | Clip-Ende im Format H:MM:SS oder HH:MM:SS, bis 12:00:00. Muss später als start_at sein. Min. Länge: 1. Maximale Länge: 8. Muster: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Bestimmungsort der Lagerung

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Ja | — | Zielort für abgeschlossene Mediendateien. Es werden nur die aufgelisteten Speicherfelder akzeptiert.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Ja | — | Speicheranbieter: s3, s3_compatible, oss, gcs, azurblau, cos, bos oder tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Ja | — | Nicht leerer Bucket- oder Containername, bis zu 1,024-Zeichen. Der umgebende Whitespace wird entfernt. Verwenden Sie für s3 einen gültigen AWS-Bucket-Namen ohne URL oder Ordnerpfad; Ordner gehören zu object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Nein | "YYYYMMDD" | Objekt-Schlüssel-Präfix, 1 zu 512 Zeichen. Jedes slash-getrennte Segment akzeptiert ASCII-Buchstaben, Ziffern, Punkte, Unterstriche und Bindestriche; leere Segmente . und .. werden abgelehnt. Kein Lead Slash. Der umgebende Weißraum und ein nachlaufender Schrägstrich werden entfernt. YYYYMMDD verwendet das UTC-Uploaddatum, auch in archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Nein | — | Zugriffsschlüssel für S3, S3-kompatibel, OSS, COS, BOS oder TOS; gepaart mit secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Nein | — | Geheimschlüssel für S3, S3-kompatibel, OSS, COS, BOS oder TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Nein | — | Öffentlicher HTTPS-Endpunkt für S3-kompatiblen Speicher oder OSS. COS, BOS und TOS leiten sie aus der Region ab.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Nein | — | Erforderlich für COS, BOS und TOS; auch Lieferung für S3 und S3-kompatible Downloads. COS-Bucket-Namen enthalten die APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Nein | — | GCS Service Account: project_id, client_email und PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Nein | — | Azure Speicherkontoname. Verwenden Sie den Containernamen in storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Nein | — | Schreibaktivierter Azure Container SAS mit Ablauf und Signatur.  |

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

## Lesen Sie das Ergebnis

Nachdem der Job abgeschlossen ist, speichern Sie den JSON aus dem Ergebnislink als response.json. Speichern Sie dies als read-response.py und führen Sie Python read-response.py aus. Es liest Dateidetails, ohne Medien herunterzuladen oder eine andere Anfrage zu stellen.

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

## Vorlage der Stichprobe

Aufgezeichnetes Beispiel; Felder und Zählungen hängen von der Quelle und der angeforderten Eingabe ab.
```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"
    }
  ]
}
```

## Antwortfelder

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| id | string | Laden Sie den Job ID herunter. |
| source | string | youtube_download. |
| status | string | anhängig, wenn der Job angenommen wird. |
| created_at | string | Zeit für die Auftragserstellung im Format ISO 8601. |
| usage.credits | number | 0 bei Einreichung. Downloads werden nach dem gelieferten Datenvolumen nach Fertigstellung berechnet. |
| links | array | Folgen Sie dem Selbstlink für den Jobstatus und dem Ergebnislink für die abgeschlossene Ausgabe. |
| links[].rel | string | Selbst oder Ergebnisse. |
| links[].href | string | URL, um mit dem gleichen API-Schlüssel abzufragen. |
| links[].method | string | GET. |

- Downloads laufen als Hintergrundjobs. Die Submission Response enthält einen Job ID; sie enthält nicht die Mediendatei. Folgen Sie dem Jobstatus bis zum Abschluss und rufen Sie dann das Ergebnis ab, das die an Ihren Speicher gelieferten Dateien beschreibt. Senden Sie Downloads an /v1/queries oder /v1/queries/batch; /v1/queries/realtime akzeptiert keine Download-Anfragen.

## Antwortformate

Antworten verwenden standardmäßig JSON. Wählen Sie ein anderes Format mit diesen optionalen Headern.

- Accept: application/json (Ausfall) oder text/plain. Klartext präsentiert die gleichen Felder in einem lesbaren, eingerückten Layout.
- X-Respond-With: markdown. Lassen Sie unset für Originalfelder. Markdown funktioniert mit beiden Antwortformaten.

Markdown formatiert das Download-Manifest; Mediendateien behalten ihr ursprüngliches Format bei. Quittungen und Jobstatus unterstützen nur Accept.

Die folgenden Felder beschreiben die Standardantwort von JSON.

[Beispiele für das Anforderungs- und Antwortformat](https://flashdata.dev/de/docs/guides/response-formats/reference.md#completed-results)

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

## Bestimmungsort der Lagerung

Einzeljob- und Batch-Downloads erfordern params.storage; Bulk-Downloads verwenden options.storage. storage_url ist der Bucket- oder Containername. Geben Sie Anmeldeinformationen mit Schreibzugriff an und bewahren Sie sie auf Ihrem Server auf.

### s3

Liefern Sie access_key und secret_key mit Schreibzugriff. Legen Sie die Region auf die AWS-Region Ihres Buckets fest.

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

Liefern Sie access_key, secret_key und ein öffentliches HTTPS endpoint_url. Legen Sie die Region so fest, wie sie von Ihrem Provider benötigt wird; Cloudflare R2 verwendet 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

Liefern Sie account_name und sas_token, einen Container SAS mit Schreibberechtigung (sp enthält w), Ressource sr=c, Ablauf se, Version sv und Signatur sig. storage_url ist der Containername. Senden Sie keine endpoint_url, access_key oder 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

Liefern Sie access_key, secret_key und Region: bj, su oder hkg. Der Endpunkt wird aus der Region abgeleitet, wenn er weggelassen wird. Verwenden Sie einen Bucket-Namen ohne Punkte.

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

### cos

Liefern Sie access_key, secret_key und eine ap-*-Region wie ap-hongkong. storage_url muss das APPID-Suffix enthalten. Senden Sie kein endpoint_url; es wird aus der Region abgeleitet.

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

### gcs

Liefern Sie service_account mit project_id, client_email (eine .gserviceaccount.com-Adresse) und dem PEM private_key von Ihrem Servicekonto. Das Konto muss Schreibzugriff auf den Bucket haben. Senden Sie keine access_key, secret_key, Region oder 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

Liefern Sie access_key, secret_key und die öffentliche HTTPS endpoint_url der Bucket-Region.

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

Liefern Sie access_key, secret_key und Region mit einem cn-, ap-, eu- oder us-Präfix. Der Endpunkt wird aus der Region abgeleitet, wenn er weggelassen wird. Verwenden Sie einen Bucket-Namen ohne Punkte.

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

## API-Grundlagen

Der Request Builder und die obigen Beispiele verwenden die Parameter dieser Quelle. Verwenden Sie die Beispiele Python und cURL unten für gemeinsame Eingabe-, Status- und Ergebnisschritte. Ein Batch-Body ist ein JSON-Objekt, das Abfragen enthält; jedes Element gibt seinen eigenen Job ID zurück.

- [Async Anfrage und Empfang](https://flashdata.dev/de/docs/reference/realtime-and-async/reference.md#async)

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

- [Jobstatus überprüfen](https://flashdata.dev/de/docs/reference/realtime-and-async/reference.md#status)

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

- [Abrufen abgeschlossener Ergebnisse](https://flashdata.dev/de/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON Anfragen](https://flashdata.dev/de/docs/reference/batch-and-bulk/reference.md#batch)
- [API für Bulk-Verarbeitung](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md)
- [Erstellen Sie einen Bulk-Workflow für diese Quelle](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Kunden-OpenAPI](https://flashdata.dev/docs/openapi.json)

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

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

## Abschlussmeldungen

- [Empfangen und Verifizieren von Abschluss-Webhooks](https://flashdata.dev/de/docs/guides/async-batch/reference.md#webhooks)

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

## Fehlerbehebung

- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md#status-codes)
- [Wann man es erneut versucht](https://flashdata.dev/de/docs/errors/reference.md#retries)

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

## Aktenauslieferung

Download unterstützt keine Echtzeit.

Medien werden in Ihren konfigurierten Speicher hochgeladen; Ergebnis JSON beschreibt diese Dateien. Private Medien verwenden Ihre Speicherauthentifizierung. JSON Ergebnisse verfallen 24 Stunden nach Abschluss; Medien folgen Ihren Aufbewahrungsrichtlinien.

## Verwandte APIs

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