YouTube Shorts thumbnail grabber: pull a frame with video frames

To grab thumbnail candidates from a Short, import the clip, then call POST /v1/video-frames with at set to the seconds you want. You get durable image artifacts, as png (lossless) or jpeg, at the source frame size unless you cap the long edge with max_edge. The docs list the call as unbilled.

YouTube's help page says custom Shorts thumbnails can currently only be added in YouTube Studio on a computer, and the account must be verified. Sume only produces the image; you still upload it there. Facts below are from Video frames, read 2026-09-30.

How do I request frames at named times?

Required: video_url (a media.sume.com artifact or asset in your workspace, so import first with POST /v1/media-imports) and exactly one of at[] or fps. at takes 1 to 24 values, each 0 or more, and every value must be before the clip's duration or the worker fails with frame_time_out_of_range.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: short-thumb-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/short.mp4",
    "at": [0.5, 3, 6.5],
    "format": "png",
    "max_edge": 2160
  }'

What size and format come back?

Omitting max_edge keeps the source size. max_edge is a long-edge clamp from 16 to 2160. On a 9:16 Short, a 2160 long edge works out to 1215 by 2160 (arithmetic, not a documented output). If the Short is already smaller, check the returned width and height for each frame; each entry in frames carries t, url, width and height.

How do I find the good frame?

Ask for a spread, such as every second or three or four chosen moments, and look at the stills. If one instant fails to extract, it comes back with a null url and the job still succeeds. For a ready-made size reference see Shorts vertical thumbnail 9:16, and for the general flow thumbnail from a video frame.

Can an agent do this over MCP?

Yes. Hosted MCP exposes video_frames_create and video_frames_get. The flow is video_frames_create, then jobs_wait, then video_frames_get. Writes need an idempotency_key.