Music job timed out? Retry with the same key: one $0.125, not two

If a Sume music submit times out on your side, retry the same request with the same Idempotency-Key and Sume returns the original job instead of billing a second one. Music is a flat $0.125 per generation, so an unkeyed blind retry that produces a second job costs $0.25 for one track.

The rule is from the Sume jobs and results guide, which says to retry the submit itself with the same key and not to submit a new paid job for the same intent, and from the API catalog (read 2026-10-09).

The sequence

Send the generate request with a key you made before the call, such as one derived from the project and the take number. If the response is a 2xx with a job id, poll GET /v1/jobs/:id/status and then GET /v1/jobs/:id/result; when the sync wait budget ends, the guide says to keep polling and not to submit again. If you got no response at all, resend the same body with the same key.

Use the same key again only for the same operation and payload. If you change the prompt, that is a different operation and needs a new key.

Wait budget is not job length

The wait_timeout_seconds value is clamped to 0 to 30 and limits how long the HTTP request blocks, not how long the job can take. For music, submit with mode: "async" and poll, or use a webhook, instead of a long synchronous wait. A music job that has not finished at 30 seconds has not failed.

Cancelling

POST /v1/jobs/:id/cancel cancels a job before generation starts. After generation starts it returns 409 job_generation_already_started. Canceling a job that is already canceled is idempotent. The catalog's reservation policy refunds failed or pre-generation canceled jobs before capture, so a quick cancel on a mistaken submit is worth trying.

Building the key

A good key names the intent: project id, scene number and take number, for example proj-42-scene-3-music-take-1. Store it with the request before you send it, so a crash does not lose it. A random key made at send time defeats the purpose, since the retry would not know it.

The same rule works for TTS and the other paid routes. The jobs guide gives the example of a date-and-counter key such as hero-shot-2026-08-03-001.

Finally, record the job id as soon as you have it. If your process restarts, you can poll the stored id instead of submitting again, and you never need the idempotency key to find a job you already hold.