Media
Analyze Video
Watch a video with AI: what is said and shown, its hook, structure and key points
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.
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’scredits 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 with422 and charges nothing; try a shorter clip.
Limits
Each payer (the workspace’s owner, or you withoutworkspace_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
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.A video in the media library. Send
url or media_id, not both. With workspace_id, the video must be in that workspace.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.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:
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).The video’s parts in order, each with
at, part (hook, problem, steps, call to action and the like) and what.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.