A 300-second recording in 24 stills: video-frames fps 0.08

To cover a 300-second clip with the most stills one video-frames call allows, send fps 0.08. Sume expands fps into mid-bin sample times, so 300 seconds at 0.08 fps gives 24 stills at 6.25, 18.75, 31.25 seconds and on, one every 12.5 seconds, the last at 293.75. That is the maximum: the route takes at most 24 frames per call, and the source cannot be longer than 300 seconds.

How the sample times come out

The docs describe fps as a sample rate that Sume turns into mid-bin samples (0.5/fps, 1.5/fps and so on) with a limit of 24 frames. Each still sits in the middle of its time slice, so it is never the first or last frame. The fps value must be above 0 and at most 2.

When fps is the wrong tool

An fps program spreads stills evenly. If you need a frame at a known moment, a title card at 4 seconds or a logo at 290, use at[] with 1 to 24 explicit seconds instead. You cannot send both in one call, and the API returns a 400 if you do. Each at value must be at least 0 and less than the clip duration, or the worker fails with frame_time_out_of_range and reports the duration it probed.

• Sources longer than 300 seconds fail with duration_out_of_range.
• Stills keep the source frame size unless you send max_edge (16 to 2160).
• format is jpeg by default, or png for lossless inspection.

The request

Import the clip first, since the route only reads media.sume.com files. A submit always returns 202, and you poll the GET route for the frames.

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-300s-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/webinar.mp4",
    "fps": 0.08,
    "max_edge": 768
  }'

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

Cost and what is not covered

Video frames has no flat per-job price in the docs. Sume bills it by its own Modal compute, and the charge is never more than the hold reserved at submit. For a transcript or probe facts on the same clip, use video inspect, which allows sources up to 1,800 seconds but returns a default of 8 stills at a 768-pixel long edge.

A shorter clip

A 120-second clip at the same 0.08 fps gives about 9 or 10 stills, not 24. Choose fps as 24 divided by the duration to fill the cap: 0.2 for 120 seconds (24 frames, one every 5 seconds) and 0.4 for 60 seconds. The limit of 2 fps only applies to clips of 12 seconds or less if you want all 24 frames.