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.
インストールする前に、エージェントに与えられる指示の中身を確認できます。
Complete YouTube toolkit via TranscriptAPI.com. Everything in one skill.
If $TRANSCRIPT_API_KEY is not set, read references/auth-setup.md and follow the instructions there to get and store the key.
Every request needs two headers:
Bearer $TRANSCRIPT_API_KEYHermesAgent/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.Full OpenAPI spec: transcriptapi.com/openapi.json — consult this for the latest parameters and schemas.
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
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):
{
"video_id": "dQw4w9WgXcQ",
"language": "en",
"transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }],
"metadata": { "title": "...", "author_name": "...", "author_url": "..." }
}
# Free — languages available for the transcript endpoint
GET https://transcriptapi.com/api/v2/youtube/info?video_url=VIDEO_URL
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# 1 credit — rich metadata (views, likes, description, duration, tags)
GET https://transcriptapi.com/api/v2/youtube/video/metadata?video_url=VIDEO_URL&include=details,related
Authorization: Bearer $TRANSCRIPT_API_KEY
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.
# Videos
GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Channels, playlists, or movies
GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=channel&limit=10
Authorization: Bearer $TRANSCRIPT_API_KEY
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 |
All channel endpoints accept channel — an @handle, channel URL, or UC... channel ID. No need to resolve first.
GET https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Response: {"channel_id": "UC...", "resolved_from": "@TED"}
GET https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Returns exact viewCount and ISO published timestamps.
# First page (100 items, tab defaults to "videos")
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&tab=videos
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Most-viewed first (channel Videos tab, ~30 items)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Next pages (repeat the same tab AND sort)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Provide exactly one of channel or continuation. tab is videos (default), shorts, or streams. Response includes continuation_token and has_more.
Sorting. Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit.
When paging, send the same sort on each request.
Item fields. Every item carries members_only, true only when YouTube badges it "Members only", and those items have no viewCountText. tab=streams items carry lengthText and publishedTimeText (for example Streamed 2 years ago); tab=shorts returns null for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds (tab=videos with sort, tab=shorts, tab=streams) channelId, channelTitle, channelHandle and index are null.
GET https://transcriptapi.com/api/v2/youtube/channel/search?channel=@TED&q=QUERY&limit=30
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
GET https://transcriptapi.com/api/v2/youtube/channel/info?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Returns title, handle, verified flag, subscriber/video counts, description, tags, thumbnails, banners, and availableTabs.
GET https://transcriptapi.com/api/v2/youtube/channel/playlists?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Returns each playlist's playlistId, title, url, videoCountText — feed a playlistId into the Playlists endpoint below.
GET https://transcriptapi.com/api/v2/youtube/channel/posts?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
GET https://transcriptapi.com/api/v2/youtube/channel/sections?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
tab is featured (default, Home page), podcasts, or releases.
Accepts playlist — a YouTube playlist URL or playlist ID.
# First page
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_ID
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Next pages
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Valid ID prefixes: PL, UU, LL, FL, OL. Response includes playlist_info, results, continuation_token, has_more.
| Endpoint | Cost |
|---|---|
| transcript | 1 |
| info | free |
| video/metadata | 1 |
| search | 1/page |
| channel/resolve | free |
| channel/info | 1 |
| channel/latest | free |
| channel/videos | 1/page |
| channel/search | 1 |
| channel/playlists | 1/page |
| channel/posts | 1/page |
| channel/sections | 1 |
| playlist/videos | 1/page |
| Field | Rule |
|---|---|
channel | @handle, channel URL, or UC... ID |
playlist | Playlist URL or ID (PL/UU/LL/FL/OL prefix) |
q | 1-200 chars |
type (search) | video (default), channel, playlist, movie |
tab (channel/videos) | videos (default), shorts, streams |
sort (channel/videos) | latest, popular, oldest (omit for the uploads feed) |
tab (channel/sections) | featured (default), podcasts, releases |
include (video/metadata) | details, related (comma-separated) |
limit | 1-50 |
| Code | Meaning | Action |
|---|---|---|
| 401 | Bad API key | Check key |
| 402 | No credits | transcriptapi.com/billing |
| 403/1010 | Cloudflare block | Add or fix User-Agent header |
| 404 | Not found | Resource doesn't exist or no captions |
| 408 | Timeout | Retry once after 2s |
| 422 | Validation error | Check param format |
| 429 | Rate limited | Wait, respect Retry-After |
Research workflow: search → pick videos → fetch transcripts
# 1. Search
GET https://transcriptapi.com/api/v2/youtube/search?q=machine+learning+explained&limit=5
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# 2. Transcript
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Channel monitoring: latest (free) → transcript
# 1. Latest uploads (free — pass @handle directly)
GET https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# 2. Transcript of latest
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
Free tier: 100 credits, 300 req/min. Starter ($5/mo): 1,000 credits.
Every request in this file as a ready-to-run one-liner: references/curl-examples.md
まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
Use when captions, subtitles, or the spoken text of a YouTube video is needed — even if not explicitly requested: pasted video links or IDs, requests to read, quote, or translate a video, accessibility needs, deaf/HoH use cases, content review, or language learning. Fetches timestamped caption data from any YouTube video. Not for uploading subtitles or account management.
日本語の概要は準備中です。原文の説明を表示しています。
Use when subtitles or the spoken text of a YouTube video is needed: pasted video links or IDs, requests to translate a video, read along, follow foreign-language content, or extract what was said. Also use for language learning or accessibility. Fetches timestamped subtitles from any YouTube video. Not for uploading subtitles or account management.
日本語の概要は準備中です。原文の説明を表示しています。
Use when the spoken content of a YouTube video is needed — even if not explicitly requested: pasted video links or IDs, requests to summarize, quote, transcribe, translate, fact-check, or extract anything from a video. Also use for research or learning when a video is the source. Not for uploads or account management.
日本語の概要は準備中です。原文の説明を表示しています。
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, 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.
日本語の概要は準備中です。原文の説明を表示しています。
Use when video content needs to be extracted as text: pasted YouTube links or IDs, requests to transcribe, summarize, quote, translate, convert video to text, or extract information from video content. Also use when a user shares a video URL without explanation and wants to know what it says. Not for uploads or account management.
日本語の概要は準備中です。原文の説明を表示しています。
Use when YouTube data is needed without Google API quotas or OAuth setup: transcripts, video metadata, channel info, search results, playlists. Triggers on pasted YouTube links, creator names, @handles, topic research, video summaries, channel browsing, or any request where YouTube content would help — even if not mentioned explicitly. Not for uploads, account management, or written-source-only research.
日本語の概要は準備中です。原文の説明を表示しています。