Etsy Video Size and Length: The Listing Video Rules and the 21 October API Change

Etsy states its listing video rules on How to Add Listing Videos, last edited on 1 July 2026, and its listing help page gives a second length. Each line below is Etsy's own sentence with the page it comes from.

Two details catch out the guides that rank for this question. Several still say one video per listing, while the current page says 2. And Etsy's own pages disagree on the shortest clip: 3 seconds on the video page, 5 on the listing page. The video page does not say whether shapes other than 2:1 and 1:2 are refused.

Aim for a clip of 5 to 15 seconds with no sound. That length meets both of Etsy's pages, which differ only on the minimum, and Etsy strips the audio from every listing video, so a soundtrack never reaches a buyer.

A short clip of the product in its scene, with light or a slow camera move, fills that time and keeps the print readable.

Use a mockup clip where Etsy allows a mockup photo: a design of yours that a production partner prints onto a base item. Etsy's image rules say nothing about video, so the photo rule is the one to follow.

Etsy's Listing Image Requirements, last updated on 9 July 2024, allow that case: "you may use a stock photo mockup to illustrate the end product buyers will receive." For items a seller makes, Etsy's Creativity Standards, last updated on 10 June 2025, say listings "must use original photo or video content of the final product". Can You Use Mockups on Etsy? sets out the photo rule for every listing type.

One request per listing makes the clip from the same template and artwork as the listing photos, so the video shows the product the photos show. SudoMock queues the clip and answers at once with a job to follow.

curl -X POST https://api.sudomock.com/api/v1/renders/video \
  -H "x-api-key: $SUDOMOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mockup_uuid": "YOUR_MOCKUP_UUID",
    "smart_objects": [
      { "uuid": "YOUR_SMART_OBJECT_UUID",
        "asset": { "url": "https://example.com/designs/citrus.png", "fit": "fit" } }
    ],
    "export_options": { "image_format": "jpg", "image_size": 1024 },
    "video": { "duration_seconds": 6, "audio": false, "motion": "ambient" }
  }'

const response = await fetch('https://api.sudomock.com/api/v1/renders/video', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SUDOMOCK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mockup_uuid": "YOUR_MOCKUP_UUID",
    "smart_objects": [
      {
        "uuid": "YOUR_SMART_OBJECT_UUID",
        "asset": {
          "url": "https://example.com/designs/citrus.png",
          "fit": "fit"
        }
      }
    ],
    "export_options": {
      "image_format": "jpg",
      "image_size": 1024
    },
    "video": {
      "duration_seconds": 6,
      "audio": false,
      "motion": "ambient"
    }
  }),
});

const data = await response.json();
console.log(data);

import os
import requests

response = requests.post(
    "https://api.sudomock.com/api/v1/renders/video",
    headers={
        "x-api-key": os.environ["SUDOMOCK_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "mockup_uuid": "YOUR_MOCKUP_UUID",
        "smart_objects": [
            {
                "uuid": "YOUR_SMART_OBJECT_UUID",
                "asset": {
                    "url": "https://example.com/designs/citrus.png",
                    "fit": "fit",
                },
            },
        ],
        "export_options": {
            "image_format": "jpg",
            "image_size": 1024,
        },
        "video": {
            "duration_seconds": 6,
            "audio": False,
            "motion": "ambient",
        },
    },
)

print(response.json())

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	payload := []byte(`{
  "mockup_uuid": "YOUR_MOCKUP_UUID",
  "smart_objects": [
    {
      "uuid": "YOUR_SMART_OBJECT_UUID",
      "asset": {
        "url": "https://example.com/designs/citrus.png",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "jpg",
    "image_size": 1024
  },
  "video": {
    "duration_seconds": 6,
    "audio": false,
    "motion": "ambient"
  }
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/renders/video", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SUDOMOCK_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

<?php

$payload = <<<'JSON'
{
  "mockup_uuid": "YOUR_MOCKUP_UUID",
  "smart_objects": [
    {
      "uuid": "YOUR_SMART_OBJECT_UUID",
      "asset": {
        "url": "https://example.com/designs/citrus.png",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "jpg",
    "image_size": 1024
  },
  "video": {
    "duration_seconds": 6,
    "audio": false,
    "motion": "ambient"
  }
}
JSON;

$ch = curl_init('https://api.sudomock.com/api/v1/renders/video');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('SUDOMOCK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

mockup_uuid, smart_objects and export_options are the blocks an image render of the same template takes, so the artwork sits where it sits in your listing photos. In video, duration_seconds: 6 asks for a clip inside both of Etsy's ranges. Set it in every request, n8n and Make steps included: a request without it gets the 4 second default, and a length outside the model's set comes back as a 400 with allowed_durations to pick from. audio: false is the default and matches what Etsy plays, and motion: ambient keeps the print readable while the scene moves.

The reply is 202 Accepted with a job_id, the status_url to poll, the model that makes the clip, and the duration_seconds, audio and estimated_credits the job was priced at. Poll the job until its status is succeeded, then download the clip from result_url:

curl -X GET https://api.sudomock.com/api/v1/jobs/YOUR_JOB_ID \
  -H "x-api-key: $SUDOMOCK_API_KEY"

const response = await fetch('https://api.sudomock.com/api/v1/jobs/YOUR_JOB_ID', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.SUDOMOCK_API_KEY,
  },
});

const data = await response.json();
console.log(data);

import os
import requests

response = requests.get(
    "https://api.sudomock.com/api/v1/jobs/YOUR_JOB_ID",
    headers={
        "x-api-key": os.environ["SUDOMOCK_API_KEY"],
    },
)

print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.sudomock.com/api/v1/jobs/YOUR_JOB_ID", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SUDOMOCK_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

<?php

$ch = curl_init('https://api.sudomock.com/api/v1/jobs/YOUR_JOB_ID');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('SUDOMOCK_API_KEY'),
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

For a catalogue, send one request per listing and let a webhook endpoint on your account collect the clips. SudoMock sends video.succeeded and video.failed events, and the job stays the record to read, as Webhooks describes.

Read the clip's length, file size and pixel dimensions before the upload, because Etsy sets a limit on each. One ffprobe command prints all four.

ffprobe -v error -select_streams v:0 -show_entries stream=width,height:format=duration,size -of default=noprint_wrappers=1 clip.mp4

Compare duration with 5 to 15 seconds, size (in bytes) with Etsy's 100 MB, and width and height with the 500px minimum.

Until 21 October 2026, Etsy's uploadListingVideo call replaces a listing's active video unless the request opts in to the new behavior. From that day every upload adds the video next to the one already there, up to 2 per listing, and an upload to a listing with 2 active videos returns 409 Conflict.

Etsy announced it on 3 September 2026 in Open API discussion 1714: "Currently, calling uploadListingVideo replaces any existing video on a listing", and after the migration "the endpoint will instead add a video alongside existing ones (up to 2 per listing), and the replace behavior will be permanently disabled." The grace period began on 21 September with the query parameter is_multi_video=true, and after 21 October "is_multi_video will be ignored and the new behavior will apply to all requests unconditionally."

The request below opts in now, so the script behaves the same before and after the date. It needs an OAuth token with the listings_w scope, and Etsy's x-api-key header carries the keystring and the shared secret joined by a colon, as the Open API specification defines it.

CLIP=clip.mp4
curl -X POST "https://openapi.etsy.com/v3/application/shops/$SHOP_ID/listings/$LISTING_ID/videos?is_multi_video=true" \
  -H "x-api-key: $ETSY_KEYSTRING:$ETSY_SHARED_SECRET" \
  -H "Authorization: Bearer $ETSY_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@$CLIP;type=video/mp4" \
  -F "name=clip.mp4"

How uploadListingVideo treats a listing's videos before and after 21 October 2026, drawn from Etsy's announcement of 3 September 2026.

A script that used to swap a listing's video now leaves two, and its next swap fails with 409. Read the listing's videos with getListingVideos, remove the old one with deleteListingVideo, then upload. Etsy's specification says a copy of a deleted video stays on its servers, so its video_id can be linked to the listing again without uploading the file. Linking a video_id that is already active on the listing returns 409 as well.

Order matters too. In Etsy's words, "The first video uploaded becomes the primary video for the listing. A second video uploaded is placed at the end of the listing's media", so upload the clip buyers should see first before the other one.

Render one clip from the template behind your best-selling listing, check it with the ffprobe command, and upload it with is_multi_video=true, which works the same before and after 21 October. Render a video mockup documents every field of the request, and Retrieve a single job the reply that carries the clip. Without code, the SudoMock nodes for n8n and Make include a video render step. With no template yet, the mockup templates for Etsy sellers are ready to render. For the photos next to the clip, Etsy Listing Photo Size gives each photo's size, and How to Automate Etsy Product Mockups runs the renders for a whole catalogue.