Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

YouTube Data beste praktijken

Vind relevante video's, selecteer bijschriften en verwerk nieuwe kanaaluploads zonder werk te herhalen.

Op deze pagina

Begin met de informatie die je al hebt

Elke bron beantwoordt een andere vraag. Skip ontdekking voor een bekende video ID of kanaal handvat, en verrijken alleen de video's die je taak nodig heeft.

Uw taakBronBesluit
Video's over een onderwerp zoekenyoutube_searchBegin met vijf kandidaten, selecteer dan door relevantie.
Een bekende video bekijkenyoutube_metadataKrijg titel, kanaal, duur en bijschrift talen.
Samenvatting of citeer wat er gezegd werdyoutube_transcript / youtube_captionsKies een taal en een automatisch of handmatig spoor.
Controleer recente kanaaluploadsyoutube_channelVergelijk geretourneerde IDs met uw verwerkte IDs.

Uitvoeren van de verzoek voorbeelden

Sla elke JSON body op met de weergegeven bestandsnaam. Python gebruikt de query.py helper hieronder; cURL kan hetzelfde bestand indienen. Gebruik een sleutel met de bronrechten die u nodig hebt en beschikbare credits. Elke inzending is één vraag, ongeacht het aantal geretourneerde video's.

Python 3.10+. Installeer verzoeken eenmaal, sla query.py hieronder op en gebruik vervolgens het commando naast elk verzoek. Bestaande outputs worden hergebruikt; gewijzigde invoer vereist een nieuwe uitvoer bestandsnaam.

Installeren
python -m pip install requests

Stel uw API-sleutel in

Hergebruik FLASHDATA_API_KEY vanuit uw terminal of geheime winkel. Anders voer de sleutel in met behulp van een verborgen prompt hieronder. Houd het in het proces draaien van deze voorbeelden.

De sleutel instellen
# 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

Bewaar query.py voor de Python voorbeelden

Maak query.py in een nieuwe werkmap en kopieer de volledige code hieronder erin. Sla de aanvraag JSON bestanden en andere Python scripts in deze map op, en voer alle commando's vanaf daar uit.

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

Zoek kandidaten voordat details worden opgehaald

Het videofilter sluit andere resultaattypes uit; ondertitels vernauwen de ontdekking tot video's met bijschriften. Het selecteert geen bijschrifttaal of garandeert de track die u nodig heeft. Opslaan als discover-request.json.

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

Selecteer door relevantie, niet de eerste ID

Bewaar candidates.py naast query.py en search.json, voer het vervolgens uit vanuit die map. Het houdt zoekopdracht orde en verwijdert dubbele video IDs. Inspecteer titels, kanalen en duur, kopieer vervolgens een geselecteerde ID naar het volgende verzoek. Een lege lijst is een voltooide zoekopdracht zonder 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))
Lees de opgeslagen zoekopdracht
python candidates.py

Alleen uitvouwen als de shortlist onvoldoende is

Standard Search ondersteunt max_results tot 20. Voor een bredere collectie, schakel naar youtube_search_extended, die tot 700 ondersteunt en aparte prijzen heeft. Dit voorbeeld vraagt om 50; controleer of uw eerste resultaten nuttig zijn voordat u ze allemaal verrijkt.

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

Alleen de metadata ophalen die uw functie nodig heeft

Vervang het monster video_id door de geselecteerde ID. Houd formaten en hoofdstukken uitgeschakeld voor een eenvoudige videokaart of bijschrift-taalcontrole. Schakel include_chapters in voor een overzicht, of include_formats bij het kiezen van een mediaformaat.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Eenmaal indienen met query.py
python query.py metadata-request.json metadata.json

Beschikbare talen inspecteren

Lees resultaten[0].transcriptLanguages voordat u bijschriften kiest. Formaten, hoofdstukken en talen zijn velden op het geretourneerde video-object; het gebruiksrecord behoort tot de externe respons.

InstellingenGebruik het voor
languageEen code van transcriptLanguages, zoals en of zh-Hans. Deze lijst onderscheidt geen handmatige en automatische tracks.
auto: trueEen bestaande automatisch gegenereerde track.
auto: falseEen bestaande handmatig geleverde track. Er is geen terugval tussen de twee track types.
Lees metadata.json · geen query
python -m json.tool metadata.json

Kies de taal en track expliciet

Gebruik dezelfde video_id als uw metadataverzoek en verander de taal en auto om de gekozen track aan te passen. youtube_transcript standaard auto: true; youtube_captions standaard auto: false. Beiden halen bestaande bijschriften op, niet spraak-tekst.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Eenmaal indienen met query.py
python query.py captions-request.json captions.json

Houd het tijdstempel bij het bewijs

Bewaar cite-segments.py naast captions.json en voer het uit vanuit die map. Resultaten gebruiken[0].segmenten voor aanhalingstekens: begin en einde zijn seconden. Behoud languageCode en isAutoGenerated met de tekst. fullText is nuttig voor het lezen, maar vervangt geen segment timing. Als de gekozen track ontbreekt, registreert u de kloof voordat u beslist of een andere query de moeite waard is.

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)
Opgeslagen bijschriften lezen · geen API-oproep
python cite-segments.py

Bezig met het verwerken van alleen nieuwe video's van een bekend kanaal

Gebruik een kanaal handvat en een begrensd video_limit (1–100). resultaten[0].videos is de teruggekeerde recente lijst; videoCount is kanaalmetadata, niet het aantal geretourneerde items. Kies een limiet en schema die de uploads die u moet observeren dekken.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Eenmaal indienen met query.py
python query.py channel-request.json channel.json

Houd een wachtrij en een controlepunt voor voltooiing

Bewaar channel-queue.py naast query.py en channel.json, en voer het uit vanuit die map. Uitvoeren zonder argumenten om new-ids.json te maken, dan verwerken en opslaan bewijs voor die IDs. Start --commit alleen nadat elke ID in de wachtrij is geslaagd; een fout laat het controlepunt ongewijzigd. Gebruik één directory per kanaal en één werknemer voor dit voorbeeld.

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))
Plan → proces → commit
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Een nieuwe kanaalcontrole doelbewust starten

De query helper gebruikt een opgeslagen antwoord. Voor de volgende geplande controle, gebruik een nieuwe resultaat bestandsnaam, inspecteer het, dan kopieer dat voltooide antwoord op channel.json voor de wachtrij stap. Houd processed-ids.json tussen de runs. Deze recente lijst is geen full-channel export of een eventstream.

Volgende vink · kies een nieuwe bestandsnaam
python query.py channel-request.json channel-next.json
Na het bevestigen van de status is voltooid
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"

Gebruik suggesties om de zoekopdracht te verbeteren

Suggesties geven zinnen terug in resultaten[0], geen videorecords. Selecteer een handige zin en maak een aparte youtube_search verzoek. Stel de taal en regio in voor het publiek dat u onderzoekt.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Eenmaal indienen met query.py
python query.py suggestions-request.json suggestions.json

Licentielabels opslaan zonder ze als toestemming te behandelen

youtube_trainability geeft een licentielabel terug voor een video. toegestaan: ["all"] kaarten aan Creative Commons; ["none"] omvat ook ontbrekende licentiemetadata. Houd de video ID, bronrespons en ophaaldatum. Dit label verleent geen download-, hergebruik- of trainingsrechten.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Eenmaal indienen met query.py
python query.py license-request.json license.json

Het werk voor apps en agenten beperken

ArtikelUitvoering
Selecteer vóór verrijkenVoor een topic taak: één zoekopdracht, één geselecteerde videometadata en één gekozen titeltrack. Dwing het gespreksbudget in uw app, en prijs elke bron apart.
Hergebruiken door de werkelijke invoerMetadata: video ID + opties. Bijschriften: video ID + taal + track. Kanaal snapshots hebben ook een ophaaltijd nodig of ID draaien.
Stoppen met het missen van bewijsProbeer geen lege ontdekkingsresultaten opnieuw of schakel stilletjes van bijschrift tracks. Geef de kloof terug zodat de gebruiker of workflow de volgende actie kan kiezen.
Gebruik behouden en mislukt werkGebruik opslaan met succesvolle reacties. Op 429, ere Retry-After; na een onzekere indiening, controleer History voor een andere betaalde vraag.