DEVELOPER REFERENCE

API Documentation

Extract YouTube transcripts programmatically. SSE streaming, timestamps, speaker detection, and caching built in.

OVERVIEW

Programmatic access

The TubeScript API provides programmatic access to YouTube video transcription. Send a YouTube URL and receive timestamped transcript segments via a real-time SSE stream or a single JSON response. Each segment includes the text, start time, duration, and optional speaker identification.

Transcripts are generated using Gemini AI and cached for 7 days. Cached responses are returned instantly. The API handles video processing, audio extraction, and text formatting so your application does not have to.

AUTHENTICATION

API keys

API access requires a Team plan subscription ($29/month). After subscribing, you can generate an API key from your account dashboard.

Include your API key in the Authorization header of every request as a Bearer token.

// Header format Authorization: Bearer YOUR_API_KEY

ENDPOINT

Transcript request

POST/api/transcript

Submit a YouTube URL for transcription. Set stream: true for real-time SSE delivery or omit it for a single JSON response.

Request Body

{
  "url": "https://youtube.com/watch?v=VIDEO_ID",
  "language": "en",
  "stream": true
}

Parameters

urlstringrequired

Full YouTube video URL. Supports youtube.com/watch, youtu.be, and /shorts/ formats.

languagestring

Language code for transcription. Defaults to "en".

streamboolean

Enable SSE streaming. Defaults to false.

SSE response format

When stream: true, the API returns a Server-Sent Events stream with three event types:

metadataSent once at the start

event: metadata
data: {
  "video_id": "dQw4w9WgXcQ",
  "video_title": "Video Title",
  "channel_name": "Channel Name",
  "video_duration": 212,
  "language": "en",
  "cached": false
}

segmentSent for each transcript segment

event: segment
data: {
  "start": 0,
  "duration": 4.2,
  "text": "First segment of the transcript",
  "speaker": "Speaker 1"
}

doneSent once when complete

event: done
data: {
  "word_count": 1847,
  "read_time_minutes": 8,
  "ai_transcribed": true,
  "permalink": "https://tubescript.cc/transcript/dQw4w9WgXcQ"
}

JSON response format

When streaming is disabled (default), the API returns a single JSON object after the transcript is fully processed.

{
  "success": true,
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "video_title": "Video Title",
    "channel_name": "Channel Name",
    "video_duration": 212,
    "language": "en",
    "is_auto_generated": true,
    "ai_transcribed": true,
    "word_count": 1847,
    "read_time_minutes": 8,
    "segments": [
      {
        "start": 0,
        "duration": 4.2,
        "text": "First segment of the transcript",
        "speaker": "Speaker 1"
      }
    ],
    "cached": false,
    "permalink": "https://tubescript.cc/transcript/dQw4w9WgXcQ"
  }
}

LIMITS

Rate limits

PlanDaily LimitAPI Access

Free2 requests/dayWeb only

Pro ($6/mo)UnlimitedWeb only

Team ($29/mo)Unlimited + 100 API/dayFull API access

Rate limits reset at midnight UTC. Free tier usage is tracked by IP address. Cached transcripts do not count against your limit.

EXAMPLES

Code examples

cURL

curl -X POST https://tubescript.cc/api/transcript \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "stream": false}'

JavaScript

const response = await fetch(
  "https://tubescript.cc/api/transcript",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
      stream: true
    })
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  const lines = text.split("\n");

  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}

Python

import requests
import json

response = requests.post(
    "https://tubescript.cc/api/transcript",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        decoded = line.decode("utf-8")
        if decoded.startswith("data: "):
            data = json.loads(decoded[6:])
            print(data)

ERRORS

Error codes

CodeNameDescription

400INVALID_URLINVALID_URLThe request body is missing a valid YouTube URL. Ensure the url field contains a full YouTube video URL.

429RATE_LIMITEDRATE_LIMITEDYou have exceeded your daily request limit. The response includes a reset_at timestamp indicating when your limit resets (midnight UTC).

500INTERNAL_ERRORINTERNAL_ERRORAn unexpected server error occurred. Retry the request after a brief delay. If the error persists, contact support.

502TRANSCRIPTION_FAILEDTRANSCRIPTION_FAILEDThe transcription service failed to process the video. This can happen with private, deleted, or age-restricted videos.

503SERVICE_UNAVAILABLESERVICE_UNAVAILABLEThe transcription service is temporarily unavailable. Retry with exponential backoff.

Error response format

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "You've used all 2 free transcripts today.",
    "reset_at": "2026-02-15T00:00:00.000Z"
  }
}

Ready to integrate?

Get your API key with the Team plan. Unlimited web transcripts plus 100 API requests per day.

View Pricing