Telegram sendVideo cover and start_timestamp: pick a poster frame

Telegram's sendVideo has a cover parameter for the image shown with the video and a start_timestamp integer for the second where playback begins in the message. If you generate clips, you can pick the cover by extracting a few stills with Sume's video-frames, choosing one, and sending that file as cover. The same call can set start_timestamp to skip a slow opening.

What do cover and start_timestamp do?

The Bot API describes cover as the cover for the video in the message and accepts a file_id, an HTTP URL or a new multipart upload. start_timestamp is an integer: the timestamp in seconds from which the video plays in the message. The caption is limited to 0-1024 characters. The incoming Video object exposes the same two ideas as a cover array of photo sizes and a start_timestamp field.

How do I pull candidate covers?

Call POST /v1/video-frames with at set to a list of instants (1 to 24 of them) or an fps of at most 2. Pick jpeg or png with format, and max_edge between 16 and 2160 to size the stills. The call returns 202 with a job id; read GET /v1/video-frames/:id until resource_status is ready, then use frames[{t,url,width,height}]. The extract is listed as unbilled in the docs.

import json, os, urllib.request

body = {
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "at": [
        0.5,
        2,
        4,
        6
    ],
    "format": "jpeg",
    "max_edge": 1080
}
req = urllib.request.Request(
    "https://api.sume.com/v1/video-frames",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["SUME_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "cover-candidates-001",
    },
    method="POST",
)
print(urllib.request.urlopen(req).read().decode())

How do I choose the frame?

Prefer a frame with the subject in focus and no motion blur, and avoid the first frame of an AI clip when it is a faded or still-resolving image. The t value on each returned frame tells you which instant it came from, which also gives you a sensible start_timestamp if the opening is weak. One frame can come back with a null url; the job still succeeds, so skip it.

What should I check?

Download the chosen frame and send it as the cover upload for the video. Test one send before automating it, because Telegram may change method fields between releases; the video frames guide documents the extract side.