Poll Sume audio jobs at the recommended interval, not a fixed sleep

Read the poll hints Sume returns instead of guessing a sleep. The job status response includes next_poll_after_seconds, recommended_poll_interval_seconds, retry_after_seconds, a terminal flag and a result_ready flag. A loop that sleeps for the recommended interval and stops on terminal polls no more often than it needs to, and does not hammer the API for a long TTS or STT job.

It also means you can change the pacing from the server side without editing every client.

Which fields matter?

The status route is /v1/jobs/{id}/status. The Sume OpenAPI spec lists these fields as required on the response.

Why not a fixed sleep?

A fixed two second sleep is fine for a demo and wasteful at scale. With a hundred jobs in flight it is a hundred requests every two seconds, much of which tells you nothing new. A server hint lets the API slow you down when work is slow, and a 429 from the API is a reason to honour retry_after_seconds rather than retry immediately.

• Stop on terminal, not on a status string you invented.
• Fetch the result only when result_ready is true.
• Add a ceiling so a stuck job does not poll forever.

What does the loop look like?

A loop with a ceiling and the server's interval:

import os, time, requests

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
url = f"https://api.sume.com/v1/jobs/{os.environ['JOB_ID']}/status"

deadline = time.time() + 900
while time.time() < deadline:
    d = requests.get(url, headers=H, timeout=30).json()["data"]
    if d["terminal"]:
        print(d["sume_status"], "result_ready:", d["result_ready"])
        break
    time.sleep(d.get("next_poll_after_seconds")
               or d.get("recommended_poll_interval_seconds") or 3)
else:
    print("gave up waiting; the job may still finish")

Should you poll at all?

If you can expose a public HTTPS endpoint, a webhook removes polling for the common case. Keep polling as the fallback; see async TTS polling on Sume and what to do after a sync timeout.