Same-second thumbnail frames for every episode of a Shorts series

For a Shorts series where each episode has a custom thumbnail, pull one frame per episode at the same second, for example 1.5 seconds in, using Sume POST /v1/video-frames with at: [1.5]. The consistent offset gives the set a consistent look, since every episode opens the same way. YouTube's page on shows says custom thumbnails per Short are allowed in a series (YouTube Help, read 2026-10-05).

The same page says a Shorts series playlist must contain only Shorts, requires a season number, and lists non-serial shows newest to oldest and serial shows oldest to newest. Thumbnails are a separate choice from those rules.

The request

The video frames docs require video_url and exactly one of at[] (1 to 24 values) or fps. format is jpeg by default or png. Without max_edge the frames keep the source size; with it, a long-edge clamp of 16 to 2160 applies. The source must be at most 300 seconds, and a submit always returns 202, so poll GET /v1/video-frames/:id or the jobs status route.

{
  "video_url": "https://media.sume.com/artifacts/artf_demo/episode-03.mp4",
  "at": [1.5],
  "format": "png"
}

One body per episode

Build the bodies in a loop and send each with its own Idempotency-Key, so a retry does not queue a second extract. The script prints bodies and calls nothing.

import json

episodes = ["ep01", "ep02", "ep03"]
for name in episodes:
    body = {"video_url": f"https://media.sume.com/artifacts/artf_demo/{name}.mp4",
            "at": [1.5], "format": "png"}
    print(f"video-frames-{name}", json.dumps(body))

Pitfalls

• An at value outside [0, duration) fails with frame_time_out_of_range and the error reports the probed duration, so keep the offset below your shortest episode.
• An accurate frame is not the same as a good thumbnail. A frame at a speech pause may show a half-closed eye or a blur, so look at the result before you pick it.
• YouTube says a show with no visuals is likely not considered a show, so a thumbnail alone does not stand in for content.
• Frames extracted from the video are not edited. Any title text you add is a design step outside this call.

Limits

Video frames only extracts stills. Setting the thumbnail on YouTube is a step you do in YouTube itself, and its availability depends on the channel's features. The extract is billed by its own compute (container seconds times the Modal list rate times 1.25, plus the platform fee) and never more than the reservation.

If you cut episodes out of a long video first, run video trim on each range and extract the frame from the trimmed file, so the offset is measured from the start of the episode and not from the source. Keep a table of episode, offset and chosen frame so you can redo one later without redoing the set.