Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Contoh

Ambil taktimestamp takarir

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.

timestamped-captions/request.json
{
  "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.

Pasang di lingkungan Python Anda
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.")
Jalankan dari timestamping -captions /
python captions.py track-001

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

Baca secara lokal panggilan API
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.json

Contoh keluaran

Abbreviated, illustratif captions.json. Teks dan waktu Anda akan berbeda. languageName mungkin null; script membuatnya seperti itu.

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

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.

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()
Cetak kutipan dari judul yang disimpan
python cite.py

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

Menggunakan kembali lokal
python captions.py track-001

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

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": false
  }
}
Trek baru permintaan API lainnya
python captions.py track-002

Bila judul hilang atau tak dapat dipakai

Apa yang terjadi?Yang perlu dilakukan
Trek yang dipilih tak tersediaPeriksa 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 salahTidak ada captions.json ditulis. Bandingkan permintaan tersimpan dengan result.json sebelum memakai teks apapun.
Pembuatan waktu atau segmen yang hilang tak validInspeksi result.json. Skrip berhenti daripada menugaskan penanda waktu yang ditemukan atau diam-diam menjatuhkan segmen yang buruk.
401 / 403 / 402Periksa kuncinya, youtube_captions izin dan keseimbangan, secara terhormat, sebelum usaha baru.
429Baca Retry-After in response-headers.txt dan menunggu. Skrip tidak mencoba lagi secara otomatis.
Timeout, 5xx, JSON tidak valid atau sebuah folder tidak lengkapTerus 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.

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")
Inspeksi secara lokal
python inspect_captions.py