Video inspect with fps 0.4 returns 24 stills from a 60-second clip

For a 60-second clip, frames: {fps: 0.4} returns 24 stills, one every 2.5 seconds. 60 x 0.4 = 24, which is the most video inspect returns in a call. The default, with no frames field, returns 8 mid-bin stills instead.

Where the stills land

Sampling is mid-bin: each still is taken at the center of its bin, so the first is at 0.5 / fps = 1.25 s, the second at 3.75 s, and the last at 58.75 s.

Why fps 2 does not give 120

The docs set 0 < fps <= 2 and a hard limit of 24 stills per call. At fps 2, a 60-second clip would want 120 stills, so you receive 24 and lose the rest of the clip. Pick fps from the target count: fps = 24 / duration. For a 90-second clip that is about 0.267.

Request

The default mode is sync and waits up to 30 seconds. If the job is not done in that time you get 202 and poll it. Stills are jpeg by default with max_edge 768; send png or a larger edge when you need detail. Import the clip first with POST /v1/media-imports so it sits on media.sume.com, send an Idempotency-Key header, then poll GET /v1/jobs/:id/status and read GET /v1/jobs/:id/result. The API rejects off-host URLs at admit, so a bad URL fails before any work runs.

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

Limits

• Source up to 1800 s; 24 stills per call.
• Send only one of at[] or fps; both together returns video_inspect_frames_program_conflict.
• An at value outside the clip returns frame_time_out_of_range with the real duration.
• Sume bills probe and stills by their Modal compute; check the live figure in the catalog.

Choosing fps for other lengths

The rule is fps = 24 / duration, capped at 2. A 30-second clip can use fps 0.8 for 24 stills 1.25 seconds apart. A 120-second clip needs fps 0.2, which gives 24 stills 5 seconds apart. A 12-second clip hits the fps cap of 2 at 24 stills, 0.5 seconds apart. When a clip is long, prefer a few explicit at times at the moments you care about, such as the first second, the call to action and the last second. Every media job follows the same lifecycle: submit with an Idempotency-Key, receive a job, poll GET /v1/jobs/:id/status until it is ready, then read GET /v1/jobs/:id/result. A retry with the same key does not queue a second job, so a network error during submit never doubles a charge.