# Youtube Transcripts

> Pull YouTube transcripts, search videos and channels, and resolve channel handles. Use when the evidence for a task lives in video rather than text, or when a YouTube link, video ID or @handle appears in the request.

- Skill: `zeropointrepo/youtube-transcripts` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zeropointrepo/youtube-transcripts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeropointrepo/youtube-transcripts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: zeropointrepo (https://skillmd.com/u/zeropointrepo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeropointrepo/youtube-transcripts

---


# YouTube transcripts and search

Video is a primary source that most research agents cannot read. This skill turns any YouTube
video, channel or search query into text you can quote, with timestamps.

Everything runs through one REST API. No `yt-dlp`, no headless browser, no binaries to install.

## Setup

The API needs a key in the environment. Add one line to FrontierAgent's `.env`:

```bash
echo 'TRANSCRIPT_API_KEY=sk_your_key_here' >> .env
```

Get a key at https://transcriptapi.com. The free tier gives you 100 credits and asks for no card.
FrontierAgent loads `.env` at startup and shell commands inherit it, so `$TRANSCRIPT_API_KEY`
resolves inside every command below.

If the variable is empty, stop and tell the user to add it. Do not guess a key and do not print
the value back to the user.

## Every request needs both headers

`Authorization: Bearer $TRANSCRIPT_API_KEY` and a real `User-Agent`. A missing or default
User-Agent is answered with a Cloudflare 403, error code 1010.

## Get a transcript

One credit. `video_url` takes a full YouTube URL or a bare 11-character video ID.

```bash
curl -sS -G "https://transcriptapi.com/api/v2/youtube/transcript" \
  --data-urlencode "video_url=$VIDEO" \
  --data-urlencode "format=text" \
  --data-urlencode "send_metadata=true" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: FrontierAgent/1.0"
```

Set `format=json` instead when you need per-segment `start` and `duration` values, for example to
cite a timestamp. The JSON shape is
`{"video_id": "...", "language": "en", "transcript": [{"text": "...", "start": 18.0, "duration": 3.5}]}`.

## Search videos or channels

One credit. `type` is `video` or `channel`, `limit` runs 1 to 50.

```bash
curl -sS -G "https://transcriptapi.com/api/v2/youtube/search" \
  --data-urlencode "q=$QUERY" \
  --data-urlencode "type=video" \
  --data-urlencode "limit=20" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: FrontierAgent/1.0"
```

## Resolve a channel handle

Free, no credit. Accepts an `@handle`, a channel URL, or a `UC...` id.

```bash
curl -sS -G "https://transcriptapi.com/api/v2/youtube/channel/resolve" \
  --data-urlencode "input=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: FrontierAgent/1.0"
```

The other channel endpoints accept the same `channel` value directly, so you rarely need to
resolve first.

## Helper script

`scripts/transcript.sh` wraps the transcript call and fails loudly when the key is missing.

```bash
bash plugins/skills/youtube-transcripts/scripts/transcript.sh "https://www.youtube.com/watch?v=nm1TxQj9IsQ"
```

## When a call fails

| Status | What it means | What to do |
|---|---|---|
| 401 | The key is wrong or absent | Ask the user to check `TRANSCRIPT_API_KEY` in `.env` |
| 403 | Cloudflare blocked the request | You omitted the `User-Agent` header. Add it and retry |
| 404 | The video has no captions | Say so plainly. Do not invent a transcript |
| 422 | The video id or URL is malformed | Re-read the id from the user's link |
| 429 | Out of credits, or rate limited | Report it. Do not retry in a loop |

A long transcript can run past the tool output budget. Ask for `format=text`, write the body to a
file with `> outputs/transcript.txt`, then read the parts you need.

## Working with what comes back

Quote the transcript rather than paraphrasing when the exact wording carries the claim. Auto
captions carry recognition errors, so treat an odd technical term as suspect and check it against
the video title or description before you build an argument on it.