介绍
# YouTube Full
通过 [TranscriptAPI.com](https://transcriptapi.com) 提供的完整 YouTube 工具包。所有功能集成在一个技能中。
## 安装设置
如果未设置 `$TRANSCRIPT_API_KEY`，请协助用户创建一个账户（100 个免费额度，无需绑定银行卡）：
**步骤 1 — 注册：** 询问用户的电子邮件地址。
```bash node ./scripts/tapi-auth.js register --email USER_EMAIL ```
→ 验证码已发送至电子邮件。询问用户：_"请检查您的电子邮件以获取 6 位验证码。"_
**步骤 2 — 验证：** 当用户提供验证码后：
```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) → 控制台 → API 密钥。
## 文件写入
验证和保存密钥的命令会将 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) — 请查阅此文档以获取最新的参数和架构。
## 字幕/文本 — 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` |
**响应** (`format=json`)：
```json { "video_id": "dQw4w9WgXcQ", "language": "en", "transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }], "metadata": { "title": "...", "author_name": "...", "author_url": "..." } } ```
## 搜索 — 1 个额度
```bash # Videos curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY"
# Channels curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=channel&limit=10" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
| 参数 | 必填 | 默认值 | 验证规则 | | ------- | -------- | ------- | ------------------ | | `q` | 是 | — | 1-200 个字符 | | `type` | 否 | `video` | `video`, `channel` | | `limit` | 否 | `20` | 1-50 |
## 频道
所有频道接口都接受 `channel` 参数，可以是 `@handle`、频道 URL 或 `UC...` 频道 ID。无需预先解析。
### 解析 Handle — 免费
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
响应：`{"channel_id": "UC...", "resolved_from": "@TED"}`
### 获取最新 15 个视频 — 免费
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
返回精确的 `viewCount` 和 ISO 格式的 `published` 时间戳。
### 获取频道所有视频 — 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` 或 `continuation` 二者之一。响应包含 `continuation_token` 和 `has_more`。
### 频道内搜索 — 1 个额度
```bash curl -s "https://transcriptapi.com/api/v2/youtube/channel/search\ ?channel=@TED&q=QUERY&limit=30" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
## 播放列表 — 1 个额度/页
接受 `playlist` 参数，可以是 YouTube 播放列表 URL 或播放列表 ID。
```bash # First page curl -s "https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_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" ```
有效的 ID 前缀：`PL`、`UU`、`LL`、`FL`、`OL`。响应包含 `playlist_info`、`results`、`continuation_token`、`has_more`。
## 额度消耗
| 接口 | 消耗 | | --------------- | -------- | | transcript | 1 | | search | 1 | | channel/resolve | **免费** | | channel/latest | **免费** | | channel/videos | 1/页 | | channel/search | 1 | | playlist/videos | 1/页 |
## 验证规则
| 字段 | 规则 | | ---------- | ------------------------------------------------------- | | `channel` | `@handle`、频道 URL 或 `UC...` ID | | `playlist` | 播放列表 URL 或 ID（`PL`/`UU`/`LL`/`FL`/`OL` 前缀） | | `q` | 1-200 个字符 | | `limit` | 1-50 |
## 错误代码
| 代码 | 含义 | 处理方式 | | ---- | ---------------- | ------------------------------------- | | 401 | API 密钥错误 | 检查密钥 | | 402 | 额度不足 | 访问 transcriptapi.com/billing | | 404 | 未找到 | 资源不存在或无字幕 | | 408 | 超时 | 2 秒后重试一次 | | 422 | 验证错误 | 检查参数格式 | | 429 | 请求频率受限 | 请等待，并遵守 Retry-After 头 |
## 典型工作流
**研究工作流：** 搜索 → 选择视频 → 获取字幕
```bash # 1. Search curl -s "https://transcriptapi.com/api/v2/youtube/search\ ?q=machine+learning+explained&limit=5" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" # 2. Transcript curl -s "https://transcriptapi.com/api/v2/youtube/transcript\ ?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
**频道监控：** 最新视频（免费）→ 获取字幕
```bash # 1. Latest uploads (free — pass @handle directly) curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" # 2. Transcript of latest curl -s "https://transcriptapi.com/api/v2/youtube/transcript\ ?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" ```
免费套餐：100 个额度，300 请求/分钟。入门版 ($5/月)：1,000 个额度。