Do I need an API key?

Yes. You must register for a TranscriptAPI key and include it in the Authorization header. The service offers a free tier with 100 credits and up to 300 requests per minute.

What formats are supported and what do they return?

format=json returns a structured transcript with timing (start and duration) and language; format=text returns clean text without timestamps.

What errors might I encounter and how should I respond?

Common errors include 402 (no credits), 404 (no subtitles available), and 408 (timeout). Retry with backoff or handle gracefully when credits are exhausted or content is unavailable.

subtitles

Scanned

npx machina-cli add skill ZeroPointRepo/youtube-skills/subtitles --openclaw

Files (1)

SKILL.md

3.3 KB

Subtitles

Fetch YouTube video subtitles via TranscriptAPI.com.

Setup

If $TRANSCRIPT_API_KEY is not set, help the user create an account (100 free credits, no card):

Step 1 — Register: Ask user for their email.

node ./scripts/tapi-auth.js register --email USER_EMAIL

→ OTP sent to email. Ask user: "Check your email for a 6-digit verification code."

Step 2 — Verify: Once user provides the OTP:

node ./scripts/tapi-auth.js verify --token TOKEN_FROM_STEP_1 --otp CODE

API key saved to your shell profile and agent config. Ready to use.

Manual option: transcriptapi.com/signup → Dashboard → API Keys.

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"

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"

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"

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	Action
402	No credits — transcriptapi.com/billing
404	No subtitles available
408	Timeout — retry once after 2s

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

Source

git clone https://github.com/ZeroPointRepo/youtube-skills/blob/main/skills/subtitles/SKILL.mdView on GitHub

Overview

Subtitles retrieves YouTube video subtitles via TranscriptAPI to support translation, language learning, or reading along. It supports multiple languages and can return timestamped transcripts for synchronized reading or clean text suitable for translation workflows.

How This Skill Works

Use your TranscriptAPI key to call /api/v2/youtube/transcript with video_url and format. Choose json for timed transcripts or text for plain lines, and use include_timestamp to toggle timing while send_metadata adds video context like title and description.

When to Use It

You want synchronized subtitles for a YouTube video to follow along with the audio.
You need subtitles in another language to aid translation or comprehension.
You are building a language-learning workflow and require clean text without timestamps.
You want a structured JSON transcript suitable for NLP or data processing.
You need video metadata (title, description) along with the transcript for cataloging.

Quick Start

Step 1: Obtain an API key from TranscriptAPI and set TRANSCRIPT_API_KEY in your environment.
Step 2: Request subtitles with your video URL, choosing format=json for timing or format=text for clean text.
Step 3: Parse the response to access video_id, language, and the transcript array or text blob.

Best Practices

Use format=json when you need timing information for synced reading.
For reading/translation alone, set include_timestamp=false and use format=text.
Enable send_metadata=true to attach video context (title, channel, description).
Handle errors (402, 404, 408) with appropriate retries or fallbacks.
Leverage auto-generated subtitles in multiple languages by inspecting available language options.

Example Use Cases

Extract a timed transcript from a music video and translate the lyrics.
Pull a clean, timestamp-free transcript of a lecture for study notes.
Sync a reading app with video playback using the JSON transcript with start times.
Obtain subtitles in a foreign language to practice listening comprehension.
Fetch video metadata alongside the transcript to organize a learning library.

Frequently Asked Questions

Add this skill to your agents