Pick a listing main image from a product clip with video-frames

To pull a candidate main image out of a product clip, import the clip to Sume, then call POST /v1/video-frames with 1 to 24 times in at[] or an fps of at most 2, and read frames[{t,url,width,height}] when the job is ready. Pick the sharpest, best-lit frame by eye, and run it through your own listing rules. Sume does not check marketplace specs for you.

A generated try-on or product clip often has one frame that is better than the rest: the product fully visible, the hands out of the way, the face turned right. A listing needs a still, and re-generating one costs money, so extracting it from a clip you already paid for is the cheap route.

What the endpoint accepts

The source has to be one workspace media.sume.com clip, not an open-internet URL. If your clip lives elsewhere, import it first with POST /v1/media-imports. The source can be up to 300 seconds. Submit always returns 202, so you poll GET /v1/video-frames/{id} until resource_status is ready (read 2026-10-03, Sume video-frames docs).

Pass either at[] or fps, not both. Each value in at[] must be at least 0 and less than the clip duration, or the worker fails with frame_time_out_of_range and tells you the probed duration. format is jpeg by default or png, and max_edge can be set from 16 to 2160 to cap the long edge; leave it out to keep the source size.

The call

Send an Idempotency-Key so a retry does not queue a second extract.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-frames-sku-1042-v1" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/tryon-1042.mp4",
    "at": [0.5, 1.5, 2.5, 3.5, 4.5, 5.5],
    "format": "png"
  }'

Choosing the frame

If one instant fails to extract, its url comes back null and the job still succeeds, so skip nulls rather than failing the batch. Frames come back as durable images at source size, so a 720p clip gives 720p stills. That is fine for a social card but may be too small for a listing that wants a large main image; check the destination's own image requirements, which this post does not state, before you rely on a frame.

Use a short checklist: is the product complete in frame, is the edge clean, are hands and sleeves natural, is there motion blur. If no frame passes, generate the still directly with the Image API instead. For the checks on a try-on look, the QC checklist applies as it is, and the which-call-returns-which post shows when a still is the better output to ask for.

Contact sheets and a faster first pass

If you do not know where the good frame is, start with fps instead of a hand-picked list. An fps of 0.5 on a 12 second clip samples at mid-bin points and returns about six frames, capped at 24. Look at the sheet, pick the best two moments, then run a second call with at[] set a little either side of them to find the sharpest frame.

This two-pass habit is cheap. Video frames is billed by its Modal compute and holds a ceiling at submit, so a small extract costs little. Use max_edge to keep first-pass frames small and drop it for the pass you plan to publish.

Keep the source clip's artifact URL and the chosen time with the frame, so you can reproduce the pick later. If a try-on clip was the source, the frame you choose is a generated image, and your own labelling rules for generated images apply to it.

Where a still is better made directly

A frame from a clip is a compromise: the clip was composed for motion, not for a main image. If you need a hero shot with the product centred, lit evenly and shown at the largest size your platform shows, generate a still on purpose with the Image API and keep the clip for the video slot. Use frame extraction for secondary images, social cards and thumbnails, where a good moment is enough.