Analyze a video by URL: import to Sume media first, then inspect

Sume's video inspect will not fetch an arbitrary URL. It reads one clip already on your workspace's media.sume.com, and an off-host link such as https://example.com/ad.mp4 is rejected when the request is admitted. Import the video first with POST /v1/media-imports, then pass the resulting media.sume.com URL as video_url.

Google's Gemini API changelog (read 2026-10-02) says its model can navigate a video timeline on demand. Sume's inspect is simpler: probe facts, stills and an optional transcript from a clip it holds.

What is the order of calls?

Three steps, and the table shows what to expect at each one.

What errors should I expect?

Idempotency-Key is required on the create. source_not_found means a dead or foreign media.sume.com URL. Transcribing a silent clip returns inspect_source_has_no_audio, so check probe.has_audio first. Sending ffmpeg fields such as vf or crf returns ffmpeg_fields_rejected, because the server compiles ffmpeg itself.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: probe-001" \
  -d '{"video_url": "https://media.sume.com/artifacts/artf_demo/ad.mp4", "frames": false}'

Is the legacy analysis route the same thing?

No. The older video analyses route returns typed scenes and is marked legacy in the docs, and new clip inspection goes through video inspect.

Can an agent do this?

Yes. The hosted MCP exposes video_inspect and media-imports_create; a write needs an idempotency_key, and a 202 response is polled with jobs_wait.

Why does Sume require an import?

Reading only from media.sume.com keeps the inspect job away from arbitrary hosts and gives every clip a stable, workspace-owned URL. It also means the stills and transcript refer to a file that will not change underneath you, so a review done today can be repeated next month.

The cost of that design is one extra call. For a batch, import every video first, store the returned URLs next to your own ids, and run the inspect jobs from that list.

What do I do with the results?

Store the job id, the media.sume.com URL and the date with the findings. If you need to explain a result later, you can fetch the same job again with GET /v1/video-inspect and the id, rather than running a new one.

What does a batch look like?

Import all the videos, keep a list of the original address and the returned media.sume.com URL, run a probe-only inspect on each to read its duration and whether it has audio, and then run the fuller inspect only where it will help. Probe and stills are unbilled, so the cheap pass costs nothing and tells you which clips are worth a transcript.