Edited script, same Idempotency-Key: 409 conflict on Sume TTS

If you change the transcript and reuse the same Idempotency-Key, Sume answers 409 idempotency_conflict and creates nothing. That is the safety working: the key means "this exact request". Give each script version its own key and the conflict never shows up, while a true retry of one version still returns the original job.

What the key promises

Send Idempotency-Key on any generation call. Repeat the identical request with the same key and you get the existing job back instead of a second charge. Repeat the key with a different payload and the API refuses. This holds for TTS 1.0, STT 1.0 and the music endpoints alike.

A key that tracks the edit

A good key names the intent, not the time. Hash the fields that define the audio, so an unchanged script reuses its key and a changed one gets a fresh one.

import hashlib
import json


def tts_key(project, transcript, avatar, language):
    body = json.dumps(
        [transcript, avatar, language], ensure_ascii=False
    )
    digest = hashlib.sha256(body.encode()).hexdigest()[:16]
    return f"{project}-{digest}"


print(tts_key("promo", "Hello there.", "narrator", "en"))
print(tts_key("promo", "Hello there!", "narrator", "en"))

Mistakes to avoid

• A fixed key like test in a script: the second run with new text fails.
• A timestamp key: every retry after a network error buys another job.
• Resubmitting after a sync timeout. A timed-out wait means the job is still running; poll status_url instead.

Handling the 409

Treat idempotency_conflict as a bug in key construction, not as a transient error. Do not retry with the same key. Log the key and the changed field, then rebuild the key from the new payload and submit once. Sume does not document an expiry window in the pages I read, so do not rely on a key aging out.