How to Use the SubtitlesYT API: A Developer Guide

SubtitlesYT offers a REST API that lets you fetch YouTube subtitles programmatically. Whether you're building a content pipeline, training dataset, or research tool, the API gives you direct access to subtitles in TXT, SRT, or VTT format — no browser needed.

Authentication

All API requests require a Bearer token in the Authorization header. Contact us at support@subtitlesyt.com to request an API token.

Endpoint

POST https://subtitlesyt.com/api/subtitles

Request Headers

Header	Value
Authorization	Bearer YOUR_API_TOKEN
Content-Type	application/json

Request Body

Field	Type	Required	Description
url	string	Yes	YouTube video URL (regular, Shorts, or live)
format	string	No	txt (default), srt, or vtt
store	boolean	No	Save subtitles to database (default: false)
meta	object	No	Custom metadata to store alongside subtitles

Example: Basic Request (cURL)

curl -X POST https://subtitlesyt.com/api/subtitles   -H "Authorization: Bearer YOUR_API_TOKEN"   -H "Content-Type: application/json"   -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "txt"
  }'

Example: Python

import requests

response = requests.post(
    "https://subtitlesyt.com/api/subtitles",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "format": "srt",
    },
)

data = response.json()
if data["ok"]:
    print(data["subtitles"])
else:
    print("Error:", data["error"])

Example: JavaScript (Node.js)

const response = await fetch("https://subtitlesyt.com/api/subtitles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    format: "vtt",
  }),
});

const data = await response.json();
if (data.ok) {
  console.log(data.subtitles);
} else {
  console.error("Error:", data.error);
}

Successful Response

{
  "ok": true,
  "video_id": "dQw4w9WgXcQ",
  "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "subtitle_format": "txt",
  "subtitles": "Never gonna give you up...",
  "lang": "en",
  "stored": false
}

Error Responses

HTTP Code	Meaning	Example
401	Missing or invalid token	{"ok": false, "error": "Invalid API token"}
400	Bad request (missing URL, invalid format)	{"ok": false, "error": "Missing 'url' in request body"}
404	No subtitles found	{"ok": false, "error": "Subtitles not found or empty"}
500	Server error	{"ok": false, "error": "Failed to fetch subtitles: ..."}

Supported URL Formats

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/shorts/VIDEO_ID
• https://www.youtube.com/live/VIDEO_ID

Subtitle Formats Explained

• TXT — Plain text, no timestamps. Best for reading, search indexing, or feeding into LLMs.
• SRT — SubRip format with numbered segments and timestamps. Works with most video players and editors.
• VTT — WebVTT format for web-based video players. Used in HTML5 <track> elements.

Not sure which format to choose? Read our guide on SRT vs VTT vs SBV subtitle formats.

Storing Subtitles

Set "store": true to save fetched subtitles to the SubtitlesYT database. You can also attach custom metadata using the meta field — useful for tagging subtitles with project names, categories, or any other context your workflow needs.

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "srt",
  "store": true,
  "meta": {
    "project": "training-data",
    "batch": 42
  }
}

Rate Limits

The API is rate-limited to prevent abuse. If you hit the limit, you'll receive a 429 Too Many Requests response. Wait a moment and retry. For higher limits, contact support@subtitlesyt.com.

Tips for Using the API

• Always check the ok field in the response before processing subtitles.
• Use srt or vtt format if you need timestamps for syncing or editing.
• Use txt format if you plan to feed the transcript into an LLM or search engine.
• Combine with the Token Counter to check token counts before sending transcripts to GPT.
• Not all YouTube videos have subtitles — handle 404 responses gracefully.

Get Started

Ready to integrate? Email support@subtitlesyt.com to request your API token and start fetching subtitles programmatically.