{ "components": { "responses": { "Error400": { "content": { "application/json": { "example": { "error": { "code": "invalid_url", "message": "This YouTube link doesn't name a video. Use a watch, Shorts or youtu.be link.", "param": "url" }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This YouTube link doesn't name a video. Use a watch, Shorts or youtu.be link.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "No API key. Send your API key as: Authorization: Bearer ." }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "No API key. Send your API key as: Authorization: Bearer .", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error402": { "content": { "application/json": { "example": { "error": { "code": "insufficient_credits", "details": { "credits_remaining": 0, "credits_required": 1, "top_up_url": "https://cleanscript.ai/pricing" }, "message": "This request needs 1 credit and the account has 0 left. Buy more at https://cleanscript.ai/pricing." }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This request needs 1 credit and the account has 0 left. Buy more at https://cleanscript.ai/pricing.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error404": { "content": { "application/json": { "example": { "error": { "code": "video_unavailable", "details": { "reason": "private" }, "message": "This video is private.", "param": "url" }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This video is private.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error409": { "content": { "application/json": { "example": { "error": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used for a different request. Use a new key.", "param": "Idempotency-Key" }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This Idempotency-Key was used for a different request. Use a new key.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error422": { "content": { "application/json": { "example": { "error": { "code": "language_unavailable", "details": { "available": [ "en" ] }, "message": "This post has no captions in xx, and we can't translate into it.", "param": "language" }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This post has no captions in xx, and we can't translate into it.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "This account is limited to 60 requests a minute. Retry in 12 seconds." }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This account is limited to 60 requests a minute. Retry in 12 seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } }, "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error503": { "content": { "application/json": { "example": { "error": { "code": "source_unavailable", "message": "Couldn't reach YouTube just now. Retry in a minute." }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Couldn't reach YouTube just now. Retry in a minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } }, "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "Error504": { "content": { "application/json": { "example": { "error": { "code": "timeout", "message": "Processing took too long. No credits were used; retry, the result is often ready by then." }, "request_id": "5f0c7d1e-0b7a-4a39-9c1e-3c1f2b8f6a10" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Processing took too long. No credits were used; retry, the result is often ready by then.", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } } }, "schemas": { "Account": { "properties": { "credits_remaining": { "title": "Credits Remaining", "type": "integer" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "rate_limit_per_minute": { "title": "Rate Limit Per Minute", "type": "integer" } }, "required": [ "email", "credits_remaining", "rate_limit_per_minute" ], "title": "Account", "type": "object" }, "Author": { "properties": { "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle, such as @Fireship.", "title": "Handle" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "title": "Name" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile or channel link.", "title": "Url" } }, "required": [ "name", "handle", "url" ], "title": "Author", "type": "object" }, "Citation": { "properties": { "end": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End" }, "quote": { "description": "The words as they appear in the source, verbatim.", "title": "Quote", "type": "string" }, "source": { "enum": [ "speech", "title", "description", "on_screen" ], "title": "Source", "type": "string" }, "start": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Seconds; null for the title, the description and slide text.", "title": "Start" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Link to the moment (YouTube) or the post; null for the title, the description and slide text.", "title": "Url" } }, "required": [ "quote", "source", "start", "end", "url" ], "title": "Citation", "type": "object" }, "Creator": { "properties": { "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Subscribers or followers; null when the platform doesn't show them.", "title": "Followers" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle, such as @Fireship.", "title": "Handle" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "title": "Name" }, "platform": { "enum": [ "youtube", "tiktok", "instagram" ], "title": "Platform", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile or channel link.", "title": "Url" } }, "required": [ "platform", "name", "handle", "url", "followers" ], "title": "Creator", "type": "object" }, "ErrorDetail": { "properties": { "code": { "examples": [ "video_unavailable" ], "title": "Code", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details" }, "message": { "title": "Message", "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param" } }, "required": [ "code", "message" ], "title": "ErrorDetail", "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" } }, "required": [ "error", "request_id" ], "title": "ErrorResponse", "type": "object" }, "ExtractRequest": { "additionalProperties": false, "properties": { "include": { "description": "Add the transcript used, as returned by /v1/transcript.", "items": { "const": "transcript", "type": "string" }, "maxItems": 1, "title": "Include", "type": "array" }, "language": { "anyOf": [ { "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "type": "string" }, { "type": "null" } ], "description": "The language to write values in. Default: the transcript's. Quotes stay verbatim.", "title": "Language" }, "preset": { "anyOf": [ { "enum": [ "summary", "mentions", "ad-breakdown", "claims" ], "type": "string" }, { "type": "null" } ], "description": "A published schema: /schemas/.json on the website.", "title": "Preset" }, "prompt": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "A question or instruction in plain language. Alone, it returns {answer, points}; with a schema or preset it adds guidance.", "examples": [ "What does it say about pricing?" ], "title": "Prompt" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Your own JSON Schema (object root, at most 32 KB).", "title": "Schema" }, "url": { "description": "A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID.", "examples": [ "https://youtu.be/jwnez8HdN7E" ], "maxLength": 2048, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "ExtractRequest", "type": "object" }, "ExtractResponse": { "properties": { "citations": { "additionalProperties": { "items": { "$ref": "#/components/schemas/Citation" }, "type": "array" }, "description": "Quotes for each value, keyed by its path (offer, claims[1]). An object in a list is cited once as a whole (speakers[0]). null, [], false and 0 need no citation.", "title": "Citations", "type": "object" }, "data": { "additionalProperties": true, "description": "Matches the schema. Any value may be null when the post doesn't support it.", "title": "Data", "type": "object" }, "post": { "$ref": "#/components/schemas/Post" }, "removed": { "description": "Paths of values dropped because no quote in the post supports them.", "items": { "type": "string" }, "title": "Removed", "type": "array" }, "transcript": { "anyOf": [ { "$ref": "#/components/schemas/Transcript" }, { "type": "null" } ], "description": "The transcript the values come from; only with include: [\"transcript\"]." }, "warnings": { "items": { "$ref": "#/components/schemas/Warning" }, "title": "Warnings", "type": "array" } }, "required": [ "post", "data", "citations", "removed", "warnings", "transcript" ], "title": "ExtractResponse", "type": "object" }, "Post": { "description": "The same object in every response, and in each item of a creator's post list.", "properties": { "author": { "$ref": "#/components/schemas/Author" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The post's own text: the YouTube description, or the TikTok or Instagram caption.", "title": "Description" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Length in seconds; null for photos.", "title": "Duration" }, "id": { "description": "The platform's ID for the post.", "title": "Id", "type": "string" }, "platform": { "enum": [ "youtube", "tiktok", "instagram" ], "title": "Platform", "type": "string" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication date, YYYY-MM-DD.", "examples": [ "2025-02-20" ], "title": "Published At" }, "sound": { "anyOf": [ { "$ref": "#/components/schemas/Sound" }, { "type": "null" } ], "description": "TikTok and Instagram audio; null on YouTube." }, "sponsored": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "The platform's paid-partnership or ad flag; null when unknown.", "title": "Sponsored" }, "stats": { "$ref": "#/components/schemas/Stats", "description": "Counts the platform shows; null where it doesn't (never 0 for unknown)." }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube thumbnail; null on TikTok and Instagram, whose image links expire.", "title": "Thumbnail Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube title; null on TikTok and Instagram.", "title": "Title" }, "type": { "enum": [ "video", "photo", "carousel" ], "title": "Type", "type": "string" }, "url": { "description": "Link to the post.", "title": "Url", "type": "string" } }, "required": [ "platform", "type", "id", "url", "title", "description", "author", "published_at", "duration", "thumbnail_url", "sponsored", "sound", "stats" ], "title": "Post", "type": "object" }, "PostsResponse": { "properties": { "author": { "$ref": "#/components/schemas/Creator" }, "posts": { "description": "The creator's recent posts, newest first. Each is the same `post` object as in every other response.", "items": { "$ref": "#/components/schemas/Post" }, "title": "Posts", "type": "array" } }, "required": [ "author", "posts" ], "title": "PostsResponse", "type": "object" }, "ScreenText": { "description": "Text shown on screen: timed for videos, by slide for photos and carousels.", "properties": { "end": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End" }, "slide": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based slide of a photo or carousel post; null for videos.", "title": "Slide" }, "start": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start" }, "text": { "title": "Text", "type": "string" } }, "required": [ "start", "end", "slide", "text" ], "title": "ScreenText", "type": "object" }, "Section": { "properties": { "end": { "title": "End", "type": "number" }, "paragraphs": { "items": { "$ref": "#/components/schemas/TimedText" }, "title": "Paragraphs", "type": "array" }, "start": { "title": "Start", "type": "number" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The creator's chapter title, or a generated one; null for a post too short to divide.", "title": "Title" }, "url": { "description": "Link to this moment: YouTube opens at it; on TikTok and Instagram it is the post link.", "title": "Url", "type": "string" } }, "required": [ "title", "start", "end", "url", "paragraphs" ], "title": "Section", "type": "object" }, "Sound": { "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "original": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when the sound is the creator's own audio, false for licensed music.", "title": "Original" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "title", "author", "original" ], "title": "Sound", "type": "object" }, "Stats": { "properties": { "comments": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Comments" }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Likes" }, "saves": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Saves" }, "shares": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Shares" }, "views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Views" } }, "required": [ "views", "likes", "comments", "shares", "saves" ], "title": "Stats", "type": "object" }, "TimedText": { "properties": { "end": { "title": "End", "type": "number" }, "start": { "description": "Seconds from the start of the post.", "title": "Start", "type": "number" }, "text": { "title": "Text", "type": "string" } }, "required": [ "start", "end", "text" ], "title": "TimedText", "type": "object" }, "Transcript": { "properties": { "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The language of `text`; null when there is no speech.", "examples": [ "en" ], "title": "Language" }, "lines": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TimedText" }, "type": "array" }, { "type": "null" } ], "description": "Caption-sized lines with their times; only with include: [\"lines\"].", "title": "Lines" }, "on_screen_text": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ScreenText" }, "type": "array" }, { "type": "null" } ], "description": "Text shown in the video, with its times, or by slide for photos and carousels. Filled automatically when there is no speech; otherwise only with include: [\"on_screen_text\"].", "title": "On Screen Text" }, "sections": { "items": { "$ref": "#/components/schemas/Section" }, "title": "Sections", "type": "array" }, "source": { "description": "creator: the creator's captions, as written. auto: the platform's automatic captions, corrected. transcribed: no usable captions, so we transcribed the audio, then corrected it. translated: a translation, the platform's own when it has one, otherwise ours (a `translated` warning names the original language). none: no speech.", "enum": [ "creator", "auto", "transcribed", "translated", "none" ], "title": "Source", "type": "string" }, "text": { "description": "The whole transcript, paragraphs separated by blank lines.", "title": "Text", "type": "string" }, "warnings": { "description": "Only when the result differs from what was asked.", "items": { "$ref": "#/components/schemas/Warning" }, "title": "Warnings", "type": "array" } }, "required": [ "language", "source", "text", "sections", "lines", "on_screen_text", "warnings" ], "title": "Transcript", "type": "object" }, "TranscriptRequest": { "additionalProperties": false, "properties": { "include": { "description": "Extra detail: caption lines, on-screen text.", "items": { "enum": [ "lines", "on_screen_text" ], "type": "string" }, "maxItems": 2, "title": "Include", "type": "array" }, "language": { "anyOf": [ { "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "type": "string" }, { "type": "null" } ], "description": "The language to read in, such as en or pt-BR. Default: the language spoken in the post. When the post has no captions in this language, the transcript is translated and labelled.", "title": "Language" }, "url": { "description": "A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID.", "examples": [ "https://youtu.be/jwnez8HdN7E" ], "maxLength": 2048, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "TranscriptRequest", "type": "object" }, "TranscriptResponse": { "description": "`post` first, then the transcript.", "properties": { "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The language of `text`; null when there is no speech.", "examples": [ "en" ], "title": "Language" }, "lines": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TimedText" }, "type": "array" }, { "type": "null" } ], "description": "Caption-sized lines with their times; only with include: [\"lines\"].", "title": "Lines" }, "on_screen_text": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ScreenText" }, "type": "array" }, { "type": "null" } ], "description": "Text shown in the video, with its times, or by slide for photos and carousels. Filled automatically when there is no speech; otherwise only with include: [\"on_screen_text\"].", "title": "On Screen Text" }, "post": { "$ref": "#/components/schemas/Post" }, "sections": { "items": { "$ref": "#/components/schemas/Section" }, "title": "Sections", "type": "array" }, "source": { "description": "creator: the creator's captions, as written. auto: the platform's automatic captions, corrected. transcribed: no usable captions, so we transcribed the audio, then corrected it. translated: a translation, the platform's own when it has one, otherwise ours (a `translated` warning names the original language). none: no speech.", "enum": [ "creator", "auto", "transcribed", "translated", "none" ], "title": "Source", "type": "string" }, "text": { "description": "The whole transcript, paragraphs separated by blank lines.", "title": "Text", "type": "string" }, "warnings": { "description": "Only when the result differs from what was asked.", "items": { "$ref": "#/components/schemas/Warning" }, "title": "Warnings", "type": "array" } }, "required": [ "post", "language", "source", "text", "sections", "lines", "on_screen_text", "warnings" ], "title": "TranscriptResponse", "type": "object" }, "Warning": { "properties": { "code": { "enum": [ "translated", "no_speech", "uncorrected", "incomplete" ], "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "Warning", "type": "object" } }, "securitySchemes": { "APIKey": { "description": "Your CleanScript API key: Authorization: Bearer . Keep it server-side.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Turn a YouTube, TikTok or Instagram post into a clean transcript, or into the fields you ask for with a verified quote and a link to the moment for each. Send any post link to `/v1/transcript` for paragraphs grouped into sections, or to `/v1/extract` with a plain-language `prompt`, a `preset` or your own JSON Schema. Authenticate with `Authorization: Bearer `. Every response carries `X-Request-Id`, `X-Credits-Used` and `X-Credits-Remaining`; errors share one shape, `{\"error\": {\"code\", \"message\", \"param\", \"details\"}, \"request_id\"}`, and use no credits. An optional `Idempotency-Key` makes retries safe, and asking again for the same thing within 6 hours is free. TikTok and Instagram are in beta.", "title": "CleanScript API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/account": { "get": { "description": "Free: uses no credits and no rate-limit allowance, and works with no credits left.", "operationId": "getAccount", "responses": { "200": { "content": { "application/json": { "example": { "credits_remaining": 940, "email": "you@example.com", "rate_limit_per_minute": 10 }, "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "Successful Response", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "summary": "Check a key and the credits left", "tags": [ "account" ] } }, "/v1/extract": { "post": { "description": "Fields from a post, each value with the quotes that support it and a link to the moment. Send a `prompt` (a question in plain language: returns {answer, points}), a `preset` (summary, mentions, ad-breakdown or claims) or your own JSON `schema`; a prompt can also guide a preset or schema. Every quote is checked against the post; a value without a verified quote is dropped and listed in `removed`. Values are written in `language` (default: the transcript's), quotes stay verbatim. Costs 3 credits per started 10 minutes; a post without captions costs 1 per started minute plus 2 per started 10 minutes. Asking again for the same thing within 6 hours is free.", "operationId": "extract", "parameters": [ { "description": "Optional. Retrying with the same key and request within 6 hours returns the first successful result without charging again; a failed request can be retried with the same key.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "preset": { "summary": "A preset", "value": { "preset": "mentions", "url": "https://youtu.be/jwnez8HdN7E" } }, "prompt": { "summary": "A question in plain language", "value": { "prompt": "What does it say about how the chip works?", "url": "https://youtu.be/jwnez8HdN7E" } }, "schema": { "summary": "Your own fields", "value": { "language": "fr", "schema": { "properties": { "creator": { "description": "Who created the language.", "type": "string" }, "release_year": { "type": "integer" }, "use_cases": { "items": { "type": "string" }, "type": "array" } }, "required": [ "creator", "release_year", "use_cases" ], "type": "object" }, "url": "https://www.youtube.com/watch?v=x7X9w_GIm1s" } } }, "schema": { "$ref": "#/components/schemas/ExtractRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "citations": { "mentions[0]": [ { "end": 27.9, "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, "url": "https://youtu.be/jwnez8HdN7E?t=20" } ], "sponsors[0]": [ { "end": 258.6, "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, "url": "https://youtu.be/jwnez8HdN7E?t=249" }, { "end": null, "quote": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm", "source": "description", "start": null, "url": 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" } ] }, "post": { "author": { "handle": "@Fireship", "name": "Fireship", "url": "https://www.youtube.com/@Fireship" }, "description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …", "duration": 259.0, "id": "jwnez8HdN7E", "platform": "youtube", "published_at": "2025-02-21", "sound": null, "sponsored": null, "stats": { "comments": 3300, "likes": 71026, "saves": null, "shares": null, "views": 2331993 }, "thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp", "title": "Microsoft’s new chip looks like science fiction…", "type": "video", "url": "https://www.youtube.com/watch?v=jwnez8HdN7E" }, "removed": [], "transcript": null, "warnings": [] }, "schema": { "$ref": "#/components/schemas/ExtractResponse" } } }, "description": "Successful Response", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Extract fields from a post, with quotes", "tags": [ "extract" ] } }, "/v1/posts": { "get": { "description": "A creator's recent posts, newest first. `author` is a profile or channel link in any form (youtube.com/@name, /channel/UC…, /c/name, tiktok.com/@name, instagram.com/name), or a handle with `platform`. Each item is the same `post` object the other routes return, so a post's `url` goes straight into /v1/transcript and /v1/extract. `since` keeps posts published on or after that date. One request yields at most 30 posts on YouTube (videos, not Shorts; the dates of older videos are approximate), 35 on TikTok and 12 on Instagram, so `limit` cannot be higher than that. The list can be up to 10 minutes old. A profile that doesn't exist, or is private, is a 404 `author_not_found` with `details.reason`. Costs 1 credit; the same call within 10 minutes is free.", "operationId": "listPosts", "parameters": [ { "description": "A profile or channel link in any form, or a handle such as @Fireship with `platform`.", "in": "query", "name": "author", "required": true, "schema": { "description": "A profile or channel link in any form, or a handle such as @Fireship with `platform`.", "examples": [ "https://www.youtube.com/@Fireship" ], "maxLength": 300, "title": "Author", "type": "string" } }, { "description": "Needed only when `author` is a handle rather than a link.", "in": "query", "name": "platform", "required": false, "schema": { "anyOf": [ { "enum": [ "youtube", "tiktok", "instagram" ], "type": "string" }, { "type": "null" } ], "description": "Needed only when `author` is a handle rather than a link.", "title": "Platform" } }, { "description": "How many posts. At most 30 on YouTube, 35 on TikTok, 12 on Instagram.", "in": "query", "name": "limit", "required": false, "schema": { "default": 12, "description": "How many posts. At most 30 on YouTube, 35 on TikTok, 12 on Instagram.", "maximum": 35, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Only posts published on or after this date, YYYY-MM-DD.", "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Only posts published on or after this date, YYYY-MM-DD.", "examples": [ "2026-10-01" ], "title": "Since" } }, { "description": "Optional. Retrying with the same key and request within 6 hours returns the first successful result without charging again; a failed request can be retried with the same key.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "author": { "followers": 4290000, "handle": "@Fireship", "name": "Fireship", "platform": "youtube", "url": "https://www.youtube.com/@Fireship" }, "posts": [ { "author": { "handle": "@Fireship", "name": "Fireship", "url": "https://www.youtube.com/@Fireship" }, "description": null, "duration": 346.0, "id": "_5p1_TNSWqQ", "platform": "youtube", "published_at": "2026-10-05", "sound": null, "sponsored": null, "stats": { "comments": null, "likes": null, "saves": null, "shares": null, "views": 489000 }, "thumbnail_url": "https://i.ytimg.com/vi/_5p1_TNSWqQ/hq720_custom_2.jpg?sqp=CMjykdYG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBewv6zstbI10M8d0myK-Ia1GS9sQ", "title": "PewDiePie is setting AI free... and OpenAI is furious", "type": "video", "url": "https://www.youtube.com/watch?v=_5p1_TNSWqQ" } ] }, "schema": { "$ref": "#/components/schemas/PostsResponse" } } }, "description": "Successful Response", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "List a creator's recent posts", "tags": [ "posts" ] } }, "/v1/transcript": { "get": { "description": "The post's spoken words as clean text: paragraphs grouped into sections (the creator's chapters, or generated ones), with times and links to each moment. Human captions come back as written; automatic captions and our transcriptions are corrected. A post without captions is transcribed from its audio; a post without speech returns its on-screen text. Pass `language` to read in another language (translated when the post has no captions in it). Costs 1 credit per started 10 minutes, or 1 per started minute for a post without captions; a translation the platform doesn't provide adds 1 per started 10 minutes. Asking again for the same thing within 6 hours is free. The same as POST, for curl and agents: `include` may be repeated.", "operationId": "getTranscript", "parameters": [ { "description": "A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID.", "in": "query", "name": "url", "required": true, "schema": { "description": "A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID.", "examples": [ "https://youtu.be/jwnez8HdN7E" ], "maxLength": 2048, "title": "Url", "type": "string" } }, { "description": "The language to read in, such as en or pt-BR. Default: the language spoken in the post. When the post has no captions in this language, the transcript is translated and labelled.", "in": "query", "name": "language", "required": false, "schema": { "anyOf": [ { "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "type": "string" }, { "type": "null" } ], "description": "The language to read in, such as en or pt-BR. Default: the language spoken in the post. When the post has no captions in this language, the transcript is translated and labelled.", "title": "Language" } }, { "in": "query", "name": "include", "required": false, "schema": { "default": [], "items": { "enum": [ "lines", "on_screen_text" ], "type": "string" }, "maxItems": 2, "title": "Include", "type": "array" } }, { "description": "Optional. Retrying with the same key and request within 6 hours returns the first successful result without charging again; a failed request can be retried with the same key.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "language": "en", "lines": null, "on_screen_text": null, "post": { "author": { "handle": "@Fireship", "name": "Fireship", "url": "https://www.youtube.com/@Fireship" }, "description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …", "duration": 259.0, "id": "jwnez8HdN7E", "platform": "youtube", "published_at": "2025-02-21", "sound": null, "sponsored": null, "stats": { "comments": 3300, "likes": 71026, "saves": null, "shares": null, "views": 2331993 }, "thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp", "title": "Microsoft’s new chip looks like science fiction…", "type": "video", "url": "https://www.youtube.com/watch?v=jwnez8HdN7E" }, "sections": [ { "end": 58.11, "paragraphs": [ { "end": 58.11, "start": 2.19, "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. …" } ], "start": 2.19, "title": "Microsoft's quantum breakthrough", "url": "https://youtu.be/jwnez8HdN7E?t=2" } ], "source": "auto", "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. …\n\n…", "warnings": [] }, "schema": { "$ref": "#/components/schemas/TranscriptResponse" } } }, "description": "Successful Response", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Get a post's transcript (query parameters)", "tags": [ "transcript" ] }, "post": { "description": "The post's spoken words as clean text: paragraphs grouped into sections (the creator's chapters, or generated ones), with times and links to each moment. Human captions come back as written; automatic captions and our transcriptions are corrected. A post without captions is transcribed from its audio; a post without speech returns its on-screen text. Pass `language` to read in another language (translated when the post has no captions in it). Costs 1 credit per started 10 minutes, or 1 per started minute for a post without captions; a translation the platform doesn't provide adds 1 per started 10 minutes. Asking again for the same thing within 6 hours is free.", "operationId": "createTranscript", "parameters": [ { "description": "Optional. Retrying with the same key and request within 6 hours returns the first successful result without charging again; a failed request can be retried with the same key.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "simple": { "summary": "A transcript", "value": { "url": "https://youtu.be/jwnez8HdN7E" } }, "translated": { "summary": "In another language, with caption lines", "value": { "include": [ "lines" ], "language": "fr", "url": "https://www.tiktok.com/@nytimes/video/7489936234010135854" } } }, "schema": { "$ref": "#/components/schemas/TranscriptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "language": "en", "lines": null, "on_screen_text": null, "post": { "author": { "handle": "@Fireship", "name": "Fireship", "url": "https://www.youtube.com/@Fireship" }, "description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …", "duration": 259.0, "id": "jwnez8HdN7E", "platform": "youtube", "published_at": "2025-02-21", "sound": null, "sponsored": null, "stats": { "comments": 3300, "likes": 71026, "saves": null, "shares": null, "views": 2331993 }, "thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp", "title": "Microsoft’s new chip looks like science fiction…", "type": "video", "url": "https://www.youtube.com/watch?v=jwnez8HdN7E" }, "sections": [ { "end": 58.11, "paragraphs": [ { "end": 58.11, "start": 2.19, "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. …" } ], "start": 2.19, "title": "Microsoft's quantum breakthrough", "url": "https://youtu.be/jwnez8HdN7E?t=2" } ], "source": "auto", "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. …\n\n…", "warnings": [] }, "schema": { "$ref": "#/components/schemas/TranscriptResponse" } } }, "description": "Successful Response", "headers": { "X-Credits-Remaining": { "description": "Credits left on the account.", "schema": { "type": "integer" } }, "X-Credits-Used": { "description": "Credits this request used.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "This request's ID, for support.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Get a post's transcript", "tags": [ "transcript" ] } } }, "security": [ { "APIKey": [] } ], "servers": [ { "url": "https://api.cleanscript.ai" } ] }