Suno API Guide: Generate Music Programmatically

Suno does not offer an official public API. Every route to calling Suno programmatically, including this one, goes through a third-party wrapper. Apiframe's version puts Suno behind the same API key and billing you'd use for every other model on the platform, images, video, and now music, so integrating it doesn't mean setting up a separate account or a separate bill.

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 async: submit a job, then poll GET /v2/jobs/:id or wait on a webhook. 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 before any generation is attempted, so check your prompt length against the mode you're using rather than assuming one limit applies everywhere.

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 identical across every version, so there's no cost penalty for defaulting to the newest one. For a full breakdown of what actually changes between versions, see Suno Versions Explained.

Full parameter reference

Pricing

Every action costs the same flat 11 credits, whether it's the initial generation, an extend, a cover, adding vocals, or splitting stems. At the pay-as-you-go top-up rate ($0.01/credit), that's $0.11 per action. Paid monthly plans bundle credits at a cheaper effective rate, down to $0.00383/credit on the Growth plan ($199/mo, 52,000 credits), which brings the same action to about $0.042.

Each generate request returns 2 tracks, so the effective per-track cost is roughly $0.055 at the top-up rate or $0.021 on a Growth-plan rate. Check current tier pricing on the pricing page.

Follow-up actions

Once a generation completes, either of its 2 tracks can be acted on further, each 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 real generations in their own right, so you can chain them, building longer or more elaborate tracks in segments.

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 use, swap the polling loop for a webhook, it's the same setup used 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 rather than one-off tracks. Rapid demoing for musicians sketching out an idea before recording it properly.

FAQ

Does Suno have an official API?

No. Suno does not publish one. Every programmatic route, Apiframe included, is a third-party wrapper.

What's the difference between description mode and custom mode?

Description mode (custom_mode: false) takes a short song description and Suno handles the rest, capped at 500 characters. Custom mode (custom_mode: true) takes actual lyrics as the prompt, up to 5,000 characters, with style and title set separately.

Does the model version affect pricing?

No. All six model_version values cost the same flat 11 credits per generation.

How many tracks does one request generate? 2 tracks per generate request, both returned in the same job result.

Can I use the generated music commercially?

Licensing terms are set by Suno and passed through; however, Apiframe’s terms of service specify that you check the current terms before using the output commercially.

How do I extend a track past its generated length?

Use the extend follow-up action on a completed track's id, it continues generation from a chosen timestamp.

Get an API key and start with free credits, or try it in Apiframe Studio first. Full parameter docs live here.