Stable idempotency keys for pause-cut trims: hash source, start, end

A pause-cut batch can fire dozens of $0.02 trims, and a network retry should not create a second set. Use a deterministic key: a hash of the source URL, the rounded start, the rounded end and the precision. The same range then reuses the same key and returns the same job, while a changed range gets a new key.

What the API does with the key

Every video-trim write needs an Idempotency-Key. Reusing a key with the same body returns the original job; reusing it with a different body returns 409 idempotency_conflict. That is why a threshold change must change the key, and why a random UUID created inside the retry loop defeats the purpose.

Key function

Round times to three decimals before hashing so 1.84 and 1.8400000001 map to one key. Keep the key under typical header limits by truncating the digest.

import hashlib, json

def trim_key(source_url, start, end, precision="exact"):
    raw = json.dumps([source_url, round(start, 3), round(end, 3), precision])
    return "trim-" + hashlib.sha256(raw.encode()).hexdigest()[:32]

k1 = trim_key("https://media.sume.com/artifacts/artf_demo/talk.mp4", 1.84, 9.1)
k2 = trim_key("https://media.sume.com/artifacts/artf_demo/talk.mp4", 1.84, 9.1)
k3 = trim_key("https://media.sume.com/artifacts/artf_demo/talk.mp4", 1.84, 9.2)
assert k1 == k2 and k1 != k3

Gotchas

• Include everything that changes the body, such as precision, audio and output; leave one out and a changed request gets idempotency_conflict.
• Hash the same rounded values you put in the body, or the body and key disagree.
• A key is tied to the request, not to the result, so store the job id next to the key in your own table.