Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Beispiele

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.

Auf dieser Seite

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.

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
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}

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.

Installieren Sie in Ihrer Python-Umgebung
python -m pip install requests
video-metadata/metadata.py
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 /
python metadata.py snapshot-001

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.

Vor Ort lesen
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json

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
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}

Lesen Sie die Felder

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

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.

Gespeicherte Daten wiederverwenden
python metadata.py snapshot-001

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
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": true
  }
}
Einen weiteren Snapshot anfordern
python metadata.py snapshot-002

Wenn Metadaten nicht verfügbar sind

Was passierteLösung
Ungültiges video_idVerwenden Sie nur das 11-Zeichen ID. Die Eingabevalidierung wird vor dem Senden der Anforderung beendet.
Privates, entferntes oder eingeschränktes VideoBehalten 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 videoIdDas 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 SprachenEin 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.
429Lesen 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 OrdnerHalten Sie den Versuch und überprüfen Sie History, bevor Sie erneut einreichen. Die Wiederverwendung seines Ordners macht keine neue Anforderung.

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

video-metadata/inspect_metadata.py
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
python inspect_metadata.py

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.