介绍
# TranscriptAPI
通过 [TranscriptAPI.com](https://transcriptapi.com) 获取全套 YouTube 数据工具包。字幕、搜索、频道、播放列表 —— 一个 API 密钥搞定。
## 安装设置
如果未设置 `$TRANSCRIPT_API_KEY`，请协助用户创建账户（100 个免费额度，无需绑定信用卡）：
**步骤 1 — 注册：** 询问用户的电子邮件。
```bash node ./scripts/tapi-auth.js register --email USER_EMAIL ```
→ OTP 已发送至电子邮件。询问用户：_"请检查您的电子邮件以获取 6 位验证码。"_
**步骤 2 — 验证：** 一旦用户提供了 OTP：
```bash node ./scripts/tapi-auth.js verify --token TOKEN_FROM_STEP_1 --otp CODE ```
> API 密钥已保存至 `~/.openclaw/openclaw.json`。详情请参阅下方的 **文件写入**。修改前会备份现有文件。
手动选项：访问 [transcriptapi.com/signup](https://transcriptapi.com/signup) → Dashboard → API Keys。
## 文件写入
验证和保存密钥命令会将 API 密钥保存到 `~/.openclaw/openclaw.json`（设置 `skills.entries.transcriptapi.apiKey` 和 `enabled: true`）。**修改前，现有文件会被备份到 `~/.openclaw/openclaw.json.bak`。**
要在代理之外的终端/CLI 中使用 API 密钥，请手动将其添加到您的 shell 配置文件中： `export TRANSCRIPT_API_KEY=<your-key>`
## API 参考
完整的 OpenAPI 规范：[transcriptapi.com/openapi.json](https://transcriptapi.com/openapi.json) — 请查阅此文件以获取最新的参数和架构。
## 认证
所有请求：`-H "Authorization: Bearer $TRANSCRIPT_API_KEY"`
## 端点
频道端点接受 `channel` 参数 —— 可以是 `@handle`、频道 URL 或 `UC...` ID。无需预先解析。播放列表端点接受 `playlist` 参数 —— 可以是播放列表 URL 或 ID。
### GET /api/v2/youtube/transcript — 1 额度
```bash curl -s "https://transcriptapi.com/api/v2/youtube/transcript\ ?video_url=VIDEO_URL&format=text&include_timestamp=true&send_metadata=true" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 默认值 | 校验规则 | | ------------------- | ------ | ------- | ---------------------------------------- | | `video_url` | 是 | — | YouTube URL 或 11 位视频 ID | | `format` | 否 | `json` | `json` 或 `text` | | `include_timestamp` | 否 | `true` | `true` 或 `false` | | `send_metadata` | 否 | `false` | `true` 或 `false` |
接受：`https://youtube.com/watch?v=ID`、`https://youtu.be/ID`、`youtube.com/shorts/ID` 或裸 ID。
**响应** (`format=json`)：
```json { "video_id": "dQw4w9WgXcQ", "language": "en", "transcript": [ { "text": "We're no strangers...", "start": 18.0, "duration": 3.5 } ], "metadata": { "title": "...", "author_name": "...", "author_url": "..." } } ```
### GET /api/v2/youtube/search — 1 额度
```bash curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 默认值 | 校验规则 | | ------- | ---- | ------- | ---------------------- | | `q` | 是 | — | 1-200 个字符（已修剪） | | `type` | 否 | `video` | `video` 或 `channel` | | `limit` | 否 | `20` | 1-50 |
**响应** (`type=video`)：
```json { "results": [ { "type": "video", "videoId": "dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "channelTitle": "Rick Astley", "channelHandle": "@RickAstley", "channelVerified": true, "lengthText": "3:33", "viewCountText": "1.5B views", "publishedTimeText": "14 years ago", "hasCaptions": true, "thumbnails": [{ "url": "...", "width": 120, "height": 90 }] } ], "result_count": 20 } ```
**响应** (`type=channel`)：
```json { "results": [ { "type": "channel", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "title": "Rick Astley", "handle": "@RickAstley", "subscriberCount": "4.2M subscribers", "verified": true, "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC..." } ], "result_count": 5 } ```
### GET /api/v2/youtube/channel/resolve — 免费（0 额度）
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 校验规则 | | ------- | ---- | -------------------------------------------------- | | `input` | 是 | 1-200 个字符 — @handle、URL 或 UC... ID |
**响应：**
```json { "channel_id": "UCsT0YIqwnpJCM-mx7-gSA4Q", "resolved_from": "@TED" } ```
如果输入已经是有效的 `UC[a-zA-Z0-9_-]{22}` ID，则立即返回，不进行查询。
### GET /api/v2/youtube/channel/videos — 1 额度/页
```bash # First page (100 videos) curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY"
# Next pages curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 校验规则 | | -------------- | ---------- | ---------------------------------------- | | `channel` | 条件必填 | `@handle`、频道 URL 或 `UC...` ID | | `continuation` | 条件必填 | 非空字符串（用于下一页） |
请恰好提供 `channel` 或 `continuation` 中的一个。
**响应：**
```json { "results": [{ "videoId": "abc123xyz00", "title": "Latest Video", "channelId": "UCsT0YIqwnpJCM-mx7-gSA4Q", "channelTitle": "TED", "channelHandle": "@TED", "lengthText": "15:22", "viewCountText": "3.2M views", "thumbnails": [...], "index": "0" }], "playlist_info": {"title": "Uploads from TED", "numVideos": "5000"}, "continuation_token": "4qmFsgKlARIYVVV1...", "has_more": true } ```
### GET /api/v2/youtube/channel/latest — 免费（0 额度）
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 校验规则 | | --------- | ---- | ------------------------------------ | | `channel` | 是 | `@handle`、频道 URL 或 `UC...` ID |
通过 RSS 返回最近的 15 个视频，包含准确的观看次数和 ISO 时间戳。
**响应：**
```json { "channel": { "channelId": "...", "title": "TED", "author": "TED", "url": "..." }, "results": [ { "videoId": "abc123xyz00", "title": "Latest Video", "published": "2026-01-30T16:00:00Z", "viewCount": "2287630", "description": "Full description...", "thumbnail": { "url": "...", "width": "480", "height": "360" } } ], "result_count": 15 } ```
### GET /api/v2/youtube/channel/search — 1 额度
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/search\ ?channel=@TED&q=climate+change&limit=30" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 校验规则 | | --------- | ---- | ------------------------------------ | | `channel` | 是 | `@handle`、频道 URL 或 `UC...` ID | | `q` | 是 | 1-200 个字符 | | `limit` | 否 | 1-50（默认 30） |
### GET /api/v2/youtube/playlist/videos — 1 额度/页
```bash # First page curl -s "https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_PLAYLIST_ID" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY"
# Next pages curl -s "https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 校验规则 | | -------------- | ---------- | -------------------------------------------------------------- | | `playlist` | 条件必填 | 播放列表 URL 或 ID（`PL`/`UU`/`LL`/`FL`/`OL` 前缀） | | `continuation` | 条件必填 | 非空字符串 |
## 额度消耗
| 端点 | 消耗 | | --------------- | ---------- | | transcript | 1 | | search | 1 | | channel/resolve | **免费** | | channel/search | 1 | | channel/videos | 1/页 | | channel/latest | **免费** | | playlist/videos | 1/页 |
## 错误
| 代码 | 含义 | 操作 | | ---- | ------------------ | ------------------------------------------------- | | 401 | API 密钥错误 | 检查密钥，重新运行安装设置 | | 402 | 额度不足 | 前往 transcriptapi.com/billing 充值 | | 404 | 未找到 | 视频/频道/播放列表不存在或没有字幕 | | 408 | 超时/可重试 | 2 秒后重试一次 | | 422 | 校验错误 | 检查参数格式 | | 429 | 速率受限 | 请等待，并遵守 Retry-After 响应头 |
## 提示
- 当用户分享 YouTube URL 但未给出具体指令时，获取字幕并总结要点。 - 使用 `channel/latest`（免费）在获取字幕之前检查是否有新上传 —— 直接传入 @handle 即可。 - 用于研究：搜索 → 选择视频 → 获取字幕。 - 免费套餐：100 额度，300 次/分钟请求。入门版（$5/月）：1,000 额度，300 次/分钟请求。