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:
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.
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.
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.
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 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.