low_confidence_long_video: why video_frames warns past 90 seconds

If GET /v1/video-frames/:id returns warnings: ["low_confidence_long_video"], your source is longer than 90 seconds. It is a warning, not an error: the job still succeeds and the stills are still delivered. The hard stop for this route is 300 seconds, where the worker fails with duration_out_of_range.

The video frames docs say the warning appears "when the source is longer than 90 s (probe reuse)". The same name appears on the retired scene-analysis resource, where the video analyses docs call 90 seconds the soft limit and say longer videos are less accurate. For frame extraction the docs do not explain what confidence means, and we will not guess.

What triggers it, and what does it not?

The trigger is source duration alone, measured by the worker's probe. It is not about frame count, fps, format or max_edge. A 100 second clip with a single at: [5] frame still carries the warning.

It also does not mean a frame is wrong. Frame extraction is an ffmpeg seek at your named time or at the mid-bin times that fps expands to. A frame that fails to extract comes back with url: null for that instant, and even that does not fail the job.

• Over 90 s and up to 300 s: succeeds with low_confidence_long_video.
• Over 300 s: fails with duration_out_of_range after the probe.
• An at value outside [0, duration): fails with frame_time_out_of_range and names the probed duration.

What are the caps across the clip tools?

If you need a still from minute 12 of a 20 minute file, video_frames is the wrong route. Video inspect accepts sources up to 1800 seconds with explicit frames.at timestamps, and its stills default to a 768 pixel long edge.

How do you handle the warning in code?

Decide whether a long source is acceptable for your use. A thumbnail picker for a 2 minute video probably is; an automated QA check that must be exact should treat any warning as a flag for review. Read the resource and branch on warnings.

curl https://api.sume.com/v1/video-frames/$REQUEST_ID \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); v=r.get('video_frames', r); print(v.get('resource_status'), v.get('warnings'))"

Can you avoid it?

Yes, by cutting first. Video trim takes a source up to 1800 seconds and returns a new MP4 for [start, end) at $0.02 per job; a trimmed segment under 90 seconds goes into video_frames without the warning. The cost is one more job and a new artifact. If you only need a few stills from a long file, using inspect with explicit at times is cheaper in steps.

Video frames itself is unbilled, so the warning has no cost implication. The only cost of ignoring it is whatever you lose if the docs' concern about long sources turns out to matter for your footage.

How does this differ from the frame_time_out_of_range error?

They are unrelated checks that people confuse. frame_time_out_of_range is about your request: an at value that is negative or at or beyond the probed duration. The worker names the duration in the error so you can correct the timestamp. low_confidence_long_video is about the file: it fires on length alone and never blocks the job.

If you see both on one run, read the error first. A warning only appears on a job that succeeded, so a failed job will not carry it. Also remember that fps sampling expands to mid-bin instants (0.5/fps, 1.5/fps, and so on) capped at 24 frames, so on a 200 second clip an fps of 0.1 yields 20 stills spread across the whole file; the warning does not change that spacing.