frame_time_out_of_range: fix a video frames request

frame_time_out_of_range means one of the times in your at[] list is at or past the end of the clip (or below zero). Sume's video frames tool requires every value to satisfy 0 <= t < duration, so the fix is to read the clip's real duration and keep each time strictly under it.

The rule and the codes below are from the Sume docs page for Video frames, read 2026-09-29, with the probe fields from Video inspect.

Why did my request fail after it was accepted?

The API checks the shape of the body when you submit: at[] must hold 1 to 24 values that are each 0 or more. It cannot know the clip length yet. The worker probes the file afterwards, and only then can it see that a time is out of range, so the job fails with frame_time_out_of_range and names the probed duration.

That is why a submit can return 202 and the job still fail. Poll the job until it is terminal before you read anything.

How do I find the duration first?

Run Video inspect on the same clip. Its result carries a probe object, and with frames: false you get the facts without the stills. Then pick times below the duration. The exclusive upper bound matters: the last valid instant is just before the duration, not on it.

Can I ask for frames without knowing the length?

Yes. Send fps instead of at[]. It samples the clip at mid-bin positions (0.5/fps, 1.5/fps and so on), so every sample lands inside the clip, and the result is capped at 24 frames. The rate must be above 0 and at most 2. Send exactly one of at[] or fps.

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-fps-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "fps": 0.5,
    "format": "png"
  }'

How do I pick safe times for the last frame?

Read source_duration_seconds from the finished result or probe from inspect, then request a time a little under it, for example the duration minus a fraction of a second. Asking for exactly the duration is the classic way to trigger frame_time_out_of_range, because the range is exclusive at the top. If you only need a few evenly spread stills and do not care about exact instants, fps avoids the question entirely.

What else can stop the job?

A source longer than 300 seconds fails duration_out_of_range, even when your times are fine. A single instant whose extract failed comes back with a null url and does not fail the job, so check each frame in frames[] before you use it. Clips over 90 seconds may add a low_confidence_long_video warning, which is not a failure.