# Abrufen von Zeitstempel-Beschriftungen

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.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/timestamped-captions-recipe
Test: 2026-11-05 von FlashData

<a id="prepare"></a>

## 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.

- [API-Schlüssel erstellen](https://flashdata.dev/app/api-keys)
- [Agententest und Kontoverknüpfung](https://flashdata.dev/de/docs/guides/agent-onboarding/reference.md)
- [Credits und Preise](https://flashdata.dev/de/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 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.

### timestamped-captions/request.json

```json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

- [Überprüfen Sie Kandidatensprachen in Metadaten](https://flashdata.dev/de/docs/guides/video-metadata-recipe/reference.md#fields)

<a id="run"></a>

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

#### Installieren Sie in Ihrer Python-Umgebung

```bash
python -m pip install requests
```

#### timestamped-captions/captions.py

```python
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.")
```

#### Laufen Sie von timestamped-captions/

```bash
python captions.py track-001
```


### Bash

#### Überprüfen Sie Ihre Tools

```bash
curl --version
jq --version
```

#### timestamped-captions/captions.sh

```bash
#!/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
```

#### Laufen Sie von timestamped-captions/

```bash
bash captions.sh track-001
```



<a id="output"></a>

## 3. 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

#### Lokal lesen · kein API-Anruf

```bash
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.json
```


### Bash

#### Lokal lesen · kein API-Anruf

```bash
cat track-001/captions.json
cat track-001/record.json
```



<a id="expected"></a>

### Beispielausgabe

Abgekürzt, illustrativ captions.json. languageName kann null sein; das Skript hält es so.

#### timestamped-captions/track-001/captions.json

```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"
    }
  ]
}
```


<a id="cite"></a>

## 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.

### Python

Speichern Sie cite.py neben captions.py und führen Sie es dann aus dem gleichen Ordner aus.

#### timestamped-captions/cite.py

```python
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()
```

#### Drucken Sie Zitate aus gespeicherten Bildunterschriften

```bash
python cite.py
```


### Bash

#### Drucken Sie Zitate aus gespeicherten Bildunterschriften

```bash
jq -r '.segments[:3][] |
  "[\(.start)–\(.end)s] \(.text)\n\(.url)\n"' track-001/captions.json
```


- [Erstellen Sie eine Zusammenfassung mit Zitaten](https://flashdata.dev/de/docs/guides/youtube-summary/reference.md)

<a id="evidence"></a>

### Behalten 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.


<a id="reuse"></a>

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

#### Lokale Wiederverwendung

```bash
python captions.py track-001
```


### Bash

#### Lokale Wiederverwendung

```bash
bash captions.sh track-001
```



<a id="track"></a>

### Wä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.

#### timestamped-captions/request.json

```json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": false
  }
}
```

#### Python

##### Neuer Track · eine weitere API-Anfrage

```bash
python captions.py track-002
```


#### Bash

##### Neuer Track · eine weitere API-Anfrage

```bash
bash captions.sh track-002
```


- [Beschriftungsparameter und Antwortformen](https://flashdata.dev/de/docs/sources/youtube_captions/reference.md)

<a id="recover"></a>

## Wenn 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. |

### Python

Speichern Sie inspect_captions.py neben captions.py und führen Sie es aus.

#### timestamped-captions/inspect_captions.py

```python
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")
```

#### Lokale Kontrolle

```bash
python inspect_captions.py
```


### Bash

#### Lokale Kontrolle

```bash
for 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
```


- [Anfrageverlauf](https://flashdata.dev/app/jobs)
- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md)
