> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsyncer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Video

> Watch a video with AI: what is said and shown, its hook, structure and key points

## 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

**url** `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.

**media\_id** `integer`

A video in the media library. Send `url` or `media_id`, not both. With `workspace_id`, the video must be in that workspace.

**question** `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`.

**workspace\_id** `integer`

Optional. The workspace whose owner pays. It must be one your token can access. Without it, your own credits are used.

```bash theme={null}
curl -X POST "https://postsyncer.com/api/v1/media/analyze-video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@personalbrandlaunch0/video/7709605548320214286",
    "question": "Turn it into TikTok slide text: 5 to 7 slides."
  }'
```

### Response

`200` - JSON object:

**video** `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).

**credits** `object`

What this watch cost and what the payer has left: `charged` and `left`.

**answer** `string`

The answer to `question`; `null` when none was sent.

**summary** `string`

What the video is about, in two or three sentences.

**language** `string`

The language spoken.

**hook** `string`

What the first seconds do to keep a viewer watching.

**key\_points** `array`

The points it makes, in order.

**structure** `array`

The video's parts in order, each with `at`, `part` (hook, problem, steps, call to action and the like) and `what`.

**on\_screen\_text** `array`

The words written on screen, each with `at` (`m:ss`) and `text`.

**scenes** `array`

What each shot shows, each with `at` and `shows`.

**transcript** `string`

Every word spoken, with `[m:ss]` marks. Empty when nothing is spoken. It comes last, as the longest part.

```json theme={null}
{
  "video": {
    "url": "https://www.tiktok.com/@personalbrandlaunch0/video/7709605548320214286",
    "media_id": null,
    "source": "tiktok",
    "title": "How Long it Actually Takes to Build a Personal Brand.",
    "author": "Personal Brand Launch",
    "duration": 51.3
  },
  "credits": {
    "charged": 2,
    "left": 248
  },
  "answer": "Slide 1: How long it really takes to build a personal brand. ...",
  "summary": "A creator compares how long building a personal brand really takes with what most people expect.",
  "language": "English",
  "hook": "It opens on a contrast: three years in reality, three months in people's heads.",
  "key_points": [
    "A solid personal brand takes about three years.",
    "Results on a new account take about 90 days of posting."
  ],
  "structure": [
    { "at": "0:00", "part": "hook", "what": "States the main contrast." },
    { "at": "0:04", "part": "steps", "what": "Six more expectations against reality." },
    { "at": "0:49", "part": "call to action", "what": "Asks viewers to follow." }
  ],
  "on_screen_text": [
    { "at": "0:00", "text": "HOW LONG it Actually Takes to Build a Personal Brand" },
    { "at": "0:01", "text": "3 Years" }
  ],
  "scenes": [
    { "at": "0:00", "shows": "A woman talks to the camera while the numbers build up beside her." }
  ],
  "transcript": "[0:00] Building a solid personal brand takes three years, but most people think it will take three months. ..."
}
```

### Errors

| Status | When |
| - | - |
| `402` | The payer doesn't have the credits for a watch of this length: `error` is `insufficient_credits`, with `credits_required` and `credits_available`. Nothing was watched. |
| `403` | The token lacks the `media:read` permission, or the payer is on the Free plan (`error` is `plan_limit_reached`). |
| `404` | The post is private, was removed or doesn't exist, or the library video isn't one your token can reach (or isn't in `workspace_id`). |
| `422` | Neither or both of `url` and `media_id`, or `url` isn't an `http(s)` link; the post has no video; the library item isn't a video or is still being processed; the video is longer than 10 minutes or bigger than 300 MB, its format can't be watched (MP4, MOV, WebM, AVI, MPEG, FLV, WMV and 3GP can), its length can't be read, or it couldn't be downloaded from the link; or the watch couldn't finish in time. `message` says which. Nothing was charged. |
| `429` | The payer already has 2 watches running, or started 10 in the last minute. `Retry-After` says how many seconds to wait. Nothing was charged. |
| `503` | The video couldn't be watched just now. Nothing was charged; try again in a minute. |

Needs the `media:read` permission. In MCP this is the [`analyze-video`](https://docs.postsyncer.com/mcp/tools-reference#media) tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.