subtitles

name	subtitles
description	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.
version	1.5.0
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":"[Truncated]"},"primaryEnv":"TRANSCRIPT_API_KEY","homepage":"https://transcriptapi.com"},"hermes":{"tags":["youtube","subtitles","captions","transcripts","video","translation","language-learning"],"category":"media"}}

Subtitles

Fetch YouTube video subtitles via TranscriptAPI.com.

Setup

If $TRANSCRIPT_API_KEY is not set, read 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.

GET /api/v2/youtube/transcript

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=false&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Param	Values	Use case
video_url	YouTube URL or video ID	Required
format	json, text	json for sync'd subs with timing
include_timestamp	true, false	false for clean text for reading/translation
send_metadata	true, false	Include title, channel, description

For language learning — clean text without timestamps:

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=false
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

For translation — structured segments:

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=json&include_timestamp=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0