Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Voorbeelden

Tijdstempel bijschriften ophalen

Sla een bestaande YouTube titeltrack op met zijn tekst, timing en taal. Voeg een videolink toe aan elk segment voor citaten in het antwoord van uw app of agent.

Op deze pagina

Voordat u begint

Gebruik een sleutel met youtube_captions toestemming en beschikbare credits. Kies Python 3.10+ met verzoeken, of Bash met cURL 7.76+ en jq. Gebruik Git Bash op Windows voor de Bash versie.

1. Kies de video- en bijschrifttrack

Maak een map met tijdstempels en sla request.json daar op. Open een terminal in die map. video_id vervangen door 11-karakter ID, niet zijn volledige URL.

Dit voorbeeld vraagt om Engelse automatische bijschriften. Met auto=true, en probeert en-orig eerst, dan en. Expliciete -orig codes en auto=false blijven exact. De API schakelt nooit tussen automatische en uploader-ondertitels.

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}

2. De bijschriften ophalen en opslaan

Kies één versie en sla het script op naast request.json. Het leest FLASHDATA_API_KEY of vraagt om uw sleutel op een verborgen prompt. Agenten moeten die omgevingsvariabele uit hun geheime winkel laden.

Uitvoeren met track-001 als uitvoermap. Een nieuwe map verstuurt één query en slaat het gerapporteerde gebruik op. Alvorens captions.json aan te maken, controleert het script de teruggekeerde video ID, taal, bijschrift oorsprong en segment timings.

Installeer in uw Python omgeving
python -m pip install requests
timestamped-captions/captions.py
import argparse
import getpass
import json
import math
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 caption request")
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_captions"
            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_captions and an 11-character video_id")
    options = request.get("params")
    if (not isinstance(options, dict) or not isinstance(options.get("language"), str)
            or not re.fullmatch(r"[A-Za-z0-9-]{1,35}", options["language"])
            or type(options.get("auto")) is not bool):
        raise SystemExit("Set one language code and auto: true or false explicitly")
    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_captions" or data.get("status") != "done":
    raise SystemExit("Caption request did not finish successfully; inspect result.json")
tracks = data.get("results")
if not isinstance(tracks, list) or len(tracks) != 1 or not isinstance(tracks[0], dict):
    raise SystemExit("Expected one caption track; inspect result.json")
track = tracks[0]
language = request["params"]["language"]
allowed_languages = [language]
if request["params"]["auto"] and not language.endswith("-orig"):
    allowed_languages.append(language + "-orig")
if (track.get("videoId") != request["video_id"]
        or track.get("languageCode") not in allowed_languages
        or track.get("requestedLanguageCode", track.get("languageCode")) != language
        or track.get("isAutoGenerated") is not request["params"]["auto"]):
    raise SystemExit("Returned video, language or caption origin does not match the request")
if not isinstance(track.get("segments"), list):
    raise SystemExit("Expected a segments array; inspect result.json")
segments = []
for cue in track["segments"]:
    if not isinstance(cue, dict):
        raise SystemExit("Expected caption segment objects")
    start, end, text = cue.get("start"), cue.get("end"), cue.get("text")
    if (type(start) not in (int, float) or not math.isfinite(start) or start < 0
            or type(end) not in (int, float) or not math.isfinite(end) or end < start
            or not isinstance(text, str)):
        raise SystemExit("Invalid caption timing or text; inspect result.json")
    segments.append({**cue, "url": f"https://www.youtube.com/watch?v={track['videoId']}&t={math.floor(start)}s"})
captions = {**track, "segments": segments}
record = {"request": request, "requested_at": (out / "requested-at.txt").read_text().strip(),
          "usage": data.get("usage"), "segment_count": len(segments), "result_file": "result.json"}
for filename, value in (("captions.json", captions), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(segments)} segments to {out}/captions.json")
if not any(cue["text"].strip() for cue in segments):
    print("No caption text to cite. Keep the empty track and report the gap.")
Uitvoeren van tijdstempels/
python captions.py track-001

3. Lees de tekst met de tijdstempel

Succes afdrukken N-segmenten opgeslagen naar track-001/captions.json. Dat bestand behoudt de geretourneerde track en voegt een URL toe aan elk segment. record.json bevat de exacte ingediende aanvraag, requested_at, gebruik en segment_count; result.json behoudt de originele API respons.

Lokaal lezen · geen API-gesprek
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.json

Voorbeelduitvoer

Afgekort, illustratief captions.json. Je tekst en timing zullen verschillen. languageName kan null zijn; het script houdt het zo.

timestamped-captions/track-001/captions.json
{
  "videoId": "FUfGcZ092b0",
  "languageCode": "en",
  "languageName": null,
  "isAutoGenerated": true,
  "segments": [
    {
      "start": 12.5,
      "end": 16.2,
      "text": "This is an illustrative caption segment.",
      "url": "https://www.youtube.com/watch?v=FUfGcZ092b0&t=12s"
    }
  ]
}

Een video-passage opzoeken

Druk de eerste drie segmenten af met hun bronlinks. begin en eindig in seconden met hun originele precisie. Alleen de starttijd van de URL wordt naar beneden afgerond: 12.5 seconden worden &t=12s. Segment orde en overlappende timings worden bewaard.

Bewaar cite.py naast captions.py en voer het vervolgens uit vanuit dezelfde map.

timestamped-captions/cite.py
import json
from pathlib import Path

captions = json.loads(Path("track-001/captions.json").read_text(encoding="utf-8"))
for cue in captions["segments"][:3]:
    print(f"[{cue['start']}–{cue['end']}s] {cue['text']}")
    print(cue["url"])
    print()
Citaties van bewaarde bijschriften afdrukken
python cite.py

De bijschriftcontext behouden

Gebruik segmenttekst als bewijs voor een citatie; fullText is nuttig voor het lezen, maar vindt geen passage. Controleer de omliggende segmenten voordat u citeert, vooral voor automatische bijschriften. Behoud languageCode en isAutoGenerated zodat uw app of agent de brontrack kan identificeren.

De opgeslagen track hergebruiken

Voer hetzelfde commando uit om captions.json te herbouwen vanaf het opgeslagen antwoord, zonder een sleutel of nieuwe query. Het bewerken van de top-level request.json verandert niet het verzoek opgeslagen met track-001.

Lokaal hergebruik
python captions.py track-001

Kies een andere track

Voor het aanvragen van een uploader met Engelse bijschriften, vervang request.json met deze versie en gebruik track-002. Verander taal alleen naar de code die u van plan bent op te halen, zoals en-orig of zh-Hans. Metadata's transcriptLanguages geeft candidate codes aan, niet of elke code een automatisch of geüploade track heeft.

Het script verwacht één taalreeks. Taalarrays hebben een andere responsvorm met tracks en per-taal fouten; gebruik de API referentie voor die workflow.

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": false
  }
}
Nieuwe track · een ander API verzoek
python captions.py track-002

Als bijschriften ontbreken of onbruikbaar zijn

Wat is er gebeurd?Wat je moet doen
De geselecteerde track is niet beschikbaarControleer de video, taal en automatische selectie. Kies een beschikbare track expliciet; het herhalen van hetzelfde verzoek zal geen bijschriften aanmaken.
segments: []Een bestaande track kan geen tekst bevatten. Het script slaat de lege track op en rapporteert de kloof. Verander het niet in een transcriptie of samenvatting.
Verkeerde oorsprong van video, taal of bijschriftEr is geen captions.json geschreven. Vergelijk het opgeslagen verzoek met result.json voordat u een tekst gebruikt.
Ongeldige timings of ontbrekende segmentenInspecteer result.json. Het script stopt in plaats van het toewijzen van uitgevonden tijdstempels of het stil laten vallen van een slecht segment.
401 / 403 / 402Controleer de sleutel, youtube_captions permissie en balans, respectievelijk, voordat een nieuwe poging.
429Lees Retry-After in response-headers.txt en wacht. Het script wordt niet automatisch opnieuw geprobeerd.
Timeout, 5xx, ongeldige JSON of een onvolledige mapHoud de poging en controleer History alvorens opnieuw te verzenden. Hergebruik van de map stuurt nooit een andere query.

Bewaar inspect_captions.py naast captions.py, voer het dan uit.

timestamped-captions/inspect_captions.py
from pathlib import Path

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