YouTube thumbnail from a video frame API: extract, upscale

To make a YouTube thumbnail from a video frame with the Sume API, extract the frame at source size with POST /v1/video-frames (one at time, format: "png", and no max_edge), then send the frame's URL to POST /v1/image-upscale-1.0/upscale if it is smaller than the 3840×2160 that YouTube recommends for video thumbnails. A 1920×1080 frame needs upscale_factor: 2 to get there.

YouTube's rules are quoted from its Help page Add custom thumbnails on YouTube, which can change. Sume facts come from the Video frames, Video inspect, and Image API docs and the Sume API reference. All were read on 2026-09-27. The frames call itself is covered in How to extract frames from a video.

What size and format does YouTube want for a thumbnail?

YouTube says a custom thumbnail should be as large as possible; it is also used as the preview image in the embedded player. Uploading your own needs a verified account, and custom Shorts thumbnails can currently be added only in YouTube Studio on a computer. A vertical video with a 16:9 custom thumbnail gets an auto-generated 4:5 thumbnail on the home, explore, and subscription pages, so match the thumbnail's shape to the video's.

Which videos can the frame come from?

Only clips already in your workspace on media.sume.com, such as an earlier Sume job's output: an avatar video or a Timeline 1.0 render. The frame tools do not fetch from the open internet, and the asset upload routes are hidden from the public API. Media imports (POST /v1/media-imports) do not take YouTube links or arbitrary video URLs; both are rejected with unsupported_platform.

• Video frames reads sources up to 300 seconds and refuses longer ones with duration_out_of_range.
• For a source of up to 1,800 seconds, ask video inspect for the still instead: a frames object with at, format: "png", and max_edge set to the source's long edge. Inspect's max_edge stops at 2160.

How do I pick and extract the frame?

Look first, for free: an inspect with no frames field returns eight mid-bin stills at a 768-pixel long edge, unbilled. Then extract the chosen moment at source size with video frames, also unbilled.

Poll GET /v1/video-frames/:id until resource_status is ready, then read frames[0]: its url, plus the width and height that set the upscale factor below. A failed instant comes back with url: null without failing the job, so check it first.

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

How do I upscale the frame to YouTube's size?

Send the frame's URL as image_url to Image Upscale 1.0. The field takes a public HTTPS image, and completed Sume jobs return public artifacts under media.sume.com. upscale_factor runs from 1 to 4 (default 2). output_format is png (the default), jpg, or webp; YouTube's page names JPG and PNG.

• A 16:9 frame needs 3840 divided by its width: 2 for a 1920×1080 frame, 3 for a 1280×720 frame.
• A 9:16 Shorts frame needs 2160 divided by its width: 2 for 1080×1920, 3 for 720×1280.
• The factor stops at 4, so a 16:9 frame under 960 pixels wide cannot reach 3840 in one job. Any frame at least 640 pixels wide already meets YouTube's minimum.
• Read the image from GET /v1/jobs/:id/result. Each artifact has a url, plus width, height, and size_bytes when reported; check size_bytes against the 2 MB mobile limit.
• The upscale costs $0.20 per image on API pricing, plus a 5.5% agent fee by default. AI image upscaler API covers its other fields.

curl -X POST https://api.sume.com/v1/image-upscale-1.0/upscale \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: thumbnail-upscale-001" \
  -d '{
    "image_url": "https://media.sume.com/artifacts/artf_demo/frame.png",
    "upscale_factor": 2,
    "output_format": "jpg"
  }'

Can I restyle the frame instead of upscaling it?

Yes, with an image model. Pass the frame to POST /v1/images as a reference: input_references: [{ "type": "image_url", "image_url": { "url": "…" } }]. Reference URLs must be public HTTPS, and a model whose input_references maximum is 0 refuses them. On openai/gpt-image-2.5, which takes up to 16 references, image_size: { "width": 3840, "height": 2160 } fits the custom-pixel rules exactly: both edges are multiples of 16, 3840 is the maximum edge, and 8,294,400 pixels is the ceiling.

The result is a newly generated image, not your frame. The call blocks for up to 30 seconds, and a slower generation answers 202 with a job to poll. You pay the model's endpoint pricing times n; Image generation with reference images covers the request.

What does this workflow not do?

The Sume steps end at a finished image file:

• No outside video: the source must be Sume-hosted.
• No batch upscaling: Image Upscale 1.0 takes one image_url per job, up to a factor of 4.
• No upload to YouTube. You add the file in YouTube Studio, and YouTube limits how many custom thumbnails a channel can upload each day.