GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing transcriptfetch.com — YouTube Transcript API: endpoint, parameters and examples

YouTube Transcript API

Returns the transcript of a YouTube video, as plain text or timestamped segments. The video is given as a URL or an 11-character id. The caption track is used when the video has one; otherwise AI Fallback Transcription transcribes the audio (on by default), inline for videos under 20 minutes and as a job for longer ones.

Supported URLs

All URL formats

Watch URLhttps://www.youtube.com/watch?v=dQw4w9WgXcQ
Short URLhttps://youtu.be/dQw4w9WgXcQ
Shorts URLhttps://www.youtube.com/shorts/dQw4w9WgXcQ
Embed URLhttps://www.youtube.com/embed/dQw4w9WgXcQ
Legacy /v/ URLhttps://www.youtube.com/v/dQw4w9WgXcQ
Completed live URLhttps://www.youtube.com/live/dQw4w9WgXcQ
Video IDdQw4w9WgXcQ

Body parameters

type

string

required

true

description

A video URL or 11-character YouTube video ID.
Accepts YouTube (watch, youtu.be, /shorts/), TikTok, and Instagram URLs, plus direct media file URLs (mp4/mp3/wav/…).
Under the default mode, a video without captions is transcribed by AI Fallback Transcription (see mode).

type

string

required

false

default

"auto"

values

captionsaudioauto

description

Where the text may come from.
"auto" (the default) reads the caption track, and when there is none transcribes the audio with AI Fallback Transcription, charged on delivery at 1 credit per started 5 minutes of audio, minimum 1 (a 20-minute video is 4; the 4-hour cap is 48).
"captions" reads an existing caption track only and answers 422 no_captions when there is none: the one mode that never charges for audio.
"audio" skips captions and always uses AI Fallback Transcription, at the same rate.
A caption fetch is always 1 credit.
AI Fallback Transcription on short media may finish inline after a wait of up to 45 seconds; longer work returns 202 with a job to poll or deliver by callback.

type

boolean

required

false

default

true

description

Which form the transcript comes back in.
true (the default) returns the segments array, each with start, duration and text.
false returns a single joined text string instead.
On the single-transcript 200 exactly one of the two is present, never both, since segments already contain every word the joined text does; job results and batch entries carry both text and segments.
The older strings "segment" and "none" mean the same two things and are still accepted.

type

boolean

required

false

default

false

description

Beta.
true adds markdown to the transcript: a title line, a line with the channel, length and link, then paragraphs that each open with their time (linked to that moment on YouTube).
Works with timestamps on or off.
Free.
Absent by default, so leaving it out changes nothing.

type

boolean | { max_tokens, overlap_tokens }

required

false

description

Beta.
Adds chunks: the transcript split into pieces sized for an embedding model or vector store.
Each piece has index, text, start and end (seconds, null when the transcript has no timings), url (opens the video at start on YouTube; the item's link on other platforms) and tokens.
Pieces break between caption lines, never mid-word, and overlap the previous piece slightly.
true uses max_tokens 500 and overlap_tokens 50; an object sets either: max_tokens 100 to 2000, overlap_tokens 0 to 200 and smaller than max_tokens.
Tokens are counted with OpenAI's o200k_base encoding.
Free.
Absent by default.

type

string (https URL)

required

false

description

Where to POST the finished transcript when a request escalates to AI Fallback Transcription, instead of polling the job.
The delivery body is a trimmed envelope - {ok, status, job_id, data} on success, {ok, status, job_id, error} on failure - without the usage and request_id the poll URL adds.
When a signing secret is configured on our side, the body is signed with HMAC-SHA256 over the exact bytes and sent as an X-TranscriptFetch-Signature: sha256=<hex> header so you can verify it came from us.
Must be a public https URL on the standard port; the URL is checked again at delivery time, so an unreachable or private address still gets a 202 but never receives a delivery.
The job stays pollable either way, so a missed delivery is never a lost transcript.

type

boolean

required

false

default

false

description

Legacy alias for "mode", still supported.
true is identical to "mode": "audio" (always AI Fallback Transcription); omitted or false is "mode": "auto", the default, which still uses AI Fallback Transcription when a video has no captions.
Send one or the other, not both.
false never turned the fallback off, which is why the field was replaced: send "mode": "captions" for that.

How a request resolves

1Caption track foundManual or auto-generated captions are read and returned.200
2No captions, under 20 minutesAI Fallback Transcription runs while the request is held open for up to 45 seconds. No polling.200
3Longer, or still running after 45 sAnswers with a job to poll, or POSTs the result to your callback_url. Retrying is safe and hits the cache once it is done.202

POST/api/v2/transcripts/videoidempotent

curl https://transcriptfetch.com/api/v2/transcripts/video \
  -H "Authorization: Bearer $TRANSCRIPTFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video":"dQw4w9WgXcQ"}'

Success

{
  "ok": true,
  "request_id": "req_…",
  "data": {
    "kind": "transcript",
    "video_id": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "title": "Example video",
    "channel": "Example Channel",
    "duration": 212,
    "language": "en",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
    "source": "captions",
    "segments": [
      {
        "start": 0,
        "duration": 3.5,
        "text": "We're no strangers to love"
      }
    ]
  },
  "usage": {
    "credits_spent": 1,
    "balance": 99,
    "bytes": 14233
  }
}

Every YouTube endpoint

Same call, other platforms:TikTok Transcript API·Instagram Transcript API

Frequently asked questions

Which YouTube URLs does the transcript endpoint accept?

Standard watch URLs, youtu.be short links, Shorts, embed and live URLs, and the bare video id. The full list, with an example of each, is on the YouTube URL formats page.

What happens when a YouTube video has no captions?

With the default mode, auto, AI Fallback Transcription transcribes the audio instead. Media under 20 minutes is held open for up to 45 seconds and returns the finished transcript inline; longer media, or a transcription still running when the hold expires, answers 202 with a job_id and poll_url. Send mode captions to fail with no_captions instead.

Do I get timestamps?

Yes by default: data.segments carries start, duration and text for every caption cue. Send timestamps false to get a single data.text string instead; a response never carries both.

How is a YouTube transcript billed?

A transcript served from captions costs 1 credit. One from AI Fallback Transcription is billed by duration, on delivery. A request that fails, or a video that is private, removed or otherwise unavailable, costs nothing.

All endpoints OpenAPI specification AI docs index Pricing and free credits

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.