Skip to content

YouTube Transcript

POST /api/v1/youtube/transcript — 1 credit per request

Get the captions of a public YouTube video or Short as text with times, in the language you ask for or the language the video is spoken in. Each line has its text, start and end in milliseconds, and a clock time, and the whole transcript is also returned as one joined string. Send the video as a URL, as a query parameter.

Method Path Returns
POST /api/v1/youtube/transcript The captions of one YouTube video or Short
Name Where Type Required Description
url query string (max 300) Yes A YouTube address: youtube.com, www.youtube.com, m.youtube.com, music.youtube.com or youtu.be, in the form watch?v=, youtu.be/, /shorts/, /live/ or /embed/. The scheme is optional. Other query parameters (t, list, si, …) are ignored. There is no video_id parameter on this endpoint
language query string (max 16) No A language code: 2 or 3 letters, optionally with a region or script (en, es, en-US, pt-BR, zh-Hans). Case ignored
original_audio query boolean No true asks for the captions in the language the video is spoken in, and overrides language

Which track is returned

  • language without a region matches any track in that language, the exact one first: en takes en, else en-GB or another English track.
  • language with a region or script matches exactly, or the bare language: en-US takes en-US, else en, never en-GB.
  • Within a match, a track written by a person beats an automatic one.
  • With neither option, you get the track in the video’s original spoken language when YouTube shows which it is, else the first track written by a person, else the first track.
  • original_audio=true returns only the track in the original spoken language. When YouTube does not show which language that is, the answer is null, not a guess.
  • Nothing is ever translated. A track comes back only in a language the video has captions in.
  • A video asked for with language=es, with language=en, with no option and with original_audio=true is four lookups, cached apart. en-US and EN-us are one.

The 200 body is flat, with no requestId, status or result wrapper.

Field Type Description
success boolean true on every 200
credits_charged integer 1 for a transcript. 0 when transcript is null, or for a transcript your key already paid for in the last 15 minutes
credits_remaining integer Your balance after this request
videoId string The video’s id, resolved from the address you sent
type string video, or short for a YouTube Short
url string The video’s address: a watch address, or /shorts/ for a Short
transcript array or null One entry per caption line, in order. null when there is no transcript to give
transcript[].text string The line’s text. Line breaks inside it are spaces
transcript[].startMs, endMs string Where the line starts and ends, in milliseconds, as strings
transcript[].startTimeText string The start as a clock: 0:01, 12:34, 1:02:03
transcript_only_text string or null Every line’s text joined with spaces. null exactly when transcript is
language string or null The captions’ language as YouTube names it (English, Spanish). null exactly when transcript is

A video with no captions to give is a 200 with transcript, transcript_only_text and language all null, and it is not charged. That covers a video with no captions at all, none in the language you asked for, or an original language YouTube does not show.

Nothing is translated or estimated. A video with no track in the language you asked for answers null, never another language’s text.

A transcript is shared across keys for 15 minutes, per video and choice of track. An answer with no transcript is cached for 5 minutes (a video can gain captions), and a video that does not exist for 1 hour. Only a 200 that carries a transcript is charged. Asking again for a transcript your key already paid for is free while it is cached, and resubmitting after a 503 never charges twice. A 403, 404, 429 and 503 are never charged.

Status When What to do
400 No url, an address that is not a video (a channel, playlist), a language that is not a language code, or an original_audio that is not true or false Fix the request
401 No API key, or an unknown one Check your key
402 Your balance cannot cover this plus your unfinished lookups Buy credit
403 The video is age-restricted (finishReason age-restricted), or YouTube asked our service to sign in or refused the request (require-login, http-429, …) Not charged. An age-restricted video will not change on retry. For the other cases, retry after the Retry-After delay
404 No such video, or one that was deleted (not-found) Not charged
429 Rate limit, too many unfinished lookups, or too many lookups from this key that found nothing to give (30 in 15 minutes by default) Slow down. Not charged
503 No answer in time, YouTube failing, or the service paused after repeated refusals. finishReason can be caption-unavailable (YouTube lists captions but the file could not be read just now), player-refused or player-walled (YouTube showed the video but not its caption list), caption-too-large (longer than this endpoint returns, 8 MB or 60,000 lines) or exit-walled Not charged. Resubmit after the Retry-After delay. caption-too-large will not change on retry
Terminal window
curl -X POST "https://api.megomi.my.id/api/v1/youtube/transcript?url=https://www.youtube.com/watch?v=a1B2c3D4e5F&language=en" \
-H "x-api-key: YOUR_API_KEY"
{
"success": true,
"credits_remaining": 249,
"credits_charged": 1,
"videoId": "a1B2c3D4e5F",
"type": "video",
"url": "https://www.youtube.com/watch?v=a1B2c3D4e5F",
"transcript": [
{ "text": "welcome back to the farm and the", "startMs": "160", "endMs": "1920", "startTimeText": "0:00" },
{ "text": "backyard trails we built", "startMs": "1920", "endMs": "3919", "startTimeText": "0:01" },
{ "text": "over an hour in", "startMs": "3723000", "endMs": "3725000", "startTimeText": "1:02:03" }
],
"transcript_only_text": "welcome back to the farm and the backyard trails we built over an hour in",
"language": "English"
}