API Reference

Everything the TubeCaption API can do — endpoints, parameters, response shapes, and errors.

Getting Started

The API is served over HTTPS from a single base URL. All responses are JSON unless you request plain text.

https://api.tubecaption.com/v1

1. Create an account and grab your API key from the dashboard.
2. Pass the key as a Bearer token on every request (see Authentication).
3. Call any endpoint — your first 100 credits are free, no card required.

Authentication

Authenticate with your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer tc_live_xxxxxxxxxxxxxxxx

• Keep keys server-side — never ship them in client bundles or mobile apps.
• Rotate keys from the dashboard at any time; old keys revoke instantly.
• Use separate keys per environment so you can revoke one without downtime.

Get Transcript

Returns the transcript of a public video. Choose JSON segments (with or without timestamps) or a single plain-text block.

Query parameters

Example request

curl "https://api.tubecaption.com/v1/youtube/transcript?video_url=dQw4w9WgXcQ&send_metadata=true" \
  -H "Authorization: Bearer $TC_API_KEY"

import requests

r = requests.get(
    "https://api.tubecaption.com/v1/youtube/transcript",
    params={"video_url": "dQw4w9WgXcQ", "send_metadata": True},
    headers={"Authorization": f"Bearer {API_KEY}"},
)
r.raise_for_status()
data = r.json()

const res = await fetch(
  "https://api.tubecaption.com/v1/youtube/transcript?" +
    new URLSearchParams({ video_url: "dQw4w9WgXcQ", send_metadata: "true" }),
  { headers: { Authorization: `Bearer ${process.env.TC_API_KEY}` } }
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

Example response

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "metadata": {
    "title": "How We Built Our Home Studio",
    "channel": "Creator Channel",
    "duration_seconds": 213
  },
  "transcript": [
    { "text": "Welcome back to the channel", "start": 0.0, "duration": 3.4 },
    { "text": "today we're covering something special", "start": 3.4, "duration": 3.1 }
  ]
}

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "Welcome back to the channel" },
    { "text": "today we're covering something special" }
  ]
}

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "Welcome back to the channel today we're covering something special ..."
}

Video Info

Returns metadata for a video without fetching its transcript. Costs no credits — useful for validating URLs before spending a credit on the transcript.

Query parameters

Example response

{
  "video_id": "dQw4w9WgXcQ",
  "title": "How We Built Our Home Studio",
  "channel": "Creator Channel",
  "duration_seconds": 213,
  "view_count": 1600000000,
  "has_transcript": true,
  "available_languages": ["en", "es", "pt"]
}

Search YouTube

Searches YouTube for videos, channels, or playlists and returns up to 30 results per page.

Query parameters

Example response

{
  "results": [
    {
      "video_id": "5C_HPTJg5ek",
      "title": "Rust in 100 Seconds",
      "channel": "Fireship",
      "duration_seconds": 156,
      "view_count": 2400000,
      "thumbnail": "https://i.ytimg.com/vi/5C_HPTJg5ek/hqdefault.jpg"
    }
  ],
  "continuation": "eyJraW5kIjoic2VhcmNoIi4uLiJ9"
}

Resolve Channel

Turns any channel reference — @handle, custom URL, or full URL — into a canonical channel ID. Free, so resolve once and cache the ID.

Query parameters

Example response

{
  "channel_id": "UCsBjURrPoezykLs9EqgamOA",
  "handle": "@fireship",
  "title": "Fireship",
  "subscriber_count": 3100000
}

Channel Search

Searches for videos within a single channel. Same result shape as Search YouTube.

Query parameters

Channel Videos

Lists channel uploads newest first, with up to 30 videos per page.

Query parameters

Example response

{
  "channel_id": "UCHnyfMqiRRG1u-2MsSQLbXA",
  "videos": [
    {
      "video_id": "aX3jf9Qw1kE",
      "title": "The Universe Is Weirder Than You Think",
      "published": "3 days ago",
      "duration_seconds": 1264,
      "view_count": 1900000
    }
  ],
  "continuation": "eyJraW5kIjoiY2hhbm5lbF92aWRlb3MiLi4ufQ"
}

Latest Uploads

Returns a channel's most recent uploads at zero credit cost. Designed for polling — diff the IDs against your store to detect new videos, then spend credits only on transcripts you actually need.

Query parameters

Playlist Videos

Expands a playlist into an ordered list of up to 100 videos per page.

Query parameters

Example response

{
  "playlist_id": "PLBmcuObd5An594-lZO6BvNU7cvz9CkQvI",
  "title": "Intro to Machine Learning",
  "videos": [
    { "position": 1, "video_id": "kfF04B6pDKY", "title": "Lesson 1: Getting Started" }
  ],
  "continuation": "eyJraW5kIjoicGxheWxpc3RfdmlkZW9zIi4uLn0"
}

Error Handling

Errors use conventional HTTP status codes with a consistent JSON body:

{
  "detail": "Transcript not available in requested language 'fr'",
  "code": "language_unavailable",
  "available_languages": ["en", "es"]
}

Rate Limits

Limits are enforced per API key in fixed one-minute windows across all API instances.

Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response also includes Retry-After.

Best practices

• Cache channel/resolve results; channel IDs never change.
• Use bounded concurrency for transcript batches.
• Honor Retry-After after a 429 response.
• Retry 500 and 503 responses with exponential backoff and jitter.

API Playground

Use the interactive Swagger UI to authorize with a TubeCaption key, inspect each endpoint, and execute requests without writing client code.

https://api.tubecaption.com/docs

The dashboard also includes a focused transcript test page that stores a test key only in your browser.