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

> 按关键词搜 YouTube，挑出值得看的视频，拿到带时间戳的字幕：lang 参数、segments 和 text 的区别、没有字幕的视频、Python 代码和费用。

网页版：https://okdata.online/zh/guides/youtube-video-transcript/

先用 YouTube 视频搜索，再对挑中的每条视频调 YouTube 视频字幕。下面的示例一共 6 次调用，最多花费 $0.024；失败的调用不扣费，没有字幕的视频返回 not_found，也不收钱。

更新于 2026-11-12

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

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

## 分步操作

### 第一步：找到视频

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

```bash
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 视频详情](https://okdata.online/zh/apis/youtube/videos/get/)。`published_at` 是从“3 周前”这类标签推算出来的，只能当作大概时间。

### 第二步：逐条取字幕

把视频的 `id` 传给[YouTube 视频字幕](https://okdata.online/zh/apis/youtube/videos/transcript/get/)。一次调用返回一份字幕，每次 $0.004。

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

```bash
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 串起来

```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](https://developers.google.com/youtube/v3/docs/captions/download) 每次消耗 200 个配额单位，而且要求你有这个视频的编辑权限，所以只适合自己频道的视频，拿不了别人的。
- **重试不会重复扣费。** 带一个 `Idempotency-Key` 请求头，比如 `transcript-` 加视频 ID。24 小时内用同样的 key 重发同样的请求，会拿回存好的结果，不再扣费。

如果 youtube-transcript-api 之类的库提示字幕被禁用，可以看[TranscriptsDisabled 是什么意思](https://okdata.online/zh/answers/youtube-transcripts-disabled/)。一次要处理几百条视频，看[批量下载 YouTube 字幕](https://okdata.online/zh/answers/bulk-youtube-transcripts/)。

## 示例花费

搜一页播放量最高的 sourdough starter（鲁邦种）视频，再取其中最长的 5 条的英文字幕

| 接口 | 调用次数 | 单价 | 小计 |
|---|---|---|---|
| [YouTube 视频搜索](https://okdata.online/zh/apis/youtube/videos/search/) | 1 | $0.004 | $0.004 |
| [YouTube 视频字幕](https://okdata.online/zh/apis/youtube/videos/transcript/get/) | 5 | $0.004 | $0.02 |
| 合计 | 6 |  | $0.024 |

按本页生成时的价格计算。失败的调用不扣费。

## 在你的 AI 里用（MCP）

先接好 MCP 服务，然后直接说你要什么。智能体会自己找到这些接口、看清价格，再用你的余额调用。

可以这样说：在 YouTube 搜 sourdough starter，按播放量排序，取一页。挑最长的 5 条视频，拿英文字幕，总结每条视频给了哪些建议，每一点都带上时间戳。

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

MCP：`https://api.okdata.online/mcp`

## 本指南用到的接口

- [YouTube 视频搜索](https://okdata.online/zh/apis/youtube/videos/search/) `youtube.videos.search`：$0.004/次 · 每页约 20 条视频
- [YouTube 视频字幕](https://okdata.online/zh/apis/youtube/videos/transcript/get/) `youtube.videos.transcript.get`：$0.004/次

## 更多YouTube内容

- [YouTube API](https://okdata.online/zh/apis/youtube/)
- [怎么导出某个话题下所有 YouTube 视频的评论](https://okdata.online/zh/guides/youtube-comments-export/)
- [几百个 YouTube 视频的字幕怎么批量下载？](https://okdata.online/zh/answers/bulk-youtube-transcripts/)
- [用平台官方 API 还是第三方社媒数据接口？](https://okdata.online/zh/answers/official-api-vs-third-party-social-data/)
- [有没有能让 Claude 读取 TikTok、YouTube 和 X 数据的 MCP 服务？](https://okdata.online/zh/answers/tiktok-youtube-x-mcp-server/)
- [怎么用 YouTube 视频字幕做一个 RAG 问答机器人？](https://okdata.online/zh/answers/youtube-transcripts-rag-chatbot/)
- [跑一个社媒数据任务之前，怎么提前知道要花多少钱？](https://okdata.online/zh/answers/estimate-data-api-cost-before-running/)
- [Node.js 智能体（Vercel AI SDK）怎么把 TikTok、YouTube 数据做成工具？](https://okdata.online/zh/answers/node-agent-tiktok-youtube-tools/)
- [平台官方 API 和第三方数据接口怎么选（2026）](https://okdata.online/zh/compare/official-apis-vs-data-apis/)
- [怎么选社交媒体数据 API（2026）](https://okdata.online/zh/compare/social-media-data-apis/)
- [内容搜索接口](https://okdata.online/zh/roles/posts-search/)
- [字幕接口](https://okdata.online/zh/roles/transcripts-get/)

## 资料来源

- [YouTube Data API: Captions: download](https://developers.google.com/youtube/v3/docs/captions/download) (读取于 2026-11-12)