Skip to content

API reference

Every route, parameter and field, with request and response examples.

View as Markdown

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, and X-Credits-Remaining once the key is accepted; Retry-After on 202, 409, 429, 503 and 504.
  • Retries: send an optional Idempotency-Key (1 to 128 letters, digits, ., _, : or -) on /v1/transcript and /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 504 processing naming its operation, or 202 with Prefer: respond-async or wait=N (up to 85). The same request again returns the result once ready, free.
  • Errors: {"error": {"code", "message", "param", "details"}, "request_id"}, param and details null when 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 en or pt-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; null when there is no speech.
sourcestring
creator, auto, transcribed, translated or none; 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}. title is null for a short TikTok or Instagram post.
linesarray or null
{start, end, text} lines of up to about 5 seconds; only with include: ["lines"].
on_screen_textarray or null
{start, end, slide, text}. Filled when there is no speech, otherwise with include: ["on_screen_text"].
warningsarray
{code, message}; code is translated, no_speech or incomplete (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"
Response
{
  "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 strings
transcript: add the transcript the values come from.

Response

postobject
The post.
dataobject
Your fields, matching the schema. Any value may be null when the post doesn't support it.
citationsobject
Quotes for each value by path (offer, sponsors[0]): {quote, source, start, end, url}, source being speech, title, description or on_screen.
removedarray of strings
Paths of values dropped because no quote in the post supports them.
warningsarray
{code, message}: no_speech or incomplete.
transcriptobject or null
The transcript the values come from, as /v1/transcript returns it with text and lines set to null (the text is in sections); only with include: ["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"}'
Response
{
  "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 @Fireship with platform.
platformstring
youtube, tiktok or instagram; needed only when author is 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}; followers is null when 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"
Response
{
  "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"
Response
{
  "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.

platformstring
youtube, tiktok or instagram.
typestring
video, photo or carousel.
idstring
The platform's ID for the post.
urlstring
Link to the post.
titlestring or null
The YouTube title; null on 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; null for photos.
thumbnail_urlstring or null
The YouTube thumbnail; null on 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}, where original is true for the creator's own audio. null on YouTube.
statsobject
{views, likes, comments, shares, saves} as the platform shows them. On Instagram, views come only in /v1/posts listings, for Reels; a single post's are null.