Subtitles

Documents

subtitles

Subtitles is an Agent Skill for documents published in the ZeroPointRepo/youtube-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/ZeroPointRepo/youtube-skills/blob/HEAD/skills/subtitles/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/subtitles, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

curl -s "https://transcriptapi.com/api/v2/youtube/transcript\
?video_url=VIDEO_URL&format=text&include_timestamp=false&send_metadata=true" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "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:

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

For translation — structured segments:

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

Response (format=json):

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 }
  ]
}

Response (format=text, include_timestamp=false):

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "We're no strangers to love\nYou know the rules and so do I..."
}

Tips

Many videos have auto-generated subtitles in multiple languages.
Use format=json to get timing for each line (great for sync'd reading).
Use include_timestamp=false for clean text suitable for translation apps.

Errors

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	No subtitles	No subtitles available
408	Timeout	Retry once after 2s

1 credit per request. Free tier: 100 credits, 300 req/min.