Video analyses keyframes: one still per second per scene

Every scene in a legacy Sume video analysis carries keyframes, an array of { t, url } stills covering every whole second of that scene, and a keyframe_url, the representative pick. The pick is the 1-second sample nearest 40% of the scene, or the historical 40% pick on scenes shorter than one second. If you want a thumbnail candidate per scene, keyframe_url is already chosen; if you want a better one, the per-second list is where you look.

Thumbnails matter more for series. YouTube's September 23 post lists custom thumbnails among the Shorts series features (YouTube Blog, read 2026-10-04), so each episode needs its own cover.

What the docs promise, and the ceiling

From the video analyses docs: ffmpeg extracts at least one JPEG still per second of each scene, so the stills ceiling is the 300-second hard duration cap, about 300 JPEGs. A failed second comes back with url: null and a warning keyframe_mirror_failed:scene_N:t_T, and does not drop the scene. If the representative still fails, keyframe_url is null with keyframe_mirror_failed:scene_N.

Choose a cover yourself

Where keyframe_url is null or just not right, take the nearest working per-second still to the point you want, skipping failed seconds.

scene = {
    "start_seconds": 10,
    "end_seconds": 20,
    "keyframe_url": None,
    "keyframes": [
        {"t": 10, "url": "https://media.sume.com/artifacts/a/10.jpg"},
        {"t": 11, "url": None},
        {"t": 12, "url": "https://media.sume.com/artifacts/a/12.jpg"},
        {"t": 14, "url": "https://media.sume.com/artifacts/a/14.jpg"},
    ],
}

span = scene["end_seconds"] - scene["start_seconds"]
target = scene["start_seconds"] + 0.4 * span
usable = [k for k in scene["keyframes"] if k["url"]]
best = min(usable, key=lambda k: abs(k["t"] - target))
print("target", target, "->", best["t"], best["url"])

This resource is legacy: dest answers 410 video_analysis_retired on create and production accepts it until a later change. For new work take stills from video frames (exact times, source size) or video inspect. The thumbnail path is covered in pick a thumbnail frame.