Pinterest video Pin cover: cover_image_key_frame_time, set in seconds

When you create a video Pin through the Pinterest API, you can choose the cover by giving cover_image_key_frame_time, an integer number of seconds. If the number is beyond the video length, Pinterest uses the last frame. Sume's video-frames extracts stills at the instants you list, so you can look at the candidates and pass the best second.

What does the cover field accept?

The spec lists three cover options for video media: cover_image_key_frame_time (keyframe timestamp in seconds, minimum 0, integer), cover_image_url, and cover_image_data with a content type for base64. The spec says that if the entered time exceeds the video duration, the last frame is used.

How do I pick the second?

Extract stills with POST /v1/video-frames using at for the instants you want (up to 24) and a jpeg format. Look at the returned frames and choose one. Since the Pinterest field is whole seconds, pick candidates at integers such as 1, 2 and 3.

import json, os, urllib.request

body = {
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "at": [
        1,
        2,
        3,
        4
    ],
    "format": "jpeg",
    "max_edge": 720
}
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": "pin-cover-001",
    },
    method="POST",
)
print(urllib.request.urlopen(req).read().decode())

When should I use a URL instead?

Use cover_image_url when the best cover is not a frame from the video, for example a designed title card made with Sume's images API. Host it where Pinterest can fetch it.

What should I verify?

Test with one Pin and look at the result in the feed. The video frames guide documents the extract.