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.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/youtube/transcript |
The captions of one YouTube video or Short |
Request & Response
Section titled “Request & Response”Request
Section titled “Request”| 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
languagewithout a region matches any track in that language, the exact one first:entakesen, elseen-GBor another English track.languagewith a region or script matches exactly, or the bare language:en-UStakesen-US, elseen, neveren-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=truereturns only the track in the original spoken language. When YouTube does not show which language that is, the answer isnull, 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, withlanguage=en, with no option and withoriginal_audio=trueis four lookups, cached apart.en-USandEN-usare one.
Response body
Section titled “Response body”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.
Caching and cost
Section titled “Caching and cost”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.
Errors
Section titled “Errors”| 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 |
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"const params = new URLSearchParams({ url: "https://www.youtube.com/watch?v=a1B2c3D4e5F", language: "en" });const res = await fetch(`https://api.megomi.my.id/api/v1/youtube/transcript?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY }, signal: AbortSignal.timeout(60_000),});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/youtube/transcript", params={"url": "https://www.youtube.com/watch?v=a1B2c3D4e5F", "language": "en"}, headers={"x-api-key": "YOUR_API_KEY"}, timeout=60,)print(res.json())<?php$url = "https://api.megomi.my.id/api/v1/youtube/transcript?" . http_build_query(["url" => "https://www.youtube.com/watch?v=a1B2c3D4e5F", "language" => "en"]);$ch = curl_init($url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_TIMEOUT, 60);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("url", "https://www.youtube.com/watch?v=a1B2c3D4e5F")q.Set("language", "en")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/youtube/transcript?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")client := &http.Client{Timeout: 60 * time.Second}resp, _ := client.Do(req){ "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"}{ "success": true, "credits_remaining": 250, "credits_charged": 0, "videoId": "a1B2c3D4e5F", "type": "video", "url": "https://www.youtube.com/watch?v=a1B2c3D4e5F", "transcript": null, "transcript_only_text": null, "language": null}{ "status": 400, "title": "Bad Request", "detail": "url is required: send the video's address as url"}{ "status": 403, "title": "Forbidden", "detail": "this video is age-restricted, and YouTube shows its details only to a signed-in viewer; you were not charged", "requestId": "req_5mPq1XwK8jVcT4nR", "videoId": "a1B2c3D4e5F", "finishReason": "age-restricted"}{ "status": 404, "title": "Not Found", "detail": "the source reports no such video (deleted, or never existed); you were not charged. This answer is cached for an hour", "requestId": "req_5mPq1XwK8jVcT4nR", "finishReason": "not-found"}{ "status": 503, "title": "Service Unavailable", "detail": "no data fetched within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "no-data-fetched"}