# Abrufen der Metadaten eines Videos

Verwandeln Sie ein YouTube-Video ID in einen gespeicherten Datensatz über Titel, Kanal, Dauer und verfügbare Anzahl. Behalten Sie die ursprüngliche Antwort und Nutzung neben sich.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/video-metadata-recipe
Test: 2026-11-05 von FlashData

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

## Bevor Sie anfangen

Verwenden Sie einen Schlüssel mit youtube_metadata-Berechtigung und verfügbaren Credits. Wählen Sie Python 3.10+ mit Anfragen oder Bash mit cURL 7.76+ und jq. Verwenden Sie unter Windows Git Bash für die Bash-Version.

- [API-Schlüssel erstellen](https://flashdata.dev/app/api-keys)
- [Agententest und Kontoverknüpfung](https://flashdata.dev/de/docs/guides/agent-onboarding/reference.md)
- [Credits und Preise](https://flashdata.dev/de/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 1. Wählen Sie ein Video

Erstellen Sie einen Video-Metadaten-Ordner und speichern Sie dort request.json. Öffnen Sie ein Terminal in diesem Ordner. Ersetzen Sie video_id durch das 11-Zeichen ID von einer Uhr URL oder einem YouTube Search-Ergebnis; geben Sie das vollständige URL nicht weiter.

Legen Sie beide optionalen Flags explizit fest: Diese erste Anforderung lässt Medienformate und Kapitel aus. Es ruft Metadaten ab, ohne das Video oder seine Bildunterschriften herunterzuladen.

### video-metadata/request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```


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

## 2. Abrufen und Speichern der Metadaten

Wählen Sie eine Version und speichern Sie das Skript neben request.json. Es liest FLASHDATA_API_KEY oder fragt nach Ihrem Schlüssel in einer versteckten Eingabeaufforderung. Agenten sollten diese Umgebungsvariable aus ihrem geheimen Speicher laden.

Führen Sie mit Snapshot-001 als Ausgabeordner aus. Ein neuer Ordner sendet eine Metadatenabfrage und speichert die gemeldete Nutzung. Das Skript prüft auf eine erfolgreiche Antwort, die genau ein Video mit dem angeforderten ID enthält, bevor Sie video.json schreiben.

### Python

#### Installieren Sie in Ihrer Python-Umgebung

```bash
python -m pip install requests
```

#### video-metadata/metadata.py

```python
import argparse
import getpass
import json
import os
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved snapshot")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_metadata"
            or not isinstance(request.get("video_id"), str)
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])):
        raise SystemExit("Use youtube_metadata and an 11-character video_id, not a URL")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
try:
    data = json.loads((out / "result.json").read_bytes())
except ValueError:
    raise SystemExit("Invalid JSON; inspect the saved result.json")
request = json.loads((out / "request.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_metadata" or data.get("status") != "done":
    raise SystemExit("Metadata request did not finish successfully; inspect result.json")
videos = data.get("results")
if (not isinstance(videos, list) or len(videos) != 1 or not isinstance(videos[0], dict)
        or videos[0].get("videoId") != request["video_id"]):
    raise SystemExit("Expected one metadata object matching the requested video_id")
record = {
    "request": request,
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "result_file": "result.json",
}
for filename, value in (("video.json", videos[0]), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {videos[0]['videoId']} to {out}/video.json")
```

#### Laufen Sie von Video-Metadaten /

```bash
python metadata.py snapshot-001
```


### Bash

#### Überprüfen Sie Ihre Tools

```bash
curl --version
jq --version
```

#### video-metadata/metadata.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash metadata.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_metadata" and
    (.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$")
     else false end)' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
video=$(jq -e --slurpfile request "$out/request.json" '
  if .source != "youtube_metadata" or .status != "done"
  then error("Expected a successful youtube_metadata response") else . end
  | .results
  | if type != "array" then error("Expected a metadata array")
    elif length != 1 then error("Expected exactly one video") else .[0] end
  | if type != "object" then error("Expected a metadata object")
    elif .videoId != $request[0].video_id then error("Returned videoId does not match the request")
    else . end' "$out/result.json")
printf '%s\n' "$video" > "$out/video.json"
jq --slurpfile request "$out/request.json" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage, result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s to %s/video.json\n' "$(jq -r .videoId "$out/video.json")" "$out"
```

#### Laufen Sie von Video-Metadaten /

```bash
bash metadata.sh snapshot-001
```



<a id="output"></a>

## 3. Lesen Sie die Videoaufzeichnung

Erfolgsdrucke Gespeichert <video ID> zu snapshot-001/video.json. Lesen Sie diese Datei für das vollständige Metadatenobjekt und record.json für die genau eingereichte Anforderung, requested_at und Nutzung. Das Lesen dieser Dateien führt zu keinem API-Aufruf.

### Python

#### Vor Ort lesen

```bash
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json
```


### Bash

#### Vor Ort lesen

```bash
cat snapshot-001/video.json
cat snapshot-001/record.json
```



<a id="expected"></a>

### Beispielausgabe

Abgekürzt, illustrativ video.json. Die zurückgegebenen Werte variieren. Das Skript bewahrt jedes verfügbare Feld, einschließlich der null-Werte, und behält die vollständige Antwort in result.json.

#### video-metadata/snapshot-001/video.json

```json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}
```


<a id="fields"></a>

### Lesen Sie die Felder

| Feld | Verwenden Sie es für |
| --- | --- |
| videoId | Der stabile Schlüssel des Rekords. Titel- und Kanalanzeigenamen können sich ändern. |
| duration | Videolänge in Sekunden. Fehlende oder null-Werte als unbekannt beibehalten. |
| viewCount / likeCount / commentCount | Zählt in diesem Snapshot verfügbar. Null oder fehlende ist unbekannt; Null ist eine gemeldete Zählung. |
| transcriptLanguages | Kandidatensprachcodes für eine separate Beschriftungsanforderung. In dieser Liste wird nicht angegeben, ob ein Gleis automatisch oder manuell ist. |


<a id="reuse"></a>

## Verwenden Sie den Snapshot erneut oder fordern Sie einen anderen an

Führen Sie den gleichen Befehl aus, um video.json und record.json aus der gespeicherten Antwort neu zu erstellen. Es ist keine Schlüssel- oder Netzwerkanforderung erforderlich. Durch das Bearbeiten der obersten Ebene request.json wird die mit Snapshot-001 gespeicherte Eingabe nicht geändert.

### Python

#### Gespeicherte Daten wiederverwenden

```bash
python metadata.py snapshot-001
```


### Bash

#### Gespeicherte Daten wiederverwenden

```bash
bash metadata.sh snapshot-001
```


- [Ergebnisse speichern und wiederverwenden](https://flashdata.dev/de/docs/guides/save-results/reference.md)

<a id="chapters"></a>

### Verfügbare Kapitel einfügen

Um Kapitelmarkierungen einzuschließen, ersetzen Sie request.json durch diese Version und verwenden Sie einen neuen Ausgabeordner. include_chapters: true gibt Kapitel zurück, wenn verfügbar; es erstellt sie nicht. Sowohl include_chapters als auch include_formats sind standardmäßig true, wenn sie weggelassen werden.

#### video-metadata/request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": true
  }
}
```

#### Python

##### Einen weiteren Snapshot anfordern

```bash
python metadata.py snapshot-002
```


#### Bash

##### Einen weiteren Snapshot anfordern

```bash
bash metadata.sh snapshot-002
```


- [Metadatenfelder und Optionen](https://flashdata.dev/de/docs/sources/youtube_metadata/reference.md)

<a id="recover"></a>

## Wenn Metadaten nicht verfügbar sind

| Was passierte | Lösung |
| --- | --- |
| Ungültiges video_id | Verwenden Sie nur das 11-Zeichen ID. Die Eingabevalidierung wird vor dem Senden der Anforderung beendet. |
| Privates, entferntes oder eingeschränktes Video | Behalten Sie den Fehler für diesen ID. Überprüfen Sie den Quellfehler und wählen Sie ein zugängliches Video aus, anstatt wiederholt dasselbe Element einzureichen. |
| Leeres Ergebnis oder ein anderes videoId | Das Skript stoppt, ohne video.json zu schreiben. Überprüfen Sie die gespeicherte Anfrage und Antwort, bevor Sie den Datensatz verwenden. |
| Fehlende Zählungen, Kapitel oder Sprachen | Ein passender Metadatensatz kann dennoch erfolgreich sein. Bewahren Sie nicht verfügbare Felder als unbekannt auf; füllen Sie sie nicht mit erfundenen Werten. |
| 401 / 403 / 402 | Überprüfen Sie den Schlüssel, youtube_metadata Berechtigung und Balance, jeweils vor einem neuen Versuch. |
| 429 | Lesen Sie Retry-After in response-headers.txt und warten Sie. Das Skript wird nie automatisch wiederholt. |
| Timeout, 5xx, ungültiges JSON oder ein unvollständiger Ordner | Halten Sie den Versuch und überprüfen Sie History, bevor Sie erneut einreichen. Die Wiederverwendung seines Ordners macht keine neue Anforderung. |

### Python

Speichern Sie inspect_metadata.py neben metadata.py und führen Sie es aus.

#### video-metadata/inspect_metadata.py

```python
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("snapshot-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
```

#### Lokale Kontrolle

```bash
python inspect_metadata.py
```


### Bash

#### Lokale Kontrolle

```bash
for name in http-status.txt response-headers.txt result.json; do
  printf '\n--- %s ---\n' "$name"
  if [[ -f "snapshot-001/$name" ]]; then cat "snapshot-001/$name"; else printf 'Not saved\n'; fi
done
```


- [Anfrageverlauf](https://flashdata.dev/app/jobs)
- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md)

<a id="next"></a>

## Verwenden Sie das Video in Ihrem Workflow

Verwenden Sie videoId, um diesen Datensatz mit Ihren Suchergebnissen oder Datensätzen zu verbinden. Für gesprochene Inhalte, rufen Sie eine bestimmte Untertitel-Track als nächstes. Verwenden Sie für mehrere IDs die Anreicherungsanleitung. Dies sind separate Anfragen mit eigenen Berechtigungen und Gebühren.

- [Abrufen von Zeitstempel-Beschriftungen](https://flashdata.dev/de/docs/guides/timestamped-captions-recipe/reference.md)
- [Anreichern ausgewähltes Video IDs](https://flashdata.dev/de/docs/guides/enrich-youtube-videos/reference.md)
