Suno AI API Integration Tutorial: Generate Your First AI Song

Suno is currently the most popular AI music generation platform. Its chirp-v3-5 model can generate a complete song with vocals and instrumental accompaniment from nothing more than a text description or a set of lyrics. For AIGC product teams, embedding Suno's capabilities into your own application (music tools, video soundtracks, game BGM, audiobook background music, emotional companion products, and more) is an exciting direction full of possibilities.

There is one small catch: Suno still does not offer a public developer API. This is one of the unique values of ApiTopMix — it provides a stable Suno interface through a compliant channel, with pay-per-call billing, and a single API key supports both Suno music generation and mainstream LLMs like Claude / OpenAI / Gemini. In this article, we'll walk you through your first Suno API integration in 30 minutes.

Why Choose the ApiTopMix Suno Channel

As of April 2026, there are two ways to access Suno's music generation capability:

• The official web app (suno.com): created through a browser, ideal for individual creators, but you can't integrate it into your own product
• Third-party API channels: aggregation platforms like ApiTopMix that provide a RESTful interface, per-call billing, and support for concurrent calls

Highlights of the ApiTopMix Suno channel:

• A single API key calls Suno + Claude + OpenAI + Gemini all at once (see the docs)
• A standard RESTful interface — Python / Node.js / Go / Java, any language works
• Pay-as-you-go per call ($0.50 / call), no monthly fee, top up from $5
• Compatible with the new-api standard, so if you're already using a similar platform, migration cost is zero

The Core Workflow: Submit → Poll → Download

Suno music generation is an asynchronous task (generation takes 30-90 seconds), so the API is designed around a "submit + poll" pattern:

1. POST /suno/submit/music: pass in the prompt / lyrics / parameters and immediately receive a task_id
2. GET /suno/fetch/{task_id}: poll once every 5-10 seconds and check the status field
3. When status === "SUCCESS", grab audio_url / video_url / image_url from the data array
4. Download the mp3 file pointed to by audio_url, or embed the URL directly into your product

Each music call returns 2 candidate songs by default — two different interpretations of the same prompt. You can pick the better one, or present both to the user and let them choose.

Prerequisites: Get an API Key in 2 Minutes

1. Go to apitopmix.com/register and sign up with your email
2. Console → Tokens → Create new token (copy the sk-... string)
3. Console → Top up, starting at $5 for your first time (enough for 10 music generations)

Hands-On Code: Description Mode (Recommended for Beginners)

Description mode is the simplest — you describe the music you want in natural language (style, mood, instruments, etc.), and Suno automatically generates the lyrics and melody.

Complete Python Example

import requests
import time

API_KEY = "sk-apitopmix-xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://apitopmix.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Submit the task
submit_resp = requests.post(
    f"{BASE_URL}/suno/submit/music",
    headers=headers,
    json={
        "mv": "chirp-v3-5",
        "gpt_description_prompt": "An upbeat summer synth-pop track blending 1980s city pop, with a wistful mood and a female lead vocal.",
        "make_instrumental": False
    }
)
task_id = submit_resp.json()["data"]
print(f"Task submitted, task_id = {task_id}")

# 2. Poll for the result
for attempt in range(30):  # up to 30 times × 6 seconds = 180-second timeout
    time.sleep(6)
    fetch_resp = requests.get(
        f"{BASE_URL}/suno/fetch/{task_id}",
        headers=headers
    )
    result = fetch_resp.json()["data"]
    status = result.get("status")
    print(f"Poll #{attempt+1}: status = {status}")

    if status == "SUCCESS":
        tracks = result.get("data", [])
        for i, track in enumerate(tracks, 1):
            print(f"  Song {i}: {track.get('title')}")
            print(f"    audio: {track.get('audio_url')}")
            print(f"    video: {track.get('video_url')}")
            print(f"    cover: {track.get('image_url')}")
            print(f"    duration: {track.get('duration')} seconds")
        break
    elif status == "FAILURE":
        print(f"Generation failed: {result.get('fail_reason')}")
        break
else:
    print("Timed out, please query again later using the task_id")

Hands-On Code: Custom Mode (Your Own Lyrics)

Custom mode lets you pass in lyrics you've written yourself (the prompt field) plus style tags (the tags field), which suits scenarios where you already have content to work with.

Complete Node.js Example

const API_KEY = "sk-apitopmix-xxxxxxxxxxxxxxxxxxxx";
const BASE_URL = "https://apitopmix.com";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

async function generateCustomMusic() {
  // 1. Submit a custom-lyrics task
  const submitRes = await fetch(`${BASE_URL}/suno/submit/music`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      mv: "chirp-v3-5",
      prompt: `[Verse 1]
午夜的海边 吹来咸咸的风
你的名字刻在贝壳中
潮水带走了我们的梦
只留下月亮 温柔地懂

[Chorus]
别说再见 别说再见
让这夜晚 停在永远`,
      title: "午夜海边",
      tags: "dreamy indie pop, female vocals, lo-fi",
      make_instrumental: false
    })
  });
  const { data: taskId } = await submitRes.json();
  console.log(`task_id = ${taskId}`);

  // 2. Poll
  for (let i = 0; i < 30; i++) {
    await new Promise(r => setTimeout(r, 6000));
    const fetchRes = await fetch(`${BASE_URL}/suno/fetch/${taskId}`, { headers });
    const { data: result } = await fetchRes.json();
    console.log(`Poll ${i+1}: ${result.status}`);
    if (result.status === "SUCCESS") {
      return result.data;  // returns 2 candidate songs
    }
    if (result.status === "FAILURE") throw new Error(result.fail_reason);
  }
  throw new Error("Polling timeout");
}

generateCustomMusic().then(tracks => {
  tracks.forEach((t, i) => console.log(`${i+1}. ${t.title}: ${t.audio_url}`));
});

Hands-On Code: Lyrics-Only Generation (curl)

If you only need AI-written lyrics (no music), use the /suno/submit/lyrics endpoint at a cost of just $0.05 / call.

curl https://apitopmix.com/suno/submit/lyrics \
  -H "Authorization: Bearer sk-apitopmix-xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Indie rock lyrics about a programmer pulling a late night, with dark humor"
  }'

# Response:
# {"code":"success","message":"","data":"task-id-xxxxxxxx"}

# Poll:
curl https://apitopmix.com/suno/fetch/task-id-xxxxxxxx \
  -H "Authorization: Bearer sk-apitopmix-xxxxxxxxxxxxxxxxxxxx"

# Success response:
# {
#   "code": "success",
#   "data": {
#     "task_id": "task-id-xxxxxxxx",
#     "status": "SUCCESS",
#     "data": [
#       {"title": "Overtime Anthem", "text": "[Verse 1]\n..."}
#     ]
#   }
# }

Request Parameters Explained

Polling Best Practices

The stability of an asynchronous task depends on a sound polling strategy:

• Initial wait: wait at least 15 seconds after submission before you start polling (Suno tasks rarely finish in under 15 seconds, and polling too early wastes requests)
• Polling interval: once every 5-10 seconds is reasonable; intervals that are too short can trigger rate limits
• Timeout ceiling: 180 seconds (30 times × 6 seconds). Beyond this, it's better to record the task_id and query again later rather than blocking the user
• State machine: SUBMITTED → IN_PROGRESS → SUCCESS / FAILURE / CANCELED
• Retry on failure: on FAILURE you can re-submit immediately (note this re-bills at $0.50); CANCELED is usually not charged, but confirm to be sure
• Production environments: use a message queue (Redis Stream / RabbitMQ) to decouple submission from polling, so you don't block web request threads

Case Study: Claude Writes a Story + Suno Writes the BGM

The combination of Suno and an LLM is genuinely fun. The example below uses Claude to generate a children's bedtime story, then extracts mood tags from the story so Suno can generate matching background music:

import requests
from openai import OpenAI

# One key calls both Claude and Suno
API_KEY = "sk-apitopmix-xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://apitopmix.com"

# 1. Claude generates the story + music description
openai_client = OpenAI(api_key=API_KEY, base_url=f"{BASE_URL}/v1")
resp = openai_client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": (
            "Write a 200-word children's bedtime story whose hero is a little bear searching for the moon. "
            "At the end of the story, in a separate paragraph, provide ..., "
            "describing in one sentence the background music style that suits this story."
        )
    }]
)
story = resp.choices[0].message.content
print(story)

# 2. Extract the music description
import re
music_desc = re.search(r"<music_description>(.*?)</music_description>", story, re.S).group(1).strip()

# 3. Suno generates matching BGM (instrumental)
suno_resp = requests.post(
    f"{BASE_URL}/suno/submit/music",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "mv": "chirp-v3-5",
        "gpt_description_prompt": music_desc,
        "make_instrumental": True  # instrumental only
    }
)
task_id = suno_resp.json()["data"]
print(f"Generating BGM, task_id = {task_id}")
# Then poll /suno/fetch/{task_id} to get the audio_url

In 30 seconds you get a complete two-in-one "story + soundtrack" piece. Wrap this pipeline into an API and you have a complete "AI story-music generator" product prototype.

Frequently Asked Questions

1. Does Suno offer an official API, and why use the ApiTopMix channel?

As of April 2026, Suno does not offer a public API for individual developers; it is available only to a small number of enterprise partners. ApiTopMix provides a Suno music generation interface through a compliant channel, with standard pricing of $0.50/call (music) and $0.05/call (lyrics), accessible with a single API key. It is currently one of the easiest ways to get stable access to the Suno API.

2. How long does it take to generate a song?

Suno music generation is an asynchronous task. After submission, it usually returns a completed status in 30-90 seconds. We recommend a polling interval of 5-10 seconds and a timeout of 180 seconds. Each submit/music call generates 2 candidate songs, so you can pick the better of the two from the returned data array.

3. What is the difference between Description mode and Custom mode?

Description mode uses the gpt_description_prompt field to describe the music you want (for example: "an upbeat 1980s synth-pop track"), and Suno automatically generates the lyrics and melody. Custom mode uses the prompt field to pass in your own lyrics (or leave it empty with make_instrumental=true for an instrumental), and the tags field to specify the style. Beginners should start with Description mode.

4. Who owns the copyright to the generated music? Can it be used commercially?

Copyright ownership follows Suno's official terms. Content generated under a paid plan is generally allowed for commercial use, but the specific terms are governed by Suno's official policy. We recommend reviewing Suno's Terms of Service before commercial use, and keeping generation logs for traceability. ApiTopMix makes no copyright guarantees and acts solely as an API channel.

5. What should I do if polling keeps failing or stays stuck on IN_PROGRESS?

In rare cases, a task may be canceled because the upstream service is busy. Best practices: (1) set a total timeout of 180 seconds; (2) monitor the status transition from SUBMITTED → IN_PROGRESS → SUCCESS/FAILURE; (3) on FAILURE, automatically re-submit once (note that this incurs another charge); (4) record the task_id to help support with troubleshooting. See the Suno section of the ApiTopMix docs for details.

Further Reading

• The Complete Guide to Migrating from OpenAI to Claude (this blog)
• ApiTopMix vs OpenRouter: A Comprehensive Comparison (this blog)
• ApiTopMix API Docs — full interface reference for the Suno section
• ApiTopMix Pricing — Suno unit pricing and the full price table for other models
• Suno official site — official product and terms of service

Conclusion

Suno is one of the few capability-level AI models that can add a "sound dimension" to AIGC products. Text generation and image generation are already white-hot, but music generation is still a relatively blue ocean — products that move first to integrate it are more likely to capture a niche. Combined with the text-generation power of Claude / GPT, the range of composite applications you can build is far richer than that of any "single-model product."

Today's 15-minute tutorial is enough to get a minimum viable Suno integration running. The next step is to wrap it into a feature of your product (for example, "generate a personalized playlist based on the user's mood," "automatically score videos with music," or "add BGM to an ad script") — and that's an entirely new product direction.