Video frames on 300 s: fps 0.08 gives 24 stills, 12.5 s apart

On a 300-second clip, send fps: 0.08 to video frames and you get 24 stills, 12.5 seconds apart. 300 x 0.08 = 24, which is the per-call cap, and 300 s is the longest source the route takes.

The sample times

Video frames expands fps into mid-bin samples at 0.5/fps, 1.5/fps, and so on. At 0.08 the first is at 6.25 s and the last at 6.25 + 23 x 12.5 = 293.75 s.

Source size versus inspect

Frames keep the source frame size unless you send max_edge (16 to 2160). Video inspect stills default to a 768 edge. If you only want a quick contact sheet, inspect is enough; if you need to read small text on screen, use frames and format: "png".

Request and polling

The submit pins async mode, so do not send mode: "sync". Poll the job, or read GET /v1/video-frames/:id until resource_status is ready. A single instant that fails gives that frame url: null without failing the job. 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-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: frames-300-001" \
  -d '{"video_url":"https://media.sume.com/artifacts/artf_demo/long.mp4","fps":0.08,"format":"png"}'

Warnings

For a source longer than 90 seconds the job can add low_confidence_long_video to warnings[]. It does not fail the job. A source longer than 300 s fails with duration_out_of_range; trim it first, or use inspect, which takes up to 1800 s.

Choosing between frames and at

The same cap applies to explicit times: at[] takes 1 to 24 values. If you need a frame at every scene change, probe first, then name those instants. For a 300 second clip, 24 evenly spaced frames is a coarse view, one frame per 12.5 seconds, so short flashes between samples are missed. Raise coverage by running two calls with offset programs, for example one at[] list on the half-bins and another on the whole seconds. 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.