怎么按关键词搜 YouTube 视频并拿到字幕

要做的事：想知道某个话题下热门视频里到底讲了什么，而不只是看标题。先在 YouTube 上搜，留下值得细看的视频，再把字幕拉下来。最后得到一个 JSON Lines 文件，每条视频有标题、频道、播放量、实际拿到的字幕语言、给模型读的全文，以及可以带时间戳引用的分段。

不需要 Google API key，不用走 OAuth 授权，也不用代理。每次调用就是带着 key 发一个 HTTPS 请求。

分步操作

第一步：找到视频

调用YouTube 视频搜索，query 填关键词。sort 可选 relevance（默认，相关度）、latest（最新）或 most_viewed（播放最多）。一次调用返回约 20 条视频，每次 $0.004，每条有 11 位的 id、title、url、published_at、频道信息 author 和 metrics.views。加上 view=full，每条视频还会带 ext.length_s，即时长（秒），想要长篇讲解时可以用它把 Shorts 筛掉。

curl -G "https://api.okdata.online/v1/youtube/videos/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=sourdough starter' \
  -d sort=most_viewed -d view=full

搜索结果里 text 为空，metrics.likes 和 metrics.comments 为 null；需要这些数据，可以用YouTube 视频详情。published_at 是从“3 周前”这类标签推算出来的，只能当作大概时间。

第二步：逐条取字幕

把视频的 id 传给YouTube 视频字幕。一次调用返回一份字幕，每次 $0.004。

• lang 是你想要的语言，比如 en、es、ja。它只是偏好：结果里的 lang 字段才是实际返回的字幕语言，判断不出语言时是 und。按语言归档之前先看一眼这个字段。
• segments 是按时间切好的字幕段，每段有 start 和 end（单位秒）以及这段的 text。引用原话、写章节笔记、做字幕文件，或者生成跳到某个时刻的链接（&t= 后面接开始秒数取整）都用它。
• text 是所有字幕段拼成的纯文本。要让模型做总结，就把这个交给它。

curl -G "https://api.okdata.online/v1/youtube/videos/transcript/get" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  -d id=Qm7rT2vXa9c -d lang=en

没有字幕的视频返回 not_found，不收钱。所以一批视频里每多一条没字幕的，账单就少一点。

第三步：用 Python 串起来

import json
import os
import requests

API = "https://api.okdata.online"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
PICK = 5  # 取几份字幕；每份一次调用


def get(path, **params):
    return requests.get(API + path, headers=HEADERS, params=params, timeout=90).json()


found = get("/v1/youtube/videos/search", query="sourdough starter", sort="most_viewed", view="full")
if found["code"] != "ok":
    raise RuntimeError(f"{found['code']}: {found['message']}")
videos = sorted(found["data"]["items"], key=lambda v: v["ext"]["length_s"] or 0, reverse=True)[:PICK]

with open("transcripts.jsonl", "w", encoding="utf-8") as out:
    for v in videos:
        body = get("/v1/youtube/videos/transcript/get", id=v["id"], lang="en")
        if body["code"] == "not_found":
            print(v["id"], "no captions, not charged")
            continue
        if body["code"] != "ok":
            print(v["id"], body["code"], body["message"])
            continue
        t = body["data"]["item"]
        out.write(json.dumps({
            "id": v["id"], "title": v["title"], "channel": v["author"]["name"], "views": v["metrics"]["views"],
            "lang": t["lang"], "text": t["text"], "segments": t["segments"],
        }, ensure_ascii=False) + "\n")

某条字幕取失败时，脚本只打印出来然后跳过，不会让整批中断，其余视频照样能拿到。

注意事项

• 没有字幕就没有文本。 这个接口读的是字幕轨，不做语音转文字。没有字幕的视频，只能对你有权使用的音频跑 Whisper 之类的语音模型。新上传的视频有时要过一天才会生成自动字幕。
• 一次调用一种语言。 再要第二种语言就是第二次计费调用。建议只要一次，看 lang，需要的话自己按字幕段逐段翻译，时间轴依然有效。
• 分不出自动字幕还是人工字幕。 返回结果不标注字幕类型。引用自动字幕时要多核对。
• 官方 API。 YouTube 的 captions.download 每次消耗 200 个配额单位，而且要求你有这个视频的编辑权限，所以只适合自己频道的视频，拿不了别人的。
• 重试不会重复扣费。 带一个 Idempotency-Key 请求头，比如 transcript- 加视频 ID。24 小时内用同样的 key 重发同样的请求，会拿回存好的结果，不再扣费。

如果 youtube-transcript-api 之类的库提示字幕被禁用，可以看TranscriptsDisabled 是什么意思。一次要处理几百条视频，看批量下载 YouTube 字幕。

{
  "endpoint": "youtube.videos.search",
  "params": {
    "query": "claude code tutorial"
  },
  "idempotency_key": "<新的 UUID>"
}