Video frames always returns 202: mode sync does not give a 200
Sume video frames pins async, so a submit returns 202 even with mode sync. How it differs from video inspect, which waits up to 30 s, and how to poll.
If you send mode: "sync" to Sume video frames and wait for a 200 with the stills, you will not get one. The docs, read 2026-10-05, say submitVideoFramesJob pins communicationMode: "async", so a submit always returns 202. Poll GET /v1/video-frames/:id or GET /v1/jobs/:id/status.
Video inspect behaves differently: its default is sync, and the handler waits up to 30 seconds for a 200, falling back to a 202 if the job is slower.
Side by side
| Tool | Submit returns | Source cap | Frame cap |
|---|---|---|---|
| Video frames | Always 202 | 300 s | 24 frames, at source size unless max_edge |
| Video inspect | 200 within 30 s, else 202 | 1800 s | 24 stills, default max_edge 768 |
When to pick which
- Need a full-size frame at one time, for a first-frame restage: video frames, with no
max_edge. - Need a quick look at a long clip, with probe facts: video inspect.
- Need the probe and an optional transcript in one call: video inspect with
transcribe: true.
A poll loop
import time
def wait_ready(get_status, tries=30, delay=2):
# get_status returns the resource_status of GET /v1/video-frames/:id
for _ in range(tries):
status = get_status()
if status in ("ready", "failed"):
return status
time.sleep(delay)
return "timeout"
states = iter(["processing", "ready"])
print(wait_ready(lambda: next(states), delay=0))Always send an Idempotency-Key on REST so a retry after a dropped connection does not queue a second extract.
Sources
Related posts
More in Media tools
- Video frames: one frame with url null and the job still succeeds
In Sume video frames, a failed instant returns url null while the job completes. How to detect partial results and retry only the missing times.
- Video inspect stills come back 432x768: set max_edge 1920
Video inspect clamps stills to a 768 long edge by default, so a 1080x1920 clip returns 432x768 frames. Set max_edge up to 2160, or use video frames.
- Video inspect frames: at and fps together return a 400 conflict
Sume video inspect frames takes either at[] or fps, never both. The conflict and required codes, the 24-still cap, and how to sample a clip evenly.
- video-inspect 400: frames at and fps together on a Shorts hook
Send frames.at or frames.fps to Sume video-inspect, never both: both returns 400 video_inspect_frames_program_conflict. Pick at[] for a Shorts hook check.
Written by Sume