Suno API in Python: a working loop

Install and authenticate

Use requests or httpx; both are enough. Keep the key in an environment variable, never in the repository, and send it as Authorization: Bearer <KEY>. Generation calls are billed; status and download calls are free.

Create a key in the console, then run the example below against https://www.suno-api.io.

Submit, poll, download

import os, time, requests

BASE = "https://www.suno-api.io"
H = {"Authorization": f"Bearer {os.environ['SUNO_API_KEY']}"}

created = requests.post(f"{BASE}/api/music/create", headers=H, timeout=300, json={
    "description": "warm Mandarin pop, piano intro, female vocal",
    "model": "suno-v6",
}).json()
song_id = created["data"]["clips"][0]["song_id"]

for _ in range(75):
    task = requests.post(f"{BASE}/api/music/query", headers=H, timeout=60,
                         json={"song_id": song_id}).json()["data"]
    if task.get("status") in ("complete", "completed"):
        break
    if task.get("status") in ("failed", "error"):
        raise RuntimeError(task.get("reason", "generation failed"))
    time.sleep(4)

media = requests.post(f"{BASE}/api/music/download-url", headers=H, timeout=60,
                      json={"song_id": song_id, "kind": "song"}).json()
print(media)

Store song_id, not the media URL. The URL is a temporary pickup ticket; ask for a new one when you need the file again.

The three failure modes

• A 30-second client timeout. Renders take minutes. A timeout means you stopped waiting, not that the order was rejected.
• Resubmitting after a timeout. This is the main source of duplicate charges: query the task first.
• Saving the audio URL as a permanent link. It expires; re-fetching it is free and does not create a new generation.

Next: Node.js version · polling vs webhooks · task lifecycle.