Suno API Guide: Generate Music Programmatically

Suno does not offer an official public API. Every way to call Suno from code, including this one, goes through a third-party wrapper. Apiframe puts Suno behind the same API key and billing you already use for every other model on the platform (images, video, and music), so you do not need a separate Suno account or bill. If you are building a unified AI media integration, this fits into your existing setup without any extra overhead. If you are new to how music wrapper APIs work, our AI music API guide explains the general setup before you dive into Suno specifically.

Quickstart

Sign up for free credits, then generate your first track:

curl -X POST https://api.apiframe.ai/v2/music/generate \
  -H "X-API-Key: afk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "upbeat electronic track with synth arpeggios and driving bass",
    "model": "suno",
    "sunoParams": {
      "model_version": "V5_5",
      "style": "electronic, synthwave"
    }
  }'

Requests are asynchronous: submit a job, then poll GET /v2/jobs/:id or wait for a webhook callback. No separate Suno account required. Try it without writing code first in Apiframe Studio.

Two ways to prompt

Suno's API accepts prompts in two distinct modes, controlled by custom_mode:

Description mode (custom_mode: false, the simpler default): the prompt is a short description of the song you want, capped at 500 characters. Suno figures out the lyrics, structure, and style from that description alone.

Custom mode (custom_mode: true): the prompt is treated as the actual lyrics, up to 5,000 characters, and you separately supply style and title to control the sound. Use this when you already have lyrics written, or when you need precise control over structure. Requests that exceed the character cap for the mode you're in fail validation with a 400 error before generation starts, so check your prompt length before submitting.

Model versions

sunoParams.model_version selects which Suno version generates the track: V4, V4_5, V4_5ALL, V4_5PLUS (Apiframe's default if you omit the field), V5, or V5_5. Credit cost is the same across every version, so there is no extra charge for choosing the newest one. For a full breakdown of what actually changes between versions, see Suno Versions Explained.

Full parameter reference

Pricing

Every action costs a flat 11 credits, whether it's the initial generation, an extend, a cover, or adding vocals. Splitting a track into stems costs 20 credits. Credits cost $0.01 each on every plan, so that works out to $0.11 per action ($0.20 for stems), whether you pay as you go or subscribe. Plans differ in monthly credit volume and how many jobs can run at once, not in the per-credit rate.

Each generate request returns 2 tracks, so the effective cost per track is roughly $0.055. Check current tier pricing on the pricing page, or see our AI music API pricing breakdown for how this compares to other providers.

Follow-up actions

Once a generation completes, either of the two resulting tracks can be acted on further. Each follow-up action is a separate 11-credit call:

Extend continues a track from a chosen timestamp, useful for stretching a track past Suno's native length limit.

Cover regenerates the track in a new style while keeping the core melody, handy for retargeting a track to a different mood without starting over.

Add Vocals layers AI vocals onto an instrumental generation.

Stems splits a track into separate vocal and instrumental files. Unlike the other three actions, a stems result is a plain audio file and can't be acted on again.

Extend, Cover, and Add Vocals results are full generations in their own right, so you can chain them to build longer or more complex tracks step by step.

Complete example

import requests
import time

API_KEY = "afk_your_api_key_here"
BASE = "https://api.apiframe.ai/v2"

def generate_track(prompt, style, model_version="V5_5"):
    response = requests.post(
        f"{BASE}/music/generate",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "prompt": prompt,
            "model": "suno",
            "sunoParams": {"model_version": model_version, "style": style},
        },
    )
    job_id = response.json()["id"]

    while True:
        job = requests.get(f"{BASE}/jobs/{job_id}", headers={"X-API-Key": API_KEY}).json()
        if job["status"] == "COMPLETED":
            return job["result"]["tracks"]
        if job["status"] == "FAILED":
            raise RuntimeError(job.get("error"))
        time.sleep(5)

tracks = generate_track(
    "a calm lo-fi hip hop beat for studying, mellow piano and light rain",
    style="lo-fi, chill, instrumental",
)
for track in tracks:
    print(track["title"], track["audioUrl"], track["duration"])

For production, swap the polling loop for a webhook callback. The setup works the same way across every model on Apiframe.

Use cases

Background music for short-form video and ads, where licensing stock tracks is either expensive or too generic for the brief.

Podcast intros and outros generated on demand, rather than picked from a stock library.

In-app soundtracks for games or apps that need original, royalty-clear music at scale.

Rapid sketching for musicians who want to hear an idea before recording it properly.

For a broader look at how teams use music generation APIs in production, see our AI music API use cases guide.