Skip to main content
POST

Analyze Video

Watch a video with AI and get back what it says and shows: the words spoken, the text on screen, the scenes, the hook, the structure and the key points, and an answer to your question when you send one. The video is either:
  • a public post with a video, by its link (url): TikTok, Instagram, YouTube, X, Facebook and more. The post does not need to be yours or in your workspace;
  • a video in your media library (media_id), such as one you uploaded.
Videos up to 10 minutes long can be watched. Nothing is stored: the video is not added to your media library. Use it to turn a video into posts, slides or a script, to see why a video works, or to get its transcript.

Cost

Watching costs AI credits by what the watch really costs, which depends on the video’s length: at least 1 credit, about 2 credits for a one-minute video. The answer’s credits says what it cost and what is left. The owner of the workspace in workspace_id pays; without it, your own credits are used. If the payer can’t cover a watch of the video’s length, the request fails before the video is watched. Watching is on the paid plans. On the Free plan the request is refused with 403 plan_limit_reached.

How long it takes

A watch takes about 15 to 60 seconds, and up to 85 seconds for a long video. Set your client’s timeout to at least 100 seconds: a request sent again is a second watch. A watch that can’t finish in that time is refused with 422 and charges nothing; try a shorter clip.

Limits

Each payer (the workspace’s owner, or you without workspace_id) can have 2 watches running at once and start 10 a minute. Past either, the request is refused with 429 and a Retry-After header (seconds). Nothing is charged.

Body

string
A public post link with a video, starting with https:// or http:// (e.g. https://www.tiktok.com/@user/video/7709605548320214286). Send url or media_id, not both.
integer
A video in the media library. Send url or media_id, not both. With workspace_id, the video must be in that workspace.
string
Optional (up to 2000 characters). What you want to find out or get from the video, e.g. “Turn it into TikTok slide text: 5 to 7 slides”. The answer is in answer.
integer
Optional. The workspace whose owner pays. It must be one your token can access. Without it, your own credits are used.

Response

200 - JSON object:
object
The video watched: url (the link, or null for a library video), media_id (or null), source (the platform, or media library), title, author and duration (seconds).
object
What this watch cost and what the payer has left: charged and left.
string
The answer to question; null when none was sent.
string
What the video is about, in two or three sentences.
string
The language spoken.
string
What the first seconds do to keep a viewer watching.
array
The points it makes, in order.
array
The video’s parts in order, each with at, part (hook, problem, steps, call to action and the like) and what.
array
The words written on screen, each with at (m:ss) and text.
array
What each shot shows, each with at and shows.
string
Every word spoken, with [m:ss] marks. Empty when nothing is spoken. It comes last, as the longest part.

Errors

Needs the media:read permission. In MCP this is the analyze-video tool.