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

Anleitungen

YouTube Data Best Practices

Finden Sie relevante Videos, wählen Sie Untertitel-Tracks aus und verarbeiten Sie neue Kanal-Uploads, ohne die Arbeit zu wiederholen.

Auf dieser Seite

Beginnen Sie mit den Informationen, die Sie bereits haben

Jede Quelle beantwortet eine andere Frage. Überspringen Sie die Entdeckung für ein bekanntes Video ID oder Channel-Handle und bereichern Sie nur die Videos, die Ihre Aufgabe benötigt.

Ihre AufgabeQuelleBeschluss
Videos zu einem Thema findenyoutube_searchBeginnen Sie mit fünf Kandidaten und wählen Sie dann nach Relevanz aus.
Überprüfen Sie ein bekanntes Videoyoutube_metadataHolen Sie sich Titel, Kanal, Dauer und Beschriftungssprachen.
Zusammenfassen oder zitieren, was gesagt wurdeyoutube_transcript / youtube_captionsWählen Sie eine Sprache und eine automatische oder manuelle Spur.
Überprüfen Sie die letzten Channel Uploadsyoutube_channelVergleichen Sie zurückgegebenes IDs mit Ihrem verarbeiteten IDs.

Führen Sie die Request-Beispiele aus

Speichern Sie jeden JSON-Body mit dem angezeigten Dateinamen. Python verwendet den unten stehenden query.py-Helfer; cURL kann die gleiche Datei einreichen. Verwenden Sie einen Schlüssel mit den benötigten Quellberechtigungen und verfügbaren Credits. Jede Einreichung ist eine Abfrage, unabhängig von der Anzahl der zurückgegebenen Videos.

Python 3.10+. Installieren Sie Anforderungen einmal, speichern Sie query.py unten und verwenden Sie dann den Befehl neben jeder Anforderung. Bestehende Outputs werden wiederverwendet; geänderte Inputs erfordern einen neuen Output-Dateinamen.

Installieren
python -m pip install requests

Stellen Sie Ihren API-Schlüssel ein

Verwenden Sie FLASHDATA_API_KEY von Ihrem Terminal oder Secret Store. Andernfalls geben Sie den Schlüssel mit einer versteckten Eingabeaufforderung unten ein. Behalten Sie es in dem Prozess, in dem diese Beispiele ausgeführt werden.

Setzen Sie den Schlüssel
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

Speichern Sie query.py für die Beispiele von Python

Erstellen Sie query.py in einem neuen Arbeitsordner und kopieren Sie den vollständigen Code unten in ihn. Speichern Sie die Anforderung JSON Dateien und andere Python Skripte in diesem Ordner, und führen Sie alle Befehle von dort aus.

query.py
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))

Finden Sie Kandidaten, bevor Sie Details abrufen

Der Videofilter schließt andere Ergebnistypen aus; Untertitel verengt die Entdeckung auf Videos mit Beschriftungen. Es wählt keine Untertitelsprache aus oder garantiert den benötigten Track. Speichern Sie als discover-request.json.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Einmalig einreichen mit query.py
python query.py discover-request.json search.json

Wählen Sie nach Relevanz, nicht nach dem ersten ID

Speichern Sie candidates.py neben query.py und search.json und führen Sie es dann aus diesem Ordner aus. Es behält die Suchreihenfolge und entfernt doppeltes Video IDs. Überprüfen Sie Titel, Kanäle und Dauer und kopieren Sie dann eine ausgewählte ID in die nächste Anforderung. Eine leere Liste ist eine abgeschlossene Suche ohne Kandidaten.

candidates.py
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
Lesen Sie die gespeicherte Suche
python candidates.py

Erweitern Sie nur, wenn die Shortlist unzureichend ist

Standard Search unterstützt max_results bis 20. Wechseln Sie für eine breitere Sammlung zu youtube_search_extended, das bis zu 700 unterstützt und separate Preise hat. In diesem Beispiel wird nach 50 gefragt; Überprüfen Sie, ob Ihre ersten Ergebnisse nützlich sind, bevor Sie sie alle anreichern.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Einmal laufen
python query.py extended-request.json extended.json

Suchen Sie nur die Metadaten ab, die Ihr Feature benötigt

Ersetzen Sie das Beispiel video_id durch das ausgewählte ID. Halten Sie Formate und Kapitel für eine einfache Überprüfung der Grafikkarte oder der Beschriftungssprache deaktiviert. Aktivieren Sie include_chapters für eine Gliederung oder include_formats bei der Auswahl eines Medienformats.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Einmalig einreichen mit query.py
python query.py metadata-request.json metadata.json

Verfügbare Sprachen prüfen

Lesen Sie Ergebnisse[0].transcriptLanguages, bevor Sie Untertitel auswählen. Formate, Kapitel und Sprachen sind Felder auf dem zurückgegebenen Videoobjekt; der Nutzungssatz gehört zur äußeren Antwort.

EinstellungVerwenden Sie es für
languageEin Code von transcriptLanguages, wie en oder zh-Hans. Diese Liste unterscheidet nicht manuelle und automatische Spuren.
auto: trueEine vorhandene automatisch generierte Spur.
auto: falseEin vorhandenes manuell bereitgestelltes Gleis. Es gibt keinen Rückfall zwischen den beiden Streckentypen.
Lesen Sie metadata.json · keine Abfrage
python -m json.tool metadata.json

Wählen Sie Sprache und Track explizit

Verwenden Sie die gleiche video_id wie Ihre Metadatenanforderung und ändern Sie Sprache und Auto, um die gewählte Spur zu entsprechen. youtube_transcript ist standardmäßig auto: true; youtube_captions ist standardmäßig auto: false. Beide rufen vorhandene Beschriftungen ab, nicht Speech-to-Text.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Einmalig einreichen mit query.py
python query.py captions-request.json captions.json

Halten Sie den Zeitstempel mit den Beweisen

Speichern Sie cite-segments.py neben captions.json und führen Sie es aus diesem Ordner aus. Verwenden Sie Ergebnisse[0].segmente für Zitate: Anfang und Ende sind Sekunden. languageCode und isAutoGenerated mit dem Text bewahren. fullText ist nützlich zum Lesen, ersetzt aber nicht das Segment-Timing. Wenn der gewählte Track fehlt, notieren Sie die Lücke, bevor Sie entscheiden, ob sich eine weitere Abfrage lohnt.

cite-segments.py
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
Lesen Sie gespeicherte Bildunterschriften · kein API-Aufruf
python cite-segments.py

Verarbeiten Sie nur neue Videos von einem bekannten Kanal

Verwenden Sie einen Channel-Handle und einen begrenzten video_limit (1–100). results[0].videos ist die zurückgegebene aktuelle Liste; videoCount sind Kanalmetadaten, nicht die Anzahl der zurückgegebenen Elemente. Wählen Sie ein Limit und einen Zeitplan, der die Uploads abdeckt, die Sie beachten müssen.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Einmalig einreichen mit query.py
python query.py channel-request.json channel.json

Halten Sie eine Warteschlange und einen Abschluss-Checkpoint

Speichern Sie channel-queue.py neben query.py und channel.json und führen Sie es aus diesem Ordner aus. Führen Sie ohne Argumente aus, um new-ids.json zu erstellen, und verarbeiten und speichern Sie dann Beweise für diese IDs. Führen Sie --commit erst aus, nachdem jede Warteschlange ID erfolgreich war; ein Fehler lässt den Checkpoint unverändert. Verwenden Sie ein Verzeichnis pro Kanal und einen Worker für dieses Beispiel.

channel-queue.py
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
Planen → Prozess → Commit
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Starten Sie einen neuen Kanal-Check absichtlich

Der Abfragehelfer verwendet eine gespeicherte Antwort wieder. Verwenden Sie für die nächste geplante Überprüfung einen neuen Ergebnisdateinamen, inspizieren Sie ihn und kopieren Sie dann die Antwort auf channel.json für den Warteschlangenschritt. Halten Sie processed-ids.json zwischen den Läufen. Diese aktuelle Liste ist kein Full-Channel-Export oder ein Event-Stream.

Nächster Check · Wählen Sie einen frischen Dateinamen
python query.py channel-request.json channel-next.json
Nachdem der Status bestätigt wurde
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Verwenden Sie Vorschläge zur Verbesserung der Abfrage

Vorschläge geben Phrasen in Ergebnissen zurück[0], keine Videoaufzeichnungen. Wählen Sie eine nützliche Phrase aus und erstellen Sie eine separate youtube_search-Anforderung. Legen Sie die Sprache und Region für das Publikum fest, das Sie recherchieren.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Einmalig einreichen mit query.py
python query.py suggestions-request.json suggestions.json

Lizenzetiketten speichern, ohne sie als Erlaubnis zu behandeln

youtube_trainability gibt ein Lizenz-Label für ein Video zurück. erlaubt: ["all"] bildet Creative Commons ab; ["none"] deckt auch fehlende Lizenz-Metadaten ab. Behalten Sie das Video ID, die Quellantwort und das Abrufdatum. Dieses Label gewährt keine Download-, Wiederverwendungs- oder Schulungsrechte.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Einmalig einreichen mit query.py
python query.py license-request.json license.json

Die Arbeit für Apps und Agenten binden

RegelDurchführung
Wählen Sie vor der AnreicherungFür eine Themenaufgabe: eine Suche, eine ausgewählte Video-Metadaten und eine ausgewählte Bildunterschrift. Erzwingen Sie das Anrufbudget in Ihrer App und bewerten Sie jede Quelle separat.
Wiederverwendung durch den tatsächlichen InputMetadaten: Video ID + Optionen. Bildunterschriften: Video ID + Sprache + Track. Channel Snapshots benötigen auch eine Abrufzeit oder führen ID aus.
Stoppen Sie fehlende BeweiseProbieren Sie kein leeres Discovery-Ergebnis erneut aus oder wechseln Sie die Untertitelspuren leise. Geben Sie die Lücke zurück, damit der Benutzer oder Workflow die nächste Aktion auswählen kann.
Nutzung und gescheiterte Arbeit erhaltenSpeichern Sie die Nutzung mit erfolgreichen Antworten. Auf 429, ehren Retry-After; nach einer unsicheren Einreichung, überprüfen Sie History vor einer anderen bezahlten Abfrage.