Match STT results to file ids: the job echoes your Idempotency-Key

A transcription batch has two bookkeeping problems. After a crash you do not know which files already have a job, and when jobs complete you must know which transcript belongs to which recording. The Sume STT job answers both if you use the file id as the Idempotency-Key.

Why this works

The jobs guide says a retry of the same submit with the same Idempotency-Key returns the original job rather than billing a second one. The same key with a different payload returns 409 idempotency_conflict. The job record itself carries an idempotency_key field, so reading a job from GET /v1/jobs/:id tells you which of your keys created it.

The pattern

Before you start, nothing needs to be stored. On every run, submit every file with its id as the key. Already submitted files return their existing jobs at no extra cost. Then read the results by job id. The key is a stable name for the operation, so build it from the file id plus the part number for chunks, such as rec-0412-p03.

import os, requests
B = "https://api.sume.com/v1"
H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
files = {"rec-0412": "https://example.com/a.mp3", "rec-0413": "https://example.com/b.mp3"}

jobs = {}
for fid, url in files.items():
    r = requests.post(B + "/stt-1.0/transcribe", headers={**H, "Idempotency-Key": fid},
                      json={"audio_url": url, "duration_seconds": 600, "mode": "async"})
    r.raise_for_status()
    jobs[fid] = r.json()["data"]["job"]["id"]

for fid, job in jobs.items():
    s = requests.get(f"{B}/jobs/{job}/status", headers=H).json()["data"]
    print(fid, job, s["sume_status"], s["terminal"])

Rules for good keys

• Use the same key only for the same payload. If you change language_code for a file, add a revision suffix, such as rec-0412-v2, or you get the 409.
• Do not reuse a key across STT and TTS, or between different files.
• Keep keys short and stable. A timestamp in the key defeats the purpose.
• The key does not live in the audio, so a renamed file needs a mapping of its own.

Cost

STT 1.0 costs about $0.01 per minute. A run that crashed at file 212 and restarted from file 1 does not pay for 211 files again if the keys match, since the retry returns the original jobs. That is the saving the pattern buys. It is a bookkeeping feature, not a discount.