Обзор документации
Примеры
Сохраните существующий трек YouTube с его текстом, временем и языком. Добавьте видео ссылку на каждый сегмент для цитирования в ответе вашего приложения или агента.
На этой странице
Прежде чем начать
Используйте ключ с разрешением youtube_captions и доступными кредитами. Выберите Python 3.10+ с запросами или Bash с cURL 7.76+ и jq. В Windows используйте Git Bash для версии Bash.
1. Выберите трек видео и подписи
Создайте папку с временными метками и сохраните там request.json. Откройте терминал в этой папке. Замените video_id на 11-символ ID, а не на URL.
Этот пример требует автоматических подписей на английском языке. С авто = true, en сначала пробует en-orig, затем en. Явные коды -orig и auto=false остаются точными. API никогда не переключается между автоматическими и загрузочными подписями.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}2. Сохранить и сохранить подписи
Выберите одну версию и сохраните ее сценарий рядом с request.json. Он считывает FLASHDATA_API_KEY или запрашивает ваш ключ в скрытом запросе. Агенты должны загрузить эту переменную из своего секретного магазина.
Запустите Track-001 в качестве выходной папки. Новая папка отправляет один запрос и сохраняет его заявленное использование. Перед созданием captions.json скрипт проверяет возвращенное видео ID, язык, происхождение подписи и время сегмента.
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. Прочитайте текст с отметкой времени
Отзывы пользователей о Saved N segments to track-001/captions.json. Этот файл сохраняет возвращенный трек и добавляет URL в каждый сегмент. record.json содержит точно отправленный запрос, requested_at, использование и segment_count; result.json сохраняет исходный ответ API.
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.jsoncat track-001/captions.json
cat track-001/record.jsonПримерный выход
Сокращенно, иллюстративно captions.json. Ваш текст и время будут отличаться. languageName может быть null; сценарий сохраняет его таким образом.
{
"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"
}
]
}Ссылка на видео прохождение
Печатайте первые три сегмента с их исходными ссылками. начать и закончить оставаться в считанные секунды с их первоначальной точностью. Время начала URL закругляется: секунды 12.5 становятся &t=12. Сохраняется порядок сегментов и перекрывающиеся сроки.
Сохраните cite.py рядом с captions.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()python cite.pyjq -r '.segments[:3][] |
"[\(.start)–\(.end)s] \(.text)\n\(.url)\n"' track-001/captions.jsonСохраняйте контекст подписи
Используйте текст сегмента в качестве доказательства для цитирования; fullText полезен для чтения, но не находит отрывок. Проверьте окружающие сегменты перед цитированием, особенно для автоматических подписей. Сохраняйте languageCode и isAutoGenerated, чтобы ваше приложение или агент могли идентифицировать исходный трек.
Воспользоваться сохраненным треком
Запустите ту же команду, чтобы восстановить captions.json из сохраненного ответа, без ключа или нового запроса. Редактирование request.json верхнего уровня не изменяет запрос, хранящийся в треке 001.
python captions.py track-001bash captions.sh track-001Выберите другой трек
Чтобы запросить английские подписи, предоставленные загрузчиком, замените request.json этой версией и используйте трек-002. Измените язык только на код, который вы хотите получить, например, en-orig или zh-Hans. В transcriptLanguages Metadata перечислены коды кандидатов, независимо от того, имеет ли каждый из них автоматический или загруженный трек.
Сценарий ожидает одну языковую строку. Языковые массивы имеют различную форму ответа с треками и ошибками на языке; используйте ссылку API для этого рабочего процесса.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": false
}
}python captions.py track-002bash captions.sh track-002Если подписи отсутствуют или непригодны
| Что случилось? | Что делать |
|---|---|
| Выбранный трек недоступен | Проверьте видео, язык и выбор авто. Выберите доступный трек в явном виде; повторение одного и того же запроса не приведет к созданию подписей. |
| segments: [] | Существующий трек не может содержать текст. Сценарий сохраняет пустую дорожку и сообщает о разрыве. Не превращайте его в стенограмму или резюме. |
| Неправильное видео, язык или происхождение подписи | captions.json не записывается. Сравните сохраненный запрос с result.json перед использованием любого текста. |
| Неверные сроки или недостающие сегменты | Проверьте result.json. Сценарий останавливается вместо того, чтобы назначать придуманные временные метки или бесшумно сбрасывать плохой сегмент. |
| 401 / 403 / 402 | Проверьте ключ, разрешение youtube_captions и баланс, соответственно, перед новой попыткой. |
| 429 | Читайте Retry-After в response-headers.txt и ждите. Сценарий не повторяется автоматически. |
| Тайм-аут, 5xx, недействительный JSON или неполная папка | Сохраните попытку и проверьте History, прежде чем отправлять снова. Повторное использование папки никогда не отправляет другой запрос. |
Сохраните inspect_captions.py рядом с 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")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