Shopify fileUpdate previewImageSource: set a video poster

To change the thumbnail of a video already in Shopify Files, call fileUpdate with the file id and a previewImageSource URL. Pull that still from your Sume clip with POST /v1/video-frames, which returns an image on media.sume.com, and send nothing else in the same call: Shopify says you cannot update originalSource and previewImageSource at once.

Shopify facts come from the fileUpdate and Video object references, read 2026-10-02. Sume facts come from Video frames.

What does fileUpdate allow on a video?

The input takes the file id (required), originalSource to replace the content while keeping the same URL, previewImageSource for a video's thumbnail, alt, and referencesToAdd to link products. The file must be in a ready state before you update it, and Shopify locks the file during the update.

One thing on the page is ambiguous. previewImageSource is described as the field for updating a video's thumbnail, yet the capability list says videos and 3D models can only change alt text and product references. Run the call on a test file first and read userErrors before you build a catalog job around it.

How do I pick the poster frame with Sume?

Video frames takes one clip hosted on your workspace's media.sume.com plus exactly one of at[] (1 to 24 explicit seconds) or fps. Each time must satisfy 0 <= t < duration, otherwise the worker fails with frame_time_out_of_range. format is jpeg by default or png, and max_edge clamps the long side between 16 and 2160 pixels.

The route is unbilled, the source clip can be up to 300 seconds, and submit always answers 202. Poll GET /v1/video-frames/{id} until resource_status is ready, then read frames[] for t, url, width and height. If one instant fails, that frame comes back with a null url and the job still succeeds, so check each url.

A clip that is not yet on media.sume.com has to be imported first with POST /v1/media-imports; the route does not fetch the open internet.

What does the full flow look like?

Three calls: extract the still, wait for it, then update the Shopify file. The Shopify mutation is shown as comments in the sketch because it runs in your Shopify client, not against Sume.

# 1) Ask Sume for one still from the clip (unbilled, source up to 300 s)
curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: poster-sku-1042-v1" \
  -d '{ "video_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
        "at": [2.5], "format": "jpeg", "max_edge": 1600 }'

# 2) Poll GET /v1/video-frames/{request_id} until resource_status is "ready",
#    then read frames[0].url (a media.sume.com image).

# 3) Send it to Shopify (variables: id = the video file id, url = frames[0].url)
#    mutation($id: ID!, $url: String!) {
#      fileUpdate(files: [{ id: $id, previewImageSource: $url }]) {
#        files { id fileStatus }
#        userErrors { field message code }
#      }
#    }

What if the poster needs text or a logo?

Video frames returns the pixels of the clip as they are. It adds nothing, so a poster with a price badge or a logo has to be made another way. One option is to feed the extracted still to the image API as an input_references entry and ask for the edit; another is to add the overlay in your own design tool.

Check the result for accuracy before it goes live. A poster that shows a different color or pack size than the product is the sort of mismatch that causes returns and platform complaints. Because the extract is unbilled, you can pull more candidates, but an image edit is a paid generation and counts against your concurrency and queue like any other.

Which frame should be the poster?

A product video often opens on a motion blur or a logo card, so frame 0 is rarely the best poster. Ask for two or three times and compare them: one mid-action, one at the end where the product holds still, one near the start. Because the route is unbilled you lose nothing by pulling several.

Sume's docs note that exact-frame extraction is not clip inspection. If you want a probe plus sampled stills to choose from, use video inspect instead.