Supported URLs
All URL formats- Post URL
https://www.tiktok.com/@creator/video/7398765432101234567 - vm.tiktok.com share link
https://vm.tiktok.com/ZMexample/ - vt.tiktok.com share link
https://vt.tiktok.com/ZSexample/ - Video ID
7398765432101234567
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 (seemode).
- 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 theaudiowith AI Fallback Transcription, charged on delivery at 1 credit per started 5 minutes ofaudio, minimum 1 (a 20-minute video is 4; the 4-hour cap is 48)."captions"reads an existing caption track only and answers 422no_captionswhen there is none: the one mode that never charges foraudio."audio"skipscaptionsand 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 thesegmentsarray, each with start, duration and text.falsereturns a single joinedtextstring 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.
trueaddsmarkdownto 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
timestampson 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,
nullwhen 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.
trueusesmax_tokens500 andoverlap_tokens50; an object sets either:max_tokens100 to 2000,overlap_tokens0 to 200 and smaller thanmax_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 andrequest_idthe 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. trueis identical to"mode":"audio"(always AI Fallback Transcription); omitted orfalseis"mode":"auto", the default, which still uses AI Fallback Transcription when a video has no captions.- Send one or the other, not both.
falsenever turned the fallback off, which is why the field was replaced: send"mode":"captions"for that.
- Legacy alias for
How a request resolves
- Caption track foundThe video's caption track is read and returned.200
- No captionsAI Fallback Transcription runs while the request is held open for up to 45 seconds. No polling.200
- 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
Success
{
"ok": true,
"request_id": "req_…",
"data": {
"kind": "transcript",
"video_id": "7690953765293231373",
"url": "https://www.tiktok.com/@khanacademy/video/7690953765293231373",
"platform": "tiktok",
"title": "Lower Car Payment? Check the Loan First! The best deal isn’t always the one with the lowest monthly payment. Learn more in Khan Academy’s Monthly payment versus total cost lesson! Link in bio",
"channel": "khanacademy",
"duration": 35,
"language": "eng-US",
"thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ogAAeIAg75qA92HwwcidCiuCVDcBDgDS5EfCnn~tplv-tiktokx-origin.image",
"source": "captions",
"segments": [
{
"start": 0.5,
"duration": 3.98,
"text": "Wait, this payment for my new car is way lower?"
},
{
"start": 4.78,
"duration": 2,
"text": "Yeah, I'm going with this payment."
},
{
"start": 6.781,
"duration": 2.86,
"text": "Okay, but look at that loan closely."
}
]
},
"usage": {
"credits_spent": 1,
"balance": 656,
"bytes": 1893
}
}Every TikTok endpoint
- POSTTranscriptText or segments for a TikTok video.
- POSTSearchFind TikTok videos by keyword.
- POSTProfile VideosList a creator's videos, newest first.
- POSTProfile MonitorNew videos from a creator, by webhook.
Same call, other platforms:YouTube Transcript APIInstagram Transcript API
Frequently asked questions
Which TikTok URLs are accepted?
Full video URLs (tiktok.com/@user/video/<id>), the vm.tiktok.com and vt.tiktok.com short links TikTok's share sheet produces, and the bare numeric video id. The URL formats page lists each with an example.
Does TikTok have captions, or does every transcript need AI Fallback Transcription?
Many TikTok videos carry a caption track, and the endpoint reads it first: the response says source captions and costs 1 credit. When there is none, AI Fallback Transcription transcribes the audio on the same request and source says audio.
Will a TikTok request answer 202 and make me poll?
Rarely. TikTok is short-form, so the request is held open and the finished transcript is returned inline whether or not the media length could be read. Only a transcription that outlasts the hold answers 202 with a job to poll.
Can I transcribe a private TikTok, or one behind an age gate?
No. Only public videos are reachable. A private, removed or region-locked video fails with a clear error and costs nothing.