POST /api/v1/tiktok/transcript — 1 credit per request
Get the captions TikTok itself has for a video, as WebVTT text, in the language you pick. If TikTok has none in that language, you get the video’s own captions, marked as a fallback.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/tiktok/transcript |
The video’s captions as WebVTT |
Request & Response
Section titled “Request & Response”Query parameters
Section titled “Query parameters”Send these in the URL query string. A request body is ignored.
| Name | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | A TikTok video URL (https://www.tiktok.com/@<handle>/video/<id>) a bare video id, or a mobile share link (vt.tiktok.com, vm.tiktok.com, tiktok.com/t/). At most 2048 characters. A photo post URL is a 400, since a photo has no transcript |
language |
string | No | A two-letter ISO 639-1 code, any case (en, id, es, …). Leave it out for the video’s own captions. Anything else, including en-US or eng, is a 400 |
With language, you get the captions TikTok has in exactly that language: the original track first, or a TikTok translation if that is all there is. If there is no track in that language, you get the video’s own captions instead, in their own language, as a normal 200 with result.fallback: true. Check result.fallback or result.language before you treat the text as the language you asked for. Without language, you get the video’s own captions, never a translation.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
requestId |
string | Opaque ID for this request (req_…). Quote it when reporting a problem |
itemId |
string | Resolved TikTok item ID |
status |
string | "success" — the only value a 200 response carries |
coalesced |
boolean | true if this request attached to an already-in-flight lookup for the same video |
cached |
boolean | true if served from a recent lookup of the same video and language |
result.id |
string | Video ID, equal to itemId |
result.url |
string | Canonical TikTok video URL, when the creator handle is available |
result.transcript |
string | WebVTT text with timestamps. At most 256 KiB |
result.language |
string | Two-letter language of the captions returned, when TikTok says |
result.source |
string | original (the video’s own captions) or translated (a TikTok translation) |
result.fallback |
boolean | true when you asked for a language the video has no captions in and these are its own captions instead. result.language says which language they are in. Absent otherwise |
result.duration |
integer | Video length in seconds, when TikTok reports it |
finishReason |
string | target-found on a fresh answer; absent on a cached one |
success |
boolean | Always true on a 200 |
credits_charged |
integer | Credits this request cost; 0 for a video and language your key already paid for |
credits_remaining |
integer | Your balance after this request |
cached_at |
string | When a cached answer was fetched, in UTC with three decimals. Cached answers only |
The request waits for the lookup to finish, up to 45 seconds, so allow at least 30 seconds on your client. Only a 200 is ever charged, and a 200 always carries a transcript, fallback or not. A video with no captions at all, captions too large to return, a caption file that could not be fetched, and every error cost nothing.
Asking again for the same video and language is free for 10 minutes if your key already paid for it. The cache is separate from Video Info: asking for the same video through both is two charges.
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/transcript?url=https://www.tiktok.com/@creator/video/7123456789012345678&language=id" \ -H "x-api-key: YOUR_API_KEY"const params = new URLSearchParams({ url: "https://www.tiktok.com/@creator/video/7123456789012345678", language: "id",});const res = await fetch(`https://api.megomi.my.id/api/v1/tiktok/transcript?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY },});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/tiktok/transcript", params={ "url": "https://www.tiktok.com/@creator/video/7123456789012345678", "language": "id", }, headers={"x-api-key": "YOUR_API_KEY"},)print(res.json())<?php$query = http_build_query([ "url" => "https://www.tiktok.com/@creator/video/7123456789012345678", "language" => "id",]);$ch = curl_init("https://api.megomi.my.id/api/v1/tiktok/transcript?" . $query);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("url", "https://www.tiktok.com/@creator/video/7123456789012345678")q.Set("language", "id")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/tiktok/transcript?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")resp, _ := http.DefaultClient.Do(req){ "requestId": "req_9f1kQ3zP7mLxA2dR", "itemId": "7123456789012345678", "status": "success", "coalesced": false, "cached": false, "result": { "id": "7123456789012345678", "url": "https://www.tiktok.com/@creator/video/7123456789012345678", "transcript": "WEBVTT\n\n00:00:00.000 --> 00:00:02.400\nStopped by the viral pizza place\n\n00:00:02.400 --> 00:00:05.100\nand it is every bit as good as the hype\n", "language": "en", "source": "original", "duration": 89 }, "finishReason": "target-found", "success": true, "credits_charged": 1, "credits_remaining": 249}{ "status": 400, "title": "Bad Request", "detail": "language must be a two-letter ISO 639-1 code" }{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }{ "status": 402, "title": "Payment Required", "detail": "insufficient credit balance", "required": 1, "balance": 0}{ "status": 404, "title": "Not Found", "detail": "TikTok has no captions for this video (none of its own, and none in the language asked for); you were not charged. Captions are checked again after about 10 minutes", "requestId": "req_9f1kQ3zP7mLxA2dR", "finishReason": "no-transcript"}{ "status": 503, "title": "Service Unavailable", "detail": "TikTok lists captions for this video but the file could not be fetched just now; you were not charged", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "transcript-fetch-failed"}Other responses
Section titled “Other responses”| Status | When | finishReason |
What to do |
|---|---|---|---|
404 |
The video has no captions at all: none of its own, and none in the language you asked for | no-transcript |
Not charged. Checked again after about 10 minutes |
404 |
The captions run past 256 KiB of WebVTT | transcript-too-large |
Not charged |
404 |
The video does not exist | — | Not charged |
403 |
TikTok refused the lookup | blocked |
Not charged. Don’t retry blindly |
503 |
The caption file could not be fetched just now. It says nothing about whether captions exist | transcript-fetch-failed |
Not charged. Resubmit shortly; the response includes Retry-After |
503 |
No answer in time | no-data-fetched |
Not charged. Resubmit shortly, it is free if the work finished |