# YouTube Download Best Practices

Wählen Sie die richtige Medienausgabe, steuern Sie, was Sie herunterladen, und verwandeln Sie einen abgeschlossenen Auftrag in eine nutzbare private Datei.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/youtube-download-guide
Test: 2026-11-04 von FlashData

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

## Beginnen Sie mit dem, was Ihre Aufgabe braucht

| Dein Ziel | Verwendung |
| --- | --- |
| Zusammenfassung gesprochener Inhalte oder Aufbau eines Textindex | Lesen Sie zuerst ein vorhandenes Transkript. Laden Sie Audio nur dann herunter, wenn Ihr Workflow das Audio selbst benötigt, z. B. einen separaten Sprach-zu-Text-Schritt. |
| Prozesssprache oder Audio | Nur Audio-Ausgabe. Vermeiden Sie das Tragen eines Videotracks, den Ihre Anwendung nicht verwendet. |
| Zeigen Sie einen kurzen Auszug | Setzen Sie start_at und end_at. Überprüfen Sie, ob beide innerhalb der Dauer des Quellvideos liegen. |
| Abspielen oder Verarbeiten von Videos | MP4 mit Audio und einer Auflösungskappe, die für Ihre Anwendung geeignet ist; das Beispiel verwendet <=720. |

- [Zusammenfassungen von Bildunterschriften](https://flashdata.dev/de/docs/guides/youtube-summary/reference.md)
- [Video-Metadaten prüfen](https://flashdata.dev/de/docs/guides/youtube-data-guide/reference.md#metadata)

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

## Speichern Sie den Output, den Sie wollen

Wählen Sie eine Registerkarte und speichern Sie die gesamte Anforderung als download-request.json. Ändern Sie video_id für Ihre Quelle. Die unten aufgeführten Eingabebefehle lesen diese Datei, so dass die Auswahl von Audio oder einem Clip die tatsächliche Anforderung ändert.

### MP4 / 720p

Ein komplettes Video mit Audio, begrenzt auf 720p.

#### download-request.json

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


### MP3

Eine Audiodatei zum Abhören oder zur weiteren Audioverarbeitung.

#### download-request.json

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


### 5 zweiter Clip

Ein MP4-Auszug von 00:00:05 zu 00:00:10. Verwenden Sie Zeiten, die zu Ihrem ausgewählten Video passen.

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


- [Alle Formatoptionen](https://flashdata.dev/de/docs/sources/youtube_download/reference.md#parameters)

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

## Überprüfen Sie den Besitzerzugriff und die bytebasierte Preisgestaltung

Verwenden Sie Bash und jq sowie ein gespeichertes CLI-Profil oder FLASHDATA_API_KEY für HTTP. Der Schlüssel benötigt die youtube_download-Berechtigung. Der Download erfordert den Zugriff des Besitzers; der temporäre Testzugriff beinhaltet ihn nicht. CLI-Beispiele verwenden Ihr Standardprofil; fügen Sie --profile-NAME zu jedem Befehl hinzu, wenn Ihr Befehl benannt ist.

| Beschluss | Wenden Sie es so an |
| --- | --- |
| Kostenschätzung | Verwenden Sie die zurückgegebenen creditsPerTb und bytesPerUnit mit Ihren geschätzten Ausgabebytes. Der Downloadpreis ist keine feste Gebühr pro Anfrage. |
| Kontrollumfang | Wählen Sie Audio, einen Clip oder eine Auflösungskappe vor dem Einreichen. Bewerben Sie Job-Count und Ausgabenregeln in Ihrer Anwendung. |
| Aufzeichnen des tatsächlichen Ladevorgangs | Lesen Sie die Verwendung aus der abgeschlossenen Lieferung. Der Eintritt kann Credits vor dem Upload enthalten; Der aktuelle Saldo ist keine Ausgabenobergrenze pro Job. |

### Kostenlose Schecks · CLI

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

- [Besitzerschlüssel-Setup](https://flashdata.dev/de/docs/guides/api-keys-and-permissions/reference.md)
- [HTTP Balance und Preisgestaltung](https://flashdata.dev/de/docs/guides/credits-and-billing/reference.md#balance)

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

## Verwenden Sie ein privates Ziel für jede Ausgabe

Speichern Sie storage.json privat mit Ihren realen Zielwerten. Halten Sie es außerhalb der Kontrolle der Quelle. Verwenden Sie für jede video/output-Version eine eindeutige object_prefix; die Wiederverwendung eines Präfixes für verschiedene Ausgänge macht es schwieriger, Anwendungsdatensätze zu vereinbaren.

| Nachweise | Zweck |
| --- | --- |
| FlashData Schlüssel | Senden Sie den Download und lesen Sie seine Aufgabe und Lieferung JSON. |
| Storage Upload Credential | Schreibe Medien auf den beabsichtigten Bucket und das Präfix. |
| Identität des Anwendungsspeichers | Lesen Sie das private Objekt oder geben Sie Zugriff auf einen autorisierten Benutzer. |

### 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 · private Datei

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

- [Windows Dateiberechtigungen](https://flashdata.dev/de/docs/guides/cli-automation/reference.md#storage)
- [Sonstige Speicheranbieter](https://flashdata.dev/de/docs/sources/youtube_download/reference.md#storage)

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

## Senden Sie die gespeicherte Anfrage einmal

Führen Sie einen Tab aus, nachdem Sie beide Dateien gespeichert haben. Der Befehl injiziert storage.json durch stdin und speichert download-submission.json. Behalten Sie diese Quittung. Mit CLI behalten Sie den gleichen Lauf ID für eine Wiederholung bei; Verwenden Sie einen neuen ID nur für eine absichtliche neue Ausgabe. HTTP-Einreichungen verwenden nicht das lokale Laufjournal des CLI.

### CLI

#### Senden Sie den gewählten Output

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

#### Senden Sie den gewählten Output

```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 Anfrage Vertrag](https://flashdata.dev/de/docs/reference/realtime-and-async/reference.md#async)

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

### Validieren Sie zuerst mit dem CLI

Erwarten Sie ok: true und data.dryRun: true. Dies überprüft die Eingabe und den FlashData-Zugriff, ohne einen Job einzureichen; es beweist nicht, dass die Upload-Anmeldeinformationen in Ihren Bucket schreiben können.

#### Freier Trockenlauf

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

### Warten Sie auf den bestehenden Job

Der Einreichungsbeleg ist nicht die Mediendatei. CLI wartet; der Befehl HTTP liest den Status einmal. Wiederholen Sie das Lesen innerhalb Ihrer Frist, bis es abgeschlossen oder fehlgeschlagen ist. Ein lokales Timeout storniert den Serverjob nicht.

#### CLI

##### Warten Sie auf den gespeicherten Job

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


#### HTTP / cURL

##### Status einmal lesen

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

## Lesen Sie die Lieferaufzeichnung, dann auf die Medien zugreifen

Nach Abschluss rufen Sie delivery.json mit dem gleichen Pfad ab, den Sie gesendet haben. Das signierte Ergebnis URL ruft JSON; results[0].file_url identifiziert das Medium in Ihrem Speicher. Ein privater file_url benötigt Ihre Speicherdatenidentität oder einen Link, der von Ihrer Anwendung ausgegeben wurde.

### CLI

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

#### Fetch-Lieferung JSON · Halten Sie die API-Taste von Speicheranforderungen fern

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

### Überprüfen Sie, was geliefert wurde

Erwarten Sie einen Dateispeicherort, ein positives file_size, ein MD5 und Nutzung. Zeichnen Sie file_size für das gelieferte Objekt auf; downloaded_bytes ist ein Übertragungsfeld, kein Ersatz für die endgültige Ladung in der Verwendung.

#### delivery.json prüfen

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

- [Verifizieren und bedienen Sie ein privates Objekt](https://flashdata.dev/de/docs/guides/media-delivery-pipeline/reference.md#verify)

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

### Überprüfen Sie eine lokale Kopie von S3

Setzen Sie OBJECT_KEY auf den gelieferten Medienschlüssel von file_url, einschließlich seines Präfixes. Verwenden Sie AWS CLI mit Lesezugriff, jq und OpenSSL. Dies speichert media.mp4 oder media.mp3 entsprechend Ihrer gewählten Anforderung und überprüft deren Größe und Prüfsumme, ohne eine vorhandene lokale Datei zu überschreiben.

#### S3 read · keine neue FlashData-Abfrage

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

- [Ergebnisspeicherung und gespeicherte Medien](https://flashdata.dev/de/docs/guides/save-results/reference.md#media)

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

## Wiederherstellen von der Phase, die fehlgeschlagen ist

| Was passierte | Nächste Maßnahme |
| --- | --- |
| Einreichung ohne bestätigten Job ID | Überprüfen Sie den gespeicherten CLI-Lauf oder die Anforderungshistorie. Behalten Sie die ursprüngliche Eingabe und senden Sie nicht automatisch erneut. |
| Job angenommen; Warten auszeitig | Lesen oder Wiederherstellen des gleichen Jobs. Erstellen Sie keinen weiteren Download, um weiter zu warten. |
| Upload fehlgeschlagen | Lesen Sie den Jobfehler und beheben Sie die Zieleinstellungen oder schreiben Sie den Zugriff, bevor Sie es absichtlich erneut versuchen. |
| Medien lesen zurück 403Q | Überprüfen Sie die Speicherleseberechtigungen oder den von der Anwendung herausgegebenen Link. Der FlashData API-Schlüssel entsperrt S3 nicht. |
| Signiertes Ergebnis JSON abgelaufen | Lesen Sie den Jobergebnis-Endpunkt erneut, während das Ergebnis beibehalten wird. Gespeicherte Medien folgen dem Lebenszyklus Ihres Buckets. |

### CLI · Überprüfen Sie den gespeicherten Lauf

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

- [Rückforderungsentscheidungen](https://flashdata.dev/de/docs/guides/agent-recovery/reference.md)
- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md)
- [Wiederkehrende Aufgaben](https://flashdata.dev/de/docs/guides/recurring-tasks/reference.md)

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

## Geben Sie Ihrem Agenten die Output- und Lieferkriterien

### Agent-Aufgabe · Geben Sie das Video, das Ziel und das Budget an

```text
Verwenden Sie den Zugriff meines gespeicherten Besitzers und konfigurieren Sie den privaten Speicherplatz.
Lesen Sie download-request.json für das Video und die Ausgabe; ändern Sie sie nicht leise.
Überprüfen Sie die Download-Preise und verfügbaren Credits für das genehmigte Aufgabenbudget.
Einmal einreichen, speichern Sie den run/job ID und lesen Sie diesen Job dann bis zum Abschluss.
Speichern Sie den Lieferdatensatz. Überprüfen Sie die Größe des gespeicherten Objekts und MD5, bevor Sie es verarbeiten.
Geben Sie den Objektstandort, das gewählte Format, das Verifizierungsergebnis und die tatsächliche Nutzung an.
Wenn die Übermittlung unsicher ist, prüfen Sie die gespeicherte Arbeit; erstellen Sie keinen Ersatzzugriff oder einen anderen Download.
Speicheranmeldeinformationen privat halten. Teilen Sie Medien nur über die konfigurierten Zugriffssteuerungen der Anwendung.
```

- [Erstellen Sie die Application Pipeline](https://flashdata.dev/de/docs/guides/media-delivery-pipeline/reference.md)
