Retrying a Sume music job: Idempotency-Key and no double charge

How do I retry a music request without paying for two tracks?

Send the same Idempotency-Key on every retry of the same request. Sume returns the original job rather than starting a second generation, and each generation is billed at the fixed Music price. Without a key, a client retry after a timeout is a second paid generation, and you will get a different song.

This matters more for music than for most jobs. Google's Lyria 3.5 page states that results may vary between calls, even with the same prompt, so a duplicate cannot be treated as a cache hit or "the same track again".

When does a music submit time out?

The Music Router accepts mode values of async, sync, subscribe and webhook, plus wait_timeout_seconds from 0 to 30 for sync and subscribe. That wait bounds the HTTP call, not the job. The jobs documentation says that if no terminal update arrives before the timeout, the response is still a 2xx with the current job state and polling URLs, and you must not submit a new paid job for the same intent.

Real retries come from network failures, load balancers, workflow engines and clients that re-send after a cut connection. In all of those, the first request may already have been accepted.

What exactly does the same key do?

The docs rule is short: reuse a key only for the same operation and payload. A matching retry returns the original job. A reused key with a different prompt or operation returns 409 idempotency_conflict, and the docs tell you to reuse keys only for exact retries.

What does a safe retry look like in practice?

Generate the key from your own record, not from a random value at call time, so a restarted process derives the same string. Below, the second call is a retry of the first and returns the same job.

KEY="campaign-482-intro-bed-v1"
BODY='{"prompt":"Warm lo-fi hip hop, 84 BPM, C minor. A 30-second track. Instrumental, no vocals."}'

for i in 1 2; do
  curl -s -X POST https://api.sume.com/v1/music-router/generate \
    -H "Authorization: Bearer $SUME_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $KEY" \
    -d "$BODY"
  echo
done

What else should the integration do?

Poll GET /v1/jobs/{id}/status until the job is terminal, then read the audio artifact from GET /v1/jobs/{id}/result. Keep status polling even if you use a webhook, because the docs describe delivery as an optimization, not your only recovery path.

Store the job id with your campaign record. The metadata field is stored on the job and not sent to the provider, so you can tag the job with your own id; see the metadata post.

Finally, do not retry a failed job by changing the key silently. Failed jobs and canceled jobs are different cases; decide deliberately whether you want a new paid attempt.