---
title: Video analyses
description: Scene-by-scene analysis of an existing public video URL into typed scenes with timings, visuals, and keyframes.
---

Video analyses take a public HTTPS video URL and return a job-backed
scene-by-scene breakdown. Prefer this when an agent needs to *read* an existing
clip (structure, hooks, B-roll insertion points). This is not trend discovery
and not virality prediction, and it does **not** generate video — pair it with
a generation Format when you want a structure-matched remix.

Under the hood a video-understanding model (TwelveLabs Pegasus) watches the MP4
and segments it into typed scenes with descriptions and transcript; ffmpeg then
extracts one JPEG still per scene (`keyframe_url`). Current
`analysis_version` is `1.1`.

```text
POST /v1/video-analyses
GET  /v1/video-analyses/:id
GET  /v1/video-analyses
```

Remote MCP wrappers: `video-analyses_create`, `video-analyses_get`,
`video-analyses_list`. Poll with `jobs_wait` (typical runtime **3–5 minutes**;
poll every **30–60s**).

**Accuracy caveat:** longer videos are less accurate; short clips give the most
reliable results.

## Create an analysis job

Required: `video_url`. Optional: `max_scenes` (2–40, default 24),
`include_transcript` (when `true`, each scene's `audio` carries the spoken
`speech` for that scene; otherwise `audio` is `null`), plus the usual `mode` /
`webhook_url` / `wait_timeout_seconds` communication fields.

```bash
curl -X POST https://api.sume.com/v1/video-analyses \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-analysis-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/ad.mp4",
    "max_scenes": 24
  }'
```

A successful submit returns `202` with a `vana_…` resource id, a
`video_analysis` job (`request_id`), and `status_url` / `result_url`.

Prefer a durable `media.sume.com` URL from media imports
(`POST /v1/media-imports`) or a completed Sume generation artifact. There is no
Higgsfield-style `media_id` intake gate.

## Pricing note

Each accepted analysis reserves and captures **$0.30 USD** of Sume usage under
the current fixed estimate. Confirm live pricing in `GET /v1/catalog` and
OpenAPI.

## Duration limits

| Cap | Behavior |
|---|---|
| Soft (~90s) | Job succeeds; response may include warning `low_confidence_long_video`. |
| Hard (300s) | Rejected after probe with a stable duration error. |

## Unsupported inputs

| Input | Result |
|---|---|
| YouTube URLs | `422 unsupported_source` |
| Non-HTTPS / private / localhost | Rejected at admit |
| Non-video assets | Fail with a stable, agent-legible code |

## Poll and read

```bash
curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/video-analyses/vana_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

curl "https://api.sume.com/v1/video-analyses?limit=20" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

When ready, the resource includes whole-video metadata plus a typed `scenes[]`
array. Each scene has contiguous `start_seconds` / `end_seconds`,
`duration_seconds`, `summary`, `visual`, optional `shot_type` /
`camera_motion`, `on_screen_text`, `audio` (`{ speech, has_speech, has_music }`
when `include_transcript` was requested, otherwise `null`), `keyframe_url` (a
per-scene JPEG still, or `null` with a `keyframe_mirror_failed:scene_N`
warning), and `confidence` (0–1).

## Scopes

| Scope | Operations |
|---|---|
| `video_analyses:write` | `POST /v1/video-analyses` |
| `video_analyses:read` | `GET /v1/video-analyses`, `GET /v1/video-analyses/:id` |

## Related

- [Video captions](/models/video-captions)
- [Trending videos](/models/trending-videos) (discovery metadata only — not analysis)
- [Jobs and results](/workflows/jobs-and-results)
- [Media inputs](/workflows/asset-library)