Jelajahi dokumentasi
Contoh
Simpan trek judul YouTube yang ada dengan teks, waktu, dan bahasa. Tambahkan link video ke setiap segmen untuk kutipan dalam aplikasi atau jawaban agen Anda.
Di halaman ini
Sebelum Anda mulai
Gunakan kunci dengan izin youtube_captions dan kredit yang tersedia. Pilih Python 3.10+ dengan permintaan, atau Bash dengan cURL 7.76+ dan jq. Hidup Windows, gunakan Git Bash untuk Bash versi.
1. Pilih trek video dan judul
Buat folder timestamped- captions dan simpan request.json di sana. Buka terminal pada folder itu. Ganti video_id dengan video 11-character ID, tidak penuh URL.
Contoh ini meminta terjemahan otomatis Inggris. Dengan auto = true, en mencoba en-orig pertama, kemudian en. Eksplisit -orig kode dan auto = false tetap tepat. API tidak pernah switch antara otomatis dan uphauder disediakan takarir.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}2. Ambil dan simpan judul
Pilih satu versi dan simpan script di samping request.json. Tertulis FLASHDATA_API_KEY atau meminta kunci Anda pada prompt tersembunyi. Agen harus memuat variabel lingkungan dari toko rahasia mereka.
Jalankan dengan tracking -001 sebagai folder keluaran. Folder baru mengirim satu permintaan dan menyimpan penggunaan yang dilaporkan. Sebelum membuat captions.json, naskah memverifikasi video yang kembali ID, bahasa, judul asal dan segmen 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. Baca teks yang sudah distempel waktu
Cetakan sukses disimpan N segmen ke track-001/captions.json. Berkas itu mempertahankan trek yang kembali dan menambahkan URL untuk setiap segmen. record.json berisi permintaan yang diajukan secara tepat, requested_at, penggunaan dan segment_count; result.json menyimpan yang asli API respon.
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.jsoncat track-001/captions.json
cat track-001/record.jsonContoh keluaran
Abbreviated, illustratif captions.json. Teks dan waktu Anda akan berbeda. languageName mungkin null; script membuatnya seperti itu.
{
"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"
}
]
}Cite a video passage
Cetak tiga segmen pertama dengan sumber link. awal dan akhir tinggal dalam hitungan detik dengan presisi asli mereka. Hanya waktu awal URL yang dibulatkan: 12.5 detik-detik menjadi & t=12QQ. Urutan segmen dan timing tumpang tindih diawetkan.
Simpan cite.py di samping captions.py, kemudian jalankan dari folder yang sama.
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.jsonSimpan konteks judul
Gunakan teks segmen sebagai bukti untuk kutipan; fullText berguna untuk dibaca tetapi tidak menemukan suatu bagian. Periksa segmen sekitarnya sebelum mengutip, terutama untuk terjemahan otomatis. Tahan languageCode dan isAutoGenerated sehingga aplikasi atau agen Anda dapat mengidentifikasi trek sumber.
Gunakan kembali trek yang disimpan
Jalankan perintah yang sama untuk membangun kembali captions.json dari respon yang disimpan, tanpa suatu kunci atau query baru. Menyunting level atas request.json tidak mengubah permintaan yang disimpan dengan track-001.
python captions.py track-001bash captions.sh track-001Pilih trek lain
Untuk meminta uphagder yang disediakan terjemahan bahasa Inggris, ganti request.json dengan versi ini dan gunakan tracking -002. Ubah bahasa hanya ke kode yang ingin Anda ambil, seperti en-orig atau zh-Hans. Daftar kandidat kode Metadata transcriptLanguages, bukan apakah masing-masing memiliki trek otomatis atau upload.
Skrip mengharapkan satu kalimat bahasa. Array bahasa memiliki bentuk respon yang berbeda dengan trek dan kesalahan bahasa permanen; gunakan referensi API untuk alur kerja tersebut.
{
"source": "youtube_captions",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": false
}
}python captions.py track-002bash captions.sh track-002Bila judul hilang atau tak dapat dipakai
| Apa yang terjadi? | Yang perlu dilakukan |
|---|---|
| Trek yang dipilih tak tersedia | Periksa video, bahasa dan seleksi mobil. Pilih trek yang tersedia secara eksplisit; mengulangi permintaan yang sama tidak akan membuat takarir. |
| segments: [] | Trek yang ada tak boleh memuat teks. Skrip menyimpan trek kosong dan melaporkan kesenjangan. Jangan mengubahnya menjadi transkrip atau ringkasan. |
| Asal video, bahasa atau judul salah | Tidak ada captions.json ditulis. Bandingkan permintaan tersimpan dengan result.json sebelum memakai teks apapun. |
| Pembuatan waktu atau segmen yang hilang tak valid | Inspeksi result.json. Skrip berhenti daripada menugaskan penanda waktu yang ditemukan atau diam-diam menjatuhkan segmen yang buruk. |
| 401 / 403 / 402 | Periksa kuncinya, youtube_captions izin dan keseimbangan, secara terhormat, sebelum usaha baru. |
| 429 | Baca Retry-After in response-headers.txt dan menunggu. Skrip tidak mencoba lagi secara otomatis. |
| Timeout, 5xx, JSON tidak valid atau sebuah folder tidak lengkap | Terus berusaha dan periksa History sebelum mengirimkan lagi. Menggunakan kembali folder tidak pernah mengirim kueri lain. |
Simpan inspect_captions.py di samping captions.py, kemudian jalankan.
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