TikTok video_cover_timestamp_ms: pick the cover frame in seconds

Preview a few candidate moments with POST /v1/video-frames (its at[] is in seconds), pick the still you prefer, and send that time times 1000 as video_cover_timestamp_ms. TikTok's reference says the field "Specifies which frame (measured in milli-seconds) will be used as the video cover."

What does the field mean?

The quote is the whole definition the page gives, so nothing else about it is assumed here: it selects a frame by time, in milliseconds, of the video you post. The unit difference is the trap, because Sume's frame times are in seconds.

How do I preview candidates?

Submit up to 24 times in at[]; each must be at least 0 and below the clip duration or the worker fails with frame_time_out_of_range. The result lists frames[{t,url,width,height}], so t is the number you convert.

Video frames is unbilled, always answers 202, and reads only sources up to 300 seconds.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cover-pick-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/post.mp4",
    "at": [0.5, 1.5, 2.5, 3.5],
    "max_edge": 720
  }'

What if the video is longer than 300 seconds?

Frames refuses a longer source as duration_out_of_range. If the moment you want is early, cut that stretch with https://docs.sume.com/models/video-trim and preview that. The cover time is measured on the video you post, so a preview cut only helps if it starts at 0 of the video you post.

What are the risks?

The page quoted here does not say how a time between two frames is resolved, so pick a time from a preview and re-check the cover on TikTok after posting. Sume does not post to TikTok; the Direct Post call and the token are yours.

What does a short checklist look like?

Because the field is a single number, the failure modes are unit errors and out-of-range values. This list keeps both visible before the upload call.

• Convert seconds to milliseconds by multiplying by 1000, and keep the result an integer.
• Keep the time below the length of the file you send to TikTok, not the source clip.
• Store the chosen frame's artifact id next to the post id to see later which moment was picked.
• Re-preview if you re-cut the video, because timings shift with the cut.