Dokumentation durchsuchen
Beispiele
Speichern Sie einen vorhandenen YouTube-Untertitel mit Text, Timing und Sprache. Fügen Sie zu jedem Segment einen Videolink für Zitate in der Antwort Ihrer App oder Ihres Agenten hinzu.
Auf dieser Seite
Bevor Sie anfangen
Verwenden Sie einen Schlüssel mit youtube_captions-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 den Video- und Caption Track
Erstellen Sie einen Ordner mit Zeitstempeln und speichern Sie dort request.json. Öffnen Sie ein Terminal in diesem Ordner. Ersetzen video_id Mit dem Video 11-Charakter IDnicht seine volle URL.
Dieses Beispiel fordert englische automatische Beschriftungen an. Mit auto=true versucht en-orig zuerst, dann en. Explizite -orig-Codes und auto=false bleiben genau. Der API wechselt niemals zwischen automatischen und von Uploadern bereitgestellten Bildunterschriften.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}2. Holen und speichern Sie die Untertitel
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 track-001 als Ausgabeordner aus. Ein neuer Ordner sendet eine Abfrage und speichert die gemeldete Nutzung. Vor dem Erstellen von captions.json überprüft das Skript das zurückgegebene Video ID, Sprache, Beschriftungsursprung und Segment-Timings.
python -m pip install requestsimport 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.")
python captions.py track-001curl --version
jq --version#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash captions.sh OUTPUT_FOLDER}"
if [[ ! -e "$out" ]]; then
jq -e '.source == "youtube_captions" and
(.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$") else false end) and
(.params.language | if type == "string" then length > 0 and length <= 35 and
(test("[^A-Za-z0-9-]") | not) else false end) and
(.params.auto | type == "boolean")' 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
captions=$(jq -e --slurpfile request "$out/request.json" '
if .source != "youtube_captions" or .status != "done"
then error("Expected a successful youtube_captions response") else . end
| .results
| if type != "array" then error("Expected a results array")
elif length != 1 then error("Expected exactly one track") else .[0] end
| $request[0].params.language as $language
| if type != "object" then error("Expected a caption object")
elif .videoId != $request[0].video_id or (.requestedLanguageCode // .languageCode) != $language
or (.languageCode != $language and ($request[0].params.auto != true
or ($language | endswith("-orig")) or .languageCode != ($language + "-orig")))
or .isAutoGenerated != $request[0].params.auto
then error("Returned video, language or caption origin does not match the request") else . end
| if (.segments | type) != "array" then error("Expected a segments array") else . end
| .videoId as $id
| .segments |= map(
if type != "object" then error("Expected caption segment objects") else . end
| if (.start | type) != "number" or (.end | type) != "number" or (.text | type) != "string"
then error("Invalid caption timing or text")
elif (.start | isfinite | not) or (.end | isfinite | not) or .start < 0 or .end < .start
then error("Invalid caption timing")
else . + {url: ("https://www.youtube.com/watch?v=" + $id + "&t=" + (.start | floor | tostring) + "s")} end
)' "$out/result.json")
printf '%s\n' "$captions" > "$out/captions.json"
jq --slurpfile request "$out/request.json" --slurpfile captions "$out/captions.json" \
--arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
'{request: $request[0], requested_at: $requested_at, usage,
segment_count: ($captions[0].segments | length), result_file: "result.json"}' \
"$out/result.json" > "$out/record.json"
printf 'Saved %s segments to %s/captions.json\n' "$(jq '.segments | length' "$out/captions.json")" "$out"
if ! jq -e 'any(.segments[]; .text | test("\\S"))' "$out/captions.json" > /dev/null; then
printf 'No caption text to cite. Keep the empty track and report the gap.\n'
fi
bash captions.sh track-0013. Lesen Sie den Zeitstempel-Text
Erfolgsdrucke Speicherte N Segmente zu track-001/captions.json. Diese Datei behält den zurückgegebenen Track bei und fügt jedem Segment ein URL hinzu. record.json enthält die genaue eingereichte Anforderung, requested_at, Nutzung und segment_count; result.json behält die ursprüngliche API-Antwort.
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.jsoncat track-001/captions.json
cat track-001/record.jsonBeispielausgabe
Abgekürzt, illustrativ captions.json. languageName kann null sein; das Skript hält es so.
{
"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"
}
]
}Zitieren Sie eine Videopassage
Drucken Sie die ersten drei Segmente mit ihren Quelllinks. Anfang und Ende bleiben in Sekunden mit ihrer ursprünglichen Präzision. Nur die Startzeit des URL wird abgerundet: 12.5 Sekunden werden &t=12s. Segmentreihenfolge und überlappende Timings bleiben erhalten.
Speichern Sie cite.py neben captions.py und führen Sie es dann aus dem gleichen Ordner aus.
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()python cite.pyjq -r '.segments[:3][] |
"[\(.start)–\(.end)s] \(.text)\n\(.url)\n"' track-001/captions.jsonBehalten Sie den Beschriftungskontext
Verwenden Sie Segmenttext als Beweis für ein Zitat; fullText ist nützlich zum Lesen, lokalisiert jedoch keine Passage. Überprüfen Sie die umgebenden Segmente vor dem Zitieren, insbesondere für automatische Beschriftungen. Bewahren Sie languageCode und isAutoGenerated auf, damit Ihre App oder Ihr Agent den Quelltrack identifizieren kann.
Wiederverwendung des gespeicherten Tracks
Führen Sie den gleichen Befehl aus, um captions.json aus der gespeicherten Antwort ohne einen Schlüssel oder eine neue Abfrage neu zu erstellen. Durch das Bearbeiten der obersten Ebene request.json wird die mit track-001 gespeicherte Anforderung nicht geändert.
python captions.py track-001bash captions.sh track-001Wählen Sie einen anderen Track
Um von einem Uploader bereitgestellte englische Bildunterschriften anzufordern, ersetzen Sie request.json durch diese Version und verwenden Sie track-002. Ändern Sie die Sprache nur in den Code, den Sie abrufen möchten, z. B. en-orig oder zh-Hans. Der transcriptLanguages von Metadaten listet Kandidatencodes auf, nicht ob jeder einen automatischen oder hochgeladenen Track hat.
Das Skript erwartet einen Sprachstring. Spracharrays haben eine andere Antwortform mit Tracks und pro-Sprachfehlern; Verwenden Sie die API-Referenz für diesen Workflow.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": false
}
}python captions.py track-002bash captions.sh track-002Wenn Untertitel fehlen oder unbrauchbar sind
| Was passierte | Lösung |
|---|---|
| Der ausgewählte Track ist nicht verfügbar | Überprüfen Sie das Video, die Sprache und die automatische Auswahl. Wählen Sie einen verfügbaren Track explizit aus; die Wiederholung der gleichen Anforderung erzeugt keine Bildunterschriften. |
| segments: [] | Ein vorhandener Track kann keinen Text enthalten. Das Skript speichert die leere Spur und meldet die Lücke. Verwandeln Sie es nicht in eine Abschrift oder Zusammenfassung. |
| Falsches Video, Sprache oder Bildunterschrift Herkunft | Es wird kein captions.json geschrieben. Vergleichen Sie die gespeicherte Anforderung mit result.json, bevor Sie einen beliebigen Text verwenden. |
| Ungültige Timings oder fehlende Segmente | result.json prüfen. Das Skript stoppt, anstatt erfundene Zeitstempel zuzuweisen oder ein fehlerhaftes Segment stillschweigend fallen zu lassen. |
| 401 / 403 / 402 | Überprüfen Sie den Schlüssel, youtube_captions Berechtigung und Balance, jeweils vor einem neuen Versuch. |
| 429 | Lesen Sie Retry-After in response-headers.txt und warten Sie. Das Skript wird nicht 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 sendet niemals eine weitere Abfrage. |
Speichern Sie inspect_captions.py neben captions.py und führen Sie es aus.
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")python inspect_captions.pyfor name in http-status.txt response-headers.txt result.json; do
printf '\n--- %s ---\n' "$name"
if [[ -f "track-001/$name" ]]; then cat "track-001/$name"; else printf 'Not saved\n'; fi
done