Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Contoh

Ambil gambar gambar - gambar yang diambil secara bertanda waktu

Simpan jalur kapsi YouTube yang sudah ada dengan teks, waktu dan bahasanya. Tambahkan link video ke setiap segmen untuk kutipan dalam aplikasi atau jawaban agen Anda.

Pada halaman ini

Sebelum kau mulai

Gunakan kunci dengan kebenaran youtube_captions dan kredit yang tersedia. Pilih Python 3.10+ dengan requests, atau Bash dengan cURL 7.76+ dan jq. Pada Windows, gunakan Git Bash untuk versi Bash.

1. Pilih video dan jalur kapsi

Buat folder penyimpanan dan simpan request.json Di sana. Buka terminal di dalam folder itu. Ganti video_id Dan videonya. 11-character ID, tidak penuh URL.

Contoh ini meminta kapsi otomatis bahasa Inggris. Dengan auto=true, en mencoba en-orig pertama, kemudian en. Kode dan auto=false akan tetap tepat. \"API\" tidak pernah beralih antara aplikasi otomatis dan uploader-disediakan.

timestamped-captions/request.json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}

2. Kutip dan simpan gambarnya

Ia memilih salah satu versi dan menyimpan skripnya di samping request.json. Ia membaca FLASHDATA_API_KEY atau meminta kunci anda pada prompt tersembunyi. Agen-agen Agen harus memuat bahwa variabel lingkungan dari toko rahasia mereka.

Jalankan dengan track-001 sebagai folder output. Sebuah folder baru mengirimkan satu pertanyaan dan menyimpan penggunaannya yang dilaporkan. Sebelum membuat captions.json, skrip mengkonversi kembali video ID, bahasa, asal kapsi dan waktu segmen.

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.")
- Lari dari serangan waktu
python captions.py track-001

3. BARIS Baca teks yang distempel

Sidik jari sukses Sidikmen Tersimpan N segmen ke track-001/captions.json. Berkas tersebut melestarikan trek yang dikembalikan dan menambahkan URL ke setiap segmen. record.json berisi permintaan yang diajukan secara tepat, requested_at, penggunaan dan segment_count; result.json tetap mempertahankan respon API asli.

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

Contoh output

captions.json. languageName mungkin null; skrip tetap 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 sebuah video bagian

Cetak tiga segmen pertama dengan sumber link mereka. Mulai dan akhir tinggal dalam detik dengan presisi asli mereka. Hanya waktu awal URL yang dibulatkan ke bawah: 12.5 detik menjadi &t=12. Urutan segmen dan waktu yang saling tumpang tindih dipertahankan.

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()
Kutipan cetakan dari gambar gambar yang disimpan
python cite.py

Jagalah konteks kapsinya

Guna teks segmen sebagai bukti untuk sebuah kutipan; fullText berguna untuk membaca tetapi tidak menemukan sebuah bagian. Cek segmen sekitarnya sebelum mengutip, terutama untuk kapsi otomatis. Kepastian languageCode dan isAutoGenerated sehingga aplikasi atau agen Anda dapat mengidentifikasi trek sumber.

Nama trek disimpan

Mengelabui perintah yang sama untuk membangun kembali captions.json dari respon yang disimpan, tanpa kunci atau pertanyaan baru. Pengeditan request.json tidak mengubah permintaan yang disimpan dengan track-001.

Minumlah kembali secara setempat
python captions.py track-001

Pilih trek lain

Ke permintaan uploader-disediakan kapsi bahasa Inggris, menggantikan request.json dengan versi ini dan menggunakan track-002. Perubahan bahasa hanya ke kode yang Anda berniat untuk mengambil, seperti en-orig atau zh-Hans. Daftar kode kandidat transcriptLanguages milik Metadata, tidak apakah masing-masing memiliki trek otomatis atau upload.

Skrip ini menerima satu rentetan bahasa. Tatasusunan bahasa mempunyai bentuk respons berbeza dengan trek dan ralat bagi setiap bahasa; rujuk rujukan API untuk aliran kerja tersebut.

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

Jika gambar-gambar hilang atau tidak dapat digunakan

Apa yang terjadi?Tindakan
trek yang dipilih tidak tersediaPeriksa video, bahasa, dan pemilihan mobil. Taksi memilih trek yang tersedia secara eksplisit; mengulangi permintaan yang sama tidak akan membuat kapsi.
segments: []Jalur yang sudah ada tidak boleh memuat teks. Skrip menyimpan trek kosong dan melaporkan celah. Jangan mengubahnya menjadi transkrip atau ringkasan.
Salah video, bahasa, atau asal usul gambarTidak ada captions.json yang ditulis. Bandingkan permintaan yang disimpan dengan result.json sebelum menggunakan teks apapun.
Waktu tidak sah atau segmen yang hilangPeriksa result.json. Naskah berhenti daripada menetapkan timestamp diciptakan atau diam-diam menjatuhkan segmen buruk.
401 / 403 / 402Periksa kuncinya, youtube_captions izin dan keseimbangan, masing-masing, sebelum percobaan baru.
429Toanny Baca Retry-After di response-headers.txt dan tunggu. Skrip tidak mencoba lagi secara otomatis.
Had waktu habis, 5xx, JSON tidak sah atau folder tidak lengkapJangan coba-coba dan periksa History sebelum mengirimkan lagi. Melepaskan kembali foldernya tidak pernah mengirim pertanyaan 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")
Periksalah secara setempat
python inspect_captions.py