Python preflight for a YouTube Short: length and shape check

This script asks Sume's video inspect for a clip's probe and prints whether it fits YouTube's Short rule: up to three minutes, square or vertical. It uses duration_seconds, width, height and rotation, treating a 90 or 270 degree rotation as a swap of width and height. Probe-only calls are unbilled per the Sume docs.

The rule is from Understand three-minute YouTube Shorts, read 2026-10-02. The fields are from the video inspect docs and the API source.

What does the probe return?

Video inspect reads one clip already on media.sume.com; there is no open-internet fetch, so import first (see Media inputs). With frames: false you get probe facts only. The probe object has duration_seconds, width, height, rotation, fps, container, video_codec, has_audio, size_bytes and a few more.

Default mode is sync: the call waits up to 30 seconds and answers 200 with the finished inspect, or 202 with a queued job to poll. The script below handles only the 200 case and stops with a clear message otherwise.

What is the script?

It needs requests and SUME_API_KEY. The response wraps the resource in data.video_inspect; the script reads probe from there and stops if it is missing.

Rotation is the trap. Phone footage is often stored landscape with a rotation flag, so width and height alone would call a vertical clip landscape.

import os, sys, requests

url = sys.argv[1]
r = requests.post(
    "https://api.sume.com/v1/video-inspect",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
             "Idempotency-Key": "preflight-" + url[-24:]},
    json={"video_url": url, "frames": False},
    timeout=60,
)
r.raise_for_status()
if r.status_code != 200:
    sys.exit(f"queued ({r.status_code}); poll the job and rerun")
data = r.json()["data"]
p = (data["video_inspect"] or {}).get("probe")
if not p:
    sys.exit("no probe in the response")
w, h = p["width"], p["height"]
if (p.get("rotation") or 0) % 180 == 90:
    w, h = h, w
problems = []
if p["duration_seconds"] is None or p["duration_seconds"] > 180:
    problems.append("longer than 180 s")
if w is None or h is None or w > h:
    problems.append("wider than tall")
print("OK for a Short" if not problems else "; ".join(problems))

What does it not check?

It checks only what YouTube's page states: length up to three minutes and a square or vertical shape. It does not check file size, codec or audio rights. The probe also reports video_codec, has_audio and size_bytes if you want to add your own rules, but YouTube's help page read for this post does not set limits for those, so none are enforced here.

The idempotency key is the last 24 characters of the URL, which is enough for a one-off; use a real unique key in a pipeline.

What do I do when it fails?

Longer than 180 seconds: cut with video trim. Wider than tall: recompose with Timeline 1.0 to vertical or square. Both return new MP4s and leave the source untouched. Rerun the script on the result before uploading.