Skip to content

Transcripts

Get a post's words as clean text, paragraphs and sections, in the language you read.

View as Markdown

Ask for a transcript

Send the post link as url, with GET and query parameters or POST and a JSON body. Both return the same thing.

curl -G https://api.cleanscript.ai/v1/transcript \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@nytimes/video/7489936234010135854" \
  -d language=fr -d include=lines

url takes any link form: watch, Shorts, youtu.be and embed links, TikTok video, photo and share links, Instagram post, Reel and TV links, with or without https://, or a bare YouTube video ID.

TikTok and Instagram are in beta: they can be slower or fail more often. Failed requests are free.

What comes back

  • sections: the video's chapters, or sections we title from the content (one section for a short post), each with start, end, a url to that moment and its paragraphs. A paragraph is one point of the talk, usually 100 to 250 words, with its times: ready to store as a retrieval chunk.
  • text: the paragraphs as one string, separated by blank lines, with include: ["text"]. The SDKs' transcript_text() / transcriptText() build it from sections.
  • lines: short timed lines of up to about 5 seconds, with include: ["lines"]: for subtitles, or to find the moment something is said. A translation keeps the same lines and times.
  • source and language: where the words came from (below) and their language.
  • warnings: only when the result differs from what you asked: translated, no_speech, or incomplete when part of the post couldn't be read (a slide, the video, or sung lines that may remain as speech). Ask again to get all of it; that request is charged again.
  • post: title, description, author, date, duration and stats, the same object on every route.

Where the words come from

source Meaning
creator The creator's own captions, returned as written.
auto The platform's automatic captions, corrected: misheard words and names fixed (names spelled as the post's title and description spell them), punctuation added, fillers, stutters and false starts removed. Numbers are never changed, and nothing is added beyond a word or two the captions missed.
transcribed The post had no usable captions, so we transcribed its audio, then corrected it.
translated A translation into the language you asked for: the platform's own when it has one, otherwise ours. A translated warning names the original language.
none No speech (music only, or silent). sections is empty, a no_speech warning says so, and on_screen_text holds the text shown in the video.

Posts without captions are transcribed up to 15 minutes long; a longer one returns no_captions.

Languages

Leave language out to get the language spoken in the post. Set it (en, fr, pt-BR) to read in another language: you get the post's own captions in that language when they exist, otherwise a translation (the platform's, or ours), line by line with the same times. A language we can't translate into returns language_unavailable, with the post's languages in details.available.

Times are seconds from the start of the post. YouTube's automatic captions time every word, so there a line starts with its first word and ends with its last; other lines are timed by their captions. A change of speaker starts a new line and a new paragraph. A section's url opens YouTube at that moment; TikTok and Instagram can't link to a moment, so there url is the post link.

On-screen text

on_screen_text lists the text shown in the video with its times (by slide for photos and carousels); text shown again later is listed again. It is filled automatically when a post has no speech. With speech, ask for it with include: ["on_screen_text"] (videos up to 15 minutes), which adds 1 credit, only when all of it was read.

Cost

1 credit per started 10 minutes of video, or 1 per started minute without captions; our translation adds 1 per started 10 minutes. See Credits & limits.