API reference
Every route, parameter and field, with request and response examples.
Basics
- Base URL:
https://api.cleanscript.ai. JSON in and out, snake_case, times in seconds. - Auth:
Authorization: Bearer <key>on every request. Keys are in the dashboard. - Headers on every response:
X-Request-Id,X-Credits-Used, andX-Credits-Remainingonce the key is accepted;Retry-Afteron202,409,429,503and504. - Retries: send an optional
Idempotency-Key(1 to 128 letters, digits,.,_,:or-) on/v1/transcriptand/v1/extract. The same key and request within 6 hours returns the first successful result, free, waiting while it runs; after an error, it runs again. - Long posts: a transcript or extraction still running after 85 seconds answers
504processingnaming its operation, or202withPrefer: respond-asyncorwait=N(up to 85). The same request again returns the result once ready, free. - Errors:
{"error": {"code", "message", "param", "details"}, "request_id"},paramanddetailsnullwhen they don't apply. Codes and what to do: Credits & limits. - OpenAPI:
/openapi.json.
GET /v1/transcript
A post's words as clean text, paragraphs and sections. POST /v1/transcript takes the same parameters as a JSON body. Costs 1 credit per started 10 minutes, or 1 per started minute without captions; see Credits & limits.
Parameters
urlstring required- A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID.
languagestring- The language to read in, such as
enorpt-BR. Default: the language spoken in the post. Without captions in it, the transcript is translated and labelled. includearray of strings- Extra detail:
text(the whole transcript as one string),lines(short timed lines),on_screen_text(text shown in the video). In a query, repeat it:include=text&include=lines.
Response
postobject- The post. See the post object.
languagestring or null- The transcript's language;
nullwhen there is no speech. sourcestringcreator,auto,transcribed,translatedornone; see Transcripts.textstring or null- The paragraphs as one string, separated by blank lines; only with
include: ["text"]. sectionsarray{title, start, end, url, paragraphs}; each paragraph is{start, end, text}.titleisnullfor a short TikTok or Instagram post.linesarray or null{start, end, text}lines of up to about 5 seconds; only withinclude: ["lines"].on_screen_textarray or null{start, end, slide, text}. Filled when there is no speech, otherwise withinclude: ["on_screen_text"].warningsarray{code, message};codeistranslated,no_speechorincomplete(part of the post couldn't be read; retry for all of it).
curl -G https://api.cleanscript.ai/v1/transcript \
-H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
--data-urlencode "url=https://youtu.be/jwnez8HdN7E"{
"post": {
"platform": "youtube",
"type": "video",
"id": "jwnez8HdN7E",
"url": "https://www.youtube.com/watch?v=jwnez8HdN7E",
"title": "Microsoft’s new chip looks like science fiction…",
"description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …",
"author": {
"name": "Fireship",
"handle": "@Fireship",
"url": "https://www.youtube.com/@Fireship"
},
"published_at": "2025-02-21",
"duration": 259,
"thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp",
"sponsored": null,
"sound": null,
"stats": {
"views": 2331993,
"likes": 71026,
"comments": 3300,
"shares": null,
"saves": null
}
},
"language": "en",
"source": "auto",
"text": null,
"sections": [
{
"title": "Microsoft's quantum breakthrough",
"start": 2.19,
"end": 58.11,
"url": "https://youtu.be/jwnez8HdN7E?t=2",
"paragraphs": [
{
"start": 2.19,
"end": 58.11,
"text": "Out of nowhere, Microsoft just announced an impossible new quantum computing chip named Majorana 1, but it's not your average quantum chip. They claim to have created an entirely new state of matter. …"
}
]
}
],
"lines": null,
"on_screen_text": null,
"warnings": []
}POST /v1/extract
The fields you ask for, each with the quotes that support it. Costs 3 credits per started 10 minutes, the transcript included; see Extract fields. Send prompt, preset or schema; a prompt can go with either of the other two.
Body (JSON)
urlstring required- A YouTube, TikTok or Instagram post link, or a bare YouTube video ID.
promptstring- A question or instruction in plain words, up to 4,000 characters. Alone, it returns
{answer, points}; with a schema or preset it adds guidance. presetstring- A published schema:
summary,mentions,ad-breakdown,claims. schemaobject- Your own JSON Schema, object at the root, up to 32 KB.
languagestring- The language to write values in. Default: the transcript's. Quotes stay word for word.
includearray of stringstranscript: add the transcript the values come from.
Response
postobject- The post.
dataobject- Your fields, matching the schema. Any value may be
nullwhen the post doesn't support it. citationsobject- Quotes for each value by path (
offer,sponsors[0]):{quote, source, start, end, url},sourcebeingspeech,title,descriptionoron_screen. removedarray of strings- Paths of values dropped because no quote in the post supports them.
warningsarray{code, message}:no_speechorincomplete.transcriptobject or null- The transcript the values come from, as
/v1/transcriptreturns it withtextandlinesset tonull(the text is insections); only withinclude: ["transcript"].
curl https://api.cleanscript.ai/v1/extract \
-H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtu.be/jwnez8HdN7E", "preset": "mentions"}'{
"post": {
"platform": "youtube",
"type": "video",
"id": "jwnez8HdN7E",
"url": "https://www.youtube.com/watch?v=jwnez8HdN7E",
"title": "Microsoft’s new chip looks like science fiction…",
"description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …",
"author": {
"name": "Fireship",
"handle": "@Fireship",
"url": "https://www.youtube.com/@Fireship"
},
"published_at": "2025-02-21",
"duration": 259,
"thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp",
"sponsored": null,
"sound": null,
"stats": {
"views": 2331993,
"likes": 71026,
"comments": 3300,
"shares": null,
"saves": null
}
},
"data": {
"mentions": [
{
"name": "Microsoft",
"sentiment": "mixed",
"type": "company"
}
],
"recommendations": [],
"sponsors": [
{
"brand": "CodeRabbit",
"code": "FIRESHIP",
"link": "https://bit.ly/41rLUxm",
"offer": "One month free for teams",
"product": "AI code reviews"
}
]
},
"citations": {
"mentions[0]": [
{
"quote": "If it turns out not to be your typical Microsoft BS—and that's a big if—it could be a breakthrough on par with the transistor.",
"source": "speech",
"start": 20.5,
"end": 27.9,
"url": "https://youtu.be/jwnez8HdN7E?t=20"
}
],
"sponsors[0]": [
{
"quote": "It's 100% free for open source projects, but you can get one month free for your team using the code FIRESHIP with the link below.",
"source": "speech",
"start": 249.7,
"end": 258.6,
"url": "https://youtu.be/jwnez8HdN7E?t=249"
},
{
"quote": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm",
"source": "description",
"start": null,
"end": null,
"url": null
}
]
},
"removed": [],
"warnings": [],
"transcript": null
}GET /v1/posts
A creator's recent posts, newest first. Costs 1 credit; see Creator posts.
Parameters
authorstring required- A profile or channel link in any form, or a handle such as
@Fireshipwithplatform. platformstringyoutube,tiktokorinstagram; needed only whenauthoris a handle.limitinteger- How many posts: by default 12, or all of them since
since. At most 30 on YouTube, 35 on TikTok, 12 on Instagram. sincestring- Only posts published on or after this date,
YYYY-MM-DD.
Response
authorobject{platform, name, handle, url, followers};followersisnullwhen the platform doesn't show it.postsarray- Post objects, newest first.
curl -G https://api.cleanscript.ai/v1/posts \
-H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
--data-urlencode "author=https://www.youtube.com/@Fireship"{
"author": {
"platform": "youtube",
"name": "Fireship",
"handle": "@Fireship",
"url": "https://www.youtube.com/@Fireship",
"followers": 4290000
},
"posts": [
{
"platform": "youtube",
"type": "video",
"id": "_5p1_TNSWqQ",
"url": "https://www.youtube.com/watch?v=_5p1_TNSWqQ",
"title": "PewDiePie is setting AI free... and OpenAI is furious",
"description": null,
"author": {
"name": "Fireship",
"handle": "@Fireship",
"url": "https://www.youtube.com/@Fireship"
},
"published_at": "2026-10-05",
"duration": 346,
"thumbnail_url": "https://i.ytimg.com/vi/_5p1_TNSWqQ/hq720_custom_2.jpg?sqp=CMjykdYG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBewv6zstbI10M8d0myK-Ia1GS9sQ",
"sponsored": null,
"sound": null,
"stats": {
"views": 489000,
"likes": null,
"comments": null,
"shares": null,
"saves": null
}
}
]
}GET /v1/account
Your balance and rate limit. Free.
Response
emailstring or null- The account's email.
credits_remaininginteger- Credits left.
rate_limit_per_minuteinteger- Requests a minute this account may send.
curl https://api.cleanscript.ai/v1/account \
-H "Authorization: Bearer $CLEANSCRIPT_API_KEY"{
"email": "you@example.com",
"credits_remaining": 940,
"rate_limit_per_minute": 10
}GET /v1/operations/{id}
A transcript or extraction that outlived its request. Free. status is running (read again after Retry-After), succeeded with result, or failed with error. Kept 6 hours.
The post object
The same object in every response and in every item of a post list. Every field is always present; unknown values are null, never 0.
platformstringyoutube,tiktokorinstagram.typestringvideo,photoorcarousel.idstring- The platform's ID for the post.
urlstring- Link to the post.
titlestring or null- The YouTube title;
nullon TikTok and Instagram. descriptionstring or null- The post's own text: the YouTube description, or the TikTok or Instagram caption.
authorobject{name, handle, url}.published_atstring or null- Publication date,
YYYY-MM-DD. durationnumber or null- Length in seconds;
nullfor photos. thumbnail_urlstring or null- The YouTube thumbnail;
nullon TikTok and Instagram, whose image links expire. sponsoredboolean or null- The platform's paid-partnership or ad flag.
soundobject or null- TikTok and Instagram audio:
{title, author, original}, whereoriginalis true for the creator's own audio.nullon YouTube. statsobject{views, likes, comments, shares, saves}as the platform shows them. On Instagram, views come only in/v1/postslistings, for Reels; a single post's arenull.