Complete Workflow

This guide walks through the full flow of generating music with sunor: authenticate, create a task, poll until it completes, and use the audio output.

Prerequisites

A sunor account with an API key
Credits in your account (music costs 10 credits)

Step 1: Create a task

Submit a music generation request:

The example below uses Suno’s input shape (gpt_description_prompt, make_instrumental). Udio uses a different shape (prompt, lyrics_type) — see /models/udio before adapting this snippet to "model": "udio".

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://sunor.cc/api/v1"

response = requests.post(
    f"{BASE_URL}/task",
    headers={
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "model": "suno",
        "task_type": "music",
        "input": {
            "gpt_description_prompt": "A chill lo-fi beat for studying, soft piano and vinyl crackle",
            "make_instrumental": True,
        },
    },
)

task = response.json()["data"]
task_id = task["task_id"]
print(f"Task created: {task_id} (status: {task['status']})")

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://sunor.cc/api/v1";

const response = await fetch(`${BASE_URL}/task`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    model: "suno",
    task_type: "music",
    input: {
      gpt_description_prompt: "A chill lo-fi beat for studying, soft piano and vinyl crackle",
      make_instrumental: true,
    },
  }),
});

const { data: task } = await response.json();
console.log(`Task created: ${task.task_id} (status: ${task.status})`);

The response returns a task_id with status "pending". Credits are frozen immediately. Before that point, Sunor validates the body and the selected model/task input. A 400 validation response happens before any credit freeze, task insert, or upstream-provider call. Record the response’s X-Request-Id header so an individual attempt can be correlated across agent logs and Sunor support.

If the create request ends with a network error or an uncertain 5xx response, do not submit the same payload again automatically. The current create endpoint does not yet provide Idempotency-Key replay semantics. If you received a task_id, continue polling that task.

Step 2: Poll for results

Tasks take 30 seconds to 5 minutes to complete. Poll every 5-10 seconds until the status is terminal (success, failure, or timeout).

import time

def wait_for_task(api_key, task_id, interval=5):
    """Poll until the task completes. Returns the task data."""
    while True:
        response = requests.get(
            f"{BASE_URL}/task/{task_id}",
            headers={"x-api-key": api_key},
        )
        data = response.json()["data"]
        status = data["status"]
        print(f"  Status: {status}")

        if status in ("success", "failure", "timeout"):
            return data

        time.sleep(interval)

result = wait_for_task(API_KEY, task_id)

async function waitForTask(apiKey, taskId, interval = 5000) {
  while (true) {
    const response = await fetch(`${BASE_URL}/task/${taskId}`, {
      headers: { "x-api-key": apiKey },
    });
    const { data } = await response.json();
    console.log(`  Status: ${data.status}`);

    if (["success", "failure", "timeout"].includes(data.status)) {
      return data;
    }

    await new Promise((r) => setTimeout(r, interval));
  }
}

const result = await waitForTask(API_KEY, task.task_id);

Step 3: Use the output

On success, the output.result contains an array of generated clips:

if result["status"] == "success":
    clips = result["output"]["result"]
    for clip in clips:
        print(f"Title: {clip['title']}")
        print(f"Audio: {clip['audio_url']}")
        print(f"Cover: {clip['image_url']}")
        print()
else:
    print(f"Task failed: {result['error']}")

if (result.status === "success") {
  const clips = result.output.result;
  for (const clip of clips) {
    console.log(`Title: ${clip.title}`);
    console.log(`Audio: ${clip.audio_url}`);
    console.log(`Cover: ${clip.image_url}`);
    console.log();
  }
} else {
  console.log(`Task failed: ${result.error}`);
}

Downloading the audio

Audio URLs point to the generated audio file. Take the file extension from the response’s Content-Type rather than hard-coding one — the container format is determined upstream and has changed before. You can download them directly:

import mimetypes
import shutil
import urllib.request

clip = clips[0]
with urllib.request.urlopen(clip["audio_url"]) as response:
    ext = mimetypes.guess_extension(response.headers.get_content_type()) or ".audio"
    filename = f"{clip['title']}{ext}"
    with open(filename, "wb") as f:
        shutil.copyfileobj(response, f)
print(f"Downloaded: {filename}")

import { writeFile } from "fs/promises";

const EXTENSIONS = {
  "audio/mpeg": ".mp3",
  "audio/mp4": ".m4a",
  "audio/wav": ".wav",
};

const clip = clips[0];
const audio = await fetch(clip.audio_url);
const buffer = Buffer.from(await audio.arrayBuffer());
const type = (audio.headers.get("content-type") || "").split(";")[0];
const filename = `${clip.title}${EXTENSIONS[type] || ".audio"}`;
await writeFile(filename, buffer);
console.log(`Downloaded: ${filename}`);

Full example

Putting it all together:

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://sunor.cc/api/v1"

# 1. Create task
print("Creating music task...")
response = requests.post(
    f"{BASE_URL}/task",
    headers={
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "model": "suno",
        "task_type": "music",
        "input": {
            "gpt_description_prompt": "A chill lo-fi beat for studying",
            "make_instrumental": True,
        },
    },
)
task_id = response.json()["data"]["task_id"]
print(f"Task ID: {task_id}")

# 2. Poll for results
print("Waiting for completion...")
while True:
    response = requests.get(
        f"{BASE_URL}/task/{task_id}",
        headers={"x-api-key": API_KEY},
    )
    data = response.json()["data"]

    if data["status"] in ("success", "failure", "timeout"):
        break
    time.sleep(5)

# 3. Use the output
if data["status"] == "success":
    for clip in data["output"]["result"]:
        print(f"  {clip['title']}: {clip['audio_url']}")
else:
    print(f"Failed: {data['error']}")

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://sunor.cc/api/v1";

// 1. Create task
console.log("Creating music task...");
const createRes = await fetch(`${BASE_URL}/task`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    model: "suno",
    task_type: "music",
    input: {
      gpt_description_prompt: "A chill lo-fi beat for studying",
      make_instrumental: true,
    },
  }),
});
const taskId = (await createRes.json()).data.task_id;
console.log(`Task ID: ${taskId}`);

// 2. Poll for results
console.log("Waiting for completion...");
let data;
while (true) {
  const res = await fetch(`${BASE_URL}/task/${taskId}`, {
    headers: { "x-api-key": API_KEY },
  });
  data = (await res.json()).data;

  if (["success", "failure", "timeout"].includes(data.status)) break;
  await new Promise((r) => setTimeout(r, 5000));
}

// 3. Use the output
if (data.status === "success") {
  for (const clip of data.output.result) {
    console.log(`  ${clip.title}: ${clip.audio_url}`);
  }
} else {
  console.log(`Failed: ${data.error}`);
}

Next steps

Music generation modes

Learn about inspiration, custom, and continuation modes.

Error handling

Handle errors and implement retries.

Rate limits

Stay within rate limits with smart polling.

API Reference

Full endpoint documentation.

Getting Started

Billing

Models

Guides

Resources

Complete Workflow

Complete Workflow

Prerequisites

Step 1: Create a task

Step 2: Poll for results

Step 3: Use the output

Downloading the audio

Full example

Next steps

Music generation modes

Error handling

Rate limits

API Reference

​Complete Workflow

​Prerequisites

​Step 1: Create a task

​Step 2: Poll for results

​Step 3: Use the output

​Downloading the audio

​Full example

​Next steps

Music generation modes

Error handling

Rate limits

API Reference

Complete Workflow

Prerequisites

Step 1: Create a task

Step 2: Poll for results

Step 3: Use the output

Downloading the audio

Full example

Next steps