Etsy two videos per listing: is_multi_video and the Oct 21 date

A listing can now hold two active videos through Etsy's Open API: call uploadListingVideo with is_multi_video set to true, once per video, and a third call while both slots are full returns 409 Conflict. Etsy's Listings Tutorial dates the change: single-video mode before September 21, 2026, a transition window from September 21 to October 21, 2026 in which the flag is available, and multi-video fully implemented after October 21.

Today is October 3, so you are 18 days into that window. This post covers what the tutorial says, what it leaves out, and how to make two different clips with Sume so the second slot is not a duplicate of the first.

What changed in uploadListingVideo?

The tutorial adds multi-video support to the existing uploadListingVideo endpoint rather than creating a new one. Shops can have up to 2 active videos on the same listing at the same time, and each video goes up in its own API call: a single request always associates exactly one video. The is_multi_video query parameter turns the mode on, and it defaults to false.

• Two slots per listing, filled one request at a time.
• is_multi_video is opt-in during the transition and defaults to false.
• A third upload while both slots are taken returns 409 Conflict, so an integration that retries blindly will hit it.

What does the tutorial not tell you?

The multi-video section gives no file format, size, or length limits, so do not infer them from it. Etsy's help center is where those live, and the existing Etsy listing video size post covers them. Treat every clip you make for the second slot as subject to the same limits as the first.

It also does not say what happens to a listing that already has one video when you add another without the flag. The safe reading is the one the tutorial states: set is_multi_video=true on both uploads, and count slots before you send the second request.

What should the second video show?

Etsy does not prescribe roles for the two slots, so this is a suggestion, not a rule. Two clips that repeat each other waste the slot. Give the first the whole item and the second one thing a photo cannot show: a close-up of texture or stitching, scale against a hand, or the item in use.

How do I make two clips with Sume?

Submit two jobs to POST /v1/videos from two different listing photos, each as a first_frame image-to-video request. The Video generation docs list the catalog from GET /v1/videos/models: seedance-2.5 accepts 4 to 30 seconds and gemini-omni-flash-1.1 accepts 3 to 10 seconds. Read supported_durations and supported_aspect_ratios there before you choose, and take the length and aspect ratio from Etsy's help page rather than from this example.

Send a different Idempotency-Key for each slot. The docs say a replay of the same key returns the original job, so a retry after a timeout does not create a third clip for a listing that only holds two. Poll GET /v1/videos/{jobId} until completed, then download from unsigned_urls[0].

If a finished clip runs longer than Etsy allows, Video trim cuts a range into a new MP4 with duration from 0.2 to 900 seconds, at $0.02 per job (the docs say to confirm the live price in GET /v1/catalog).

for ROLE in whole-item close-detail; do
  PHOTO=$( [ "$ROLE" = whole-item ] && echo "$MAIN_PHOTO_URL" || echo "$DETAIL_PHOTO_URL" )
  curl -X POST https://api.sume.com/v1/videos \
    -H "Authorization: Bearer $SUME_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: etsy-$LISTING_ID-$ROLE" \
    -d "{\"model\":\"seedance-2.5\",\"prompt\":\"Slow camera drift, keep the product unchanged\",\"duration\":6,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\",\"frame_images\":[{\"type\":\"image_url\",\"image_url\":{\"url\":\"$PHOTO\"},\"frame_type\":\"first_frame\"}]}"
done

What about disclosure?

Etsy's AI and creativity rules are a separate matter from the upload API, and this post does not summarize them. Read Etsy's current wording before you publish an AI-made clip, and use the AI-generated video disclosure checklist to keep a record of how each clip was made. Keep the item in the clip the item you ship: start from your own photo, as above.