Video inspect API: 24 stills max, so 2 fps covers only 12 seconds

Sume video inspect returns at most 24 stills per call, and frames.fps cannot exceed 2. At 2 frames per second, 24 stills cover only 12 seconds. For a 60-second clip, send fps: 0.4 (24 / 60) to spread the 24 stills evenly, or list up to 24 explicit timestamps in frames.at.

The frames program

POST /v1/video-inspect takes a media.sume.com clip you already own. It never re-encodes the source. The frames field has four forms:

Sizing fps

Send only one of at or fps; both together return video_inspect_frames_program_conflict. Samples are mid-bin: with fps: 0.4 on a 60-second clip the bins are 2.5 seconds wide and stills sit at the middle of each. The coverage is 24 / fps seconds, so 12 seconds at 2, 24 seconds at 1, 48 seconds at 0.5, and 60 seconds at 0.4. The source can be up to 1,800 seconds, but 24 stills over 1,800 seconds is fps of about 0.0133, below any useful density; use at for specific moments instead.

Stills default to format: jpeg and a max_edge of 768, which you can set between 64 and 2160. For source-size frames at one time, use the separate frames endpoint.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inspect-60s-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
    "frames": { "fps": 0.4, "seek": "fast" }
  }'

Fast or precise seek

seek defaults to precise, which decodes to the accurate instant. fast moves each still to the keyframe at or before its instant. The still can be earlier by at most one GOP, which the docs put at roughly 0 to 5 seconds on typical sources, but never later. Use fast for a quick look and precise when the timestamp matters. With fast, the result shows sample_times (what the tiles show) next to requested_times.

Picking a program for a clip

For a quick storyboard of a 90-second clip, use fps: 0.2667 (24 / 90) with seek: fast, which gives about one still every 3.75 seconds. For specific moments, such as the first frame and the last second, list them in at. For a thumbnail grid of a 20-second clip, fps: 1 gives 20 stills and stays under the 24 limit.

Remember that an at value outside [0, duration) fails with frame_time_out_of_range and tells you the real duration, so read probe once if you do not know the length. A first inspect with frames: false costs only the probe.

Cost and the transcript option

Inspect is billed by its Modal compute rather than a fixed price: the job reserves a compute ceiling and captures actual container seconds at the Modal list rate times 1.25, plus the platform fee, never more than the hold. transcribe: true adds speech-to-text at $0.01 per audio minute; without a duration_seconds hint (max 600) Sume reserves 1 minute. The default mode is sync with a 30-second wait; a slower job returns 202 and you poll.