Extract 6 thumbnail candidates from a clip with video-frames

To pull thumbnail candidates, POST video_url and an at list of up to 24 timestamps to /v1/video-frames. The job returns 202, and when resource_status is ready each frame is a durable media.sume.com image with t, url, width and height (Video frames). Frames keep the source size unless you send max_edge.

Python, end to end

The clip must already be on media.sume.com. The submit always returns 202, so there is no sync mode to ask for.

import os, time, requests

API = "https://api.sume.com"
h = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}

r = requests.post(API + "/v1/video-frames", headers={**h, "Idempotency-Key": "thumbs-001"}, json={
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "at": [1, 4, 8, 12, 16, 20],
    "format": "jpeg",
    "max_edge": 1280,
})
rid = r.json()["request_id"]
while True:
    o = requests.get(API + "/v1/video-frames/" + rid, headers=h).json()["video_frames"]
    if o["resource_status"] == "ready":
        break
    time.sleep(2)
for f in o["frames"]:
    print(f["t"], f["url"])

Parameters

Behaviour worth knowing

• If one instant fails to extract, that frame's url is null and the job still succeeds.
• A timestamp at or past the duration fails the job with frame_time_out_of_range.
• Billing follows the job's Modal compute, never more than the hold reserved at submit.

Sampling with fps instead of a list

Send fps instead of at[] when you do not know where the good frames are. It must be above 0 and at most 2, and Sume expands it to mid-bin samples at 0.5/fps, 1.5/fps and so on, capped at 24 frames per call. At fps: 0.5 a 20-second clip yields frames at 1, 3, 5 ... 19 seconds, ten candidates.

Send only one of at or fps. The source can be at most 300 seconds. The job reserves its Modal compute ceiling at submit and bills the actual compute, never more than the hold.