domains / media / youtube-transcript-search / youtube-full

youtube-full

Skill card

combined

The three copies are not interchangeable. The ZeroPointRepo copy is the only one that contains the actual executable procedure (curl commands, required headers, endpoint parameters, and credit costs). The davepoon copy is a high-level overview that omits the API mechanics. The sickn33 copy is a wrapper that claims automatic OAuth provisioning and uses abstract function names (e.g., get_transcript) rather than the raw API calls found in the source. Because the source copy is the only one that is actually executable, but the other copies contain distinct constraints (like the 'Do NOT use for' list and rate limits) that the source lacks, crowning one would hide the specific operational details or the specific safety constraints.

Repositories

Other copies

Combined skill

---
name: youtube-full
description: "Use when YouTube is or could be relevant — even if not mentioned: pasted video/channel/playlist links, video IDs, @handles, creator lookups, video summaries, quotes, translations, topic research, tutorials, talks, lectures, expert discussions, product reviews, how-to guides, new product announcements, first looks, or anything where video content is fresher or richer than text search. Covers transcripts, video/channel search, channel browsing, playlists, and within-channel search. Not for uploads, account management, or written-source-only research."
version: "1.6.2"
user-invocable: true
compatibility: Requires internet access to reach transcriptapi.com. No additional runtimes or dependencies needed.
required_environment_variables:
  - name: TRANSCRIPT_API_KEY
    prompt: Your TranscriptAPI key (starts with sk_)
    help: Free account at https://transcriptapi.com — 100 credits, no card required. Or let the agent create one for you.
    required_for: all API requests
metadata: {"openclaw":{"emoji":"🎯","requires":{"env":["TRANSCRIPT_API_KEY"]},"primaryEnv":"TRANSCRIPT_API_KEY","homepage":"https://transcriptapi.com"},"hermes":{"tags":["youtube","transcripts","video","search","channels","playlists","captions"],"category":"media"}}
---

# YouTube Full

Complete YouTube toolkit via [TranscriptAPI.com](https://transcriptapi.com). Everything in one skill.

## Setup

If `$TRANSCRIPT_API_KEY` is not set, read [references/auth-setup.md](references/auth-setup.md) and follow the instructions there to get and store the key.

## Required Headers

Every request needs two headers:

- **Authorization:** `Bearer $TRANSCRIPT_API_KEY`
- **User-Agent:** your agent's name and version if known (e.g. `HermesAgent/0.11.0`, `ClaudeCode/1.0`). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request.

## API Reference

Full OpenAPI spec: [transcriptapi.com/openapi.json](https://transcriptapi.com/openapi.json) — consult this for the latest parameters and schemas.

## Transcript — 1 credit

```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" \
  -H "User-Agent: YourAgent/1.0"
```

| Param               | Required | Default | Values                          |
| ------------------- | -------- | ------- | ------------------------------- |
| `video_url`         | yes      | —       | YouTube URL or 11-char video ID |
| `format`            | no       | `json`  | `json`, `text`                  |
| `include_timestamp` | no       | `true`  | `true`, `false`                 |
| `send_metadata`     | no       | `false` | `true`, `false`                 |

**Response** (`format=json`):

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }],
  "metadata": { "title": "...", "author_name": "...", "author_url": "..." }
}
```

## Video Info & Metadata

```bash
# Free — languages available for the transcript endpoint
curl -s "https://transcriptapi.com/api/v2/youtube/info?video_url=VIDEO_URL" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# 1 credit — rich metadata (views, likes, description, duration, tags)
curl -s "https://transcriptapi.com/api/v2/youtube/video/metadata\
?video_url=VIDEO_URL&include=details,related" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

`include` on `video/metadata` accepts `details` and/or `related`. Naming: `/video/metadata` was previously `/video/info` — the old path still works but is deprecated.

## Search — 1 credit/page

```bash
# Videos
curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# Channels, playlists, or movies
curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=channel&limit=10" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param   | Required | Default | Validation                                     |
| ------- | -------- | ------- | ----------------------------------------------- |
| `q`     | yes      | —       | 1-200 chars                                      |
| `type`  | no       | `video` | `video`, `channel`, `playlist`, `movie`         |
| `sort`  | no       | `relevance` | `relevance`, `views` (first page only)      |
| `upload_date` | no | —       | `hour`, `today`, `week`, `month`, `year` (videos, first page) |
| `duration` | no    | —       | `short`, `medium`, `long` (videos, first page)  |
| `features` | no    | —       | e.g. `hd,subtitles,cc` (first page)             |
| `limit` | no       | `20`    | 1-50                                             |

## Channels

All channel endpoints accept `channel` — an `@handle`, channel URL, or `UC...` channel ID. No need to resolve first.

### Resolve handle — FREE

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

Response: `{"channel_id": "UC...", "resolved_from": "@TED"}`

### Latest 15 videos — FREE

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

Returns exact `viewCount` and ISO `published` timestamps.

### Channel feed (videos/shorts/streams) — 1 credit/page

```bash
# First page (100 items, tab defaults to "videos")
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&tab=videos" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# Most-viewed first (channel Videos tab, ~30 items)
curl -s
[truncated]
```

## Best Practices

- Use `channel_latest` (free) before `get_transcript` to check if a video is new
- Cache transcripts in your workflow — each `get_transcript` call costs 1 credit
- Use `search_in_channel` when you already know the channel to avoid broad search noise
- Prefer `get_playlist_videos` for course or lecture series — cheaper than searching by query
- Don't batch-transcribe entire channels unless the user explicitly requested it
- Don't use `search_youtube` when you already have the video URL — jump straight to `get_transcript`

## Limitations

- This skill does not replace environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
- Transcripts are available only when YouTube has captions (manual or auto-generated). Some videos have no captions.
- API key is required for paid usage beyond the free 100-credit tier. Get one at transcriptapi.com.
- Rate limits apply: 200 RPM on Monthly plan, 300 RPM on Annual. Contact support for higher limits.

## Security & Safety Notes

- This skill makes HTTPS API calls to `transcriptapi.com`. No local data is written.
- The API key is stored in the agent's credential store, not in this SKILL.md.
- No shell commands, no binary execution, no local system mutation. Risk level: `safe`.

## Common Pitfalls

- **Problem:** `yt-dlp` fails when the agent runs on a cloud server.  
  **Solution:** This is exactly the use case for `youtube-full`. The API routes through TranscriptAPI's infrastructure a
[truncated]