How do I pull a Shorts thumbnail frame from an episode with Sume?

Send POST /v1/video-frames with the episode's Sume-hosted video_url and at set to the second you want. The result is a durable media.sume.com image at the source size.

YouTube's Help page on Shorts series describes a series as a Shorts-only playlist with seasons and episodes, with each episode at most 180 seconds (read 2026-10-07). A frame from the episode is a quick start for the cover art; read YouTube's page for the exact artwork rules.

The request

You send video_url and exactly one of at[] or fps. Options are format (jpeg by default or png) and max_edge from 16 to 2160. A submit always returns 202; poll GET /v1/video-frames/:id. When resource_status is ready, each frame has t, url, width and height; a frame that failed has a null url without failing the job.

The job does not use an admission seat, and it is billed by its Modal compute, so there is no fixed price to quote. The hold is the maximum.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ep01-thumb-001" \
  -d '{"video_url": "https://media.sume.com/artifacts/artf_demo/ep01.mp4", "at": [0, 2.5]}'

Picking the frame

Ask for several times, say 0, 2.5 and 5, and choose the one with a clear face. Frames come out at the clip's own size, so a vertical episode gives a vertical still. Put the title on afterwards with your image tool of choice.

Details are on the Video frames page.

• Request three times, keep one.
• Use png if you will edit the still.
• Name the output with the episode number.

From a still to a cover

A frame is a start, not a finished cover. Add the episode number and a short title using your design tool, and keep the face in the upper two thirds so it survives a crop. Use the same layout for every episode, so a viewer who sees three covers in a row knows they belong together.

Extract at a few times, such as 0, 2.5 and 5 seconds. A frame at time 0 is often a lead-in and a frame at 2.5 seconds is more often a face with an expression. The extract returns width and height for each frame, so your layout code can check the crop before it uploads anything.

Because the job is billed by compute and holds a ceiling at submit, treat it as a small cost per episode and test one before you run fifty. See the trailer post for a related cheap cut.

Common mistakes

Do not send both at and fps; the API accepts exactly one. Do not pass a URL that is not on media.sume.com. Do not forget the idempotency key on REST, since a retry could queue a second extract.

A frame that fails comes back with a null url and the job still succeeds, so check each entry.