---
name: Subtitles
slug: subtitles-2
category: Automation
description: Subtitles fetches timestamped or plain-text transcripts from YouTube videos. Use it to read along, translate, extract what was said, or support language learning and accessibility.
github: "https://github.com/ZeroPointRepo/youtube-skills/tree/main/skills/subtitles"
stars: 560
forks: 56
install: "npx degit https://github.com/ZeroPointRepo/youtube-skills/tree/main/skills/subtitles ~/.claude/skills/subtitles"
installs_to: ~/.claude/skills/subtitles
source_path: skills/subtitles/SKILL.md
collection_size: 24
category_size: 1523
collection_url: "https://dirskills.com/collections/ZeroPointRepo/youtube-skills"
added: 2026-08-25T05:14:45.057Z
last_synced: 2026-08-25T05:14:45.057Z
canonical_url: "https://dirskills.com/skills/subtitles-2"
---

# Subtitles

Subtitles fetches timestamped or plain-text transcripts from YouTube videos. Use it to read along, translate, extract what was said, or support language learning and accessibility.

**Install:**

```bash
npx degit https://github.com/ZeroPointRepo/youtube-skills/tree/main/skills/subtitles ~/.claude/skills/subtitles
```

## README

# Subtitles

Fetch YouTube video subtitles via [TranscriptAPI.com](https://transcriptapi.com).

## Setup

If `$TRANSCRIPT_API_KEY` is not set, read [references/auth-setup.md](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

```http
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:

```http
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:

```http
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
```

**Response** (`format=json`):

```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`):

```json
{
  "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.

## Copy-paste examples

Every request in this file as a ready-to-run one-liner: [references/curl-examples.md](references/curl-examples.md)