Suno API Documentation — AI Music Generation, Lyrics & Audio

The Suno API is a developer interface for AI music generation, enabling you to programmatically create complete songs, lyrics, and audio tracks from text prompts. Through TTAPI’s unified gateway, you get stable access to the latest Suno models — including Suno v5 (chirp-v5) — for music creation, vocal separation (stems), and asynchronous job processing. This documentation covers every Suno API endpoint, workflow pattern, and integration guide. If you want the fastest path to working code, start with the Suno API Quickstart.

New to Suno API? Jump to the End-to-End Example to see a complete generate → fetch flow in under 3 minutes.

What Is the Suno API?

The Suno API allows developers to send text prompts to Suno’s AI music models and receive fully generated audio tracks in return — including vocals, instrumentation, and lyrics. Unlike basic music loop generators, the Suno API produces complete, studio-quality songs from a single prompt. Through TTAPI, you get:

Access to Suno v5 / chirp-v5, the latest and most capable model
A clean, standard REST API with consistent authentication
Async job handling via polling or webhook callbacks
Stems separation, lyrics generation, music extension, and cover creation
Unified billing and quota management across all AI audio models

Get Started with Suno API

Suno API Quickstart — fastest path to a working integration
Music Generation API — submit a song generation job
Fetch API (Get Results) — poll for async results
Suno API Async Workflow — deep dive on job handling
Suno API Workflow Guide — full workflow patterns
Audio Pricing — credits and cost per generation

Key Features of the Suno API

🎵 AI Music Generation with Suno v5

Generate complete music tracks from text prompts using the latest Suno models, including chirp-v5. Supports vocal and instrumental outputs, music continuation, and creative style control — suitable for any scale of AI music application.

⚡ Asynchronous & Scalable Workflow

Submit generation tasks asynchronously and retrieve results via polling or webhook callbacks. This async-first design handles long-running jobs efficiently and integrates cleanly into production backends.

🎚️ Stems & Vocal Separation

Separate any generated audio into vocals and instrumental tracks. Use this for remixing, editing, cover production, or integration into professional audio pipelines.

🎼 Lyrics Generation & Custom Mode

Generate lyrics before music creation, or supply your own lyrics in custom mode. The Suno Lyrics API aligns lyric content with vocal timing for seamless integration into full song generation.

🧩 Developer-Friendly REST API

Simple RESTful endpoints with clear request and response schemas. Designed for fast integration with any backend stack — Node.js, Python, Go, or any HTTP client.

Authentication & Base URL

All Suno API requests through TTAPI use a unified gateway and a single authentication header.

Setting	Value
Base URL	`https://api.ttapi.io`
Auth Header	`TT-API-KEY: YOUR_API_KEY`
Content-Type	`application/json`

For full setup instructions, see Gateway & Auth.

Suno API End-to-End Example

The shortest production-safe Suno API flow has three steps:

Submit POST /suno/v1/music
Store data.jobId from the response
Pass that jobId to GET /suno/v2/fetch to retrieve results

Step 1 — Submit a Music Generation Request

curl --request POST 'https://api.ttapi.io/suno/v1/music' \
  --header 'Content-Type: application/json' \
  --header 'TT-API-KEY: YOUR_TTAPI_KEY' \
  --data-raw '{
    "custom": true,
    "instrumental": false,
    "mv": "chirp-v5",
    "title": "Midnight Drive",
    "tags": "synthwave, female vocal, cinematic",
    "prompt": "[Verse] Neon headlights on a rainy street"
  }'

Step 2 — Read the Immediate Response

{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Store data.jobId immediately. This is the handle used for all downstream operations: polling, webhook reconciliation, extend, cover, stems, and WAV export.

Step 3 — Fetch the Generation Result

curl --request GET 'https://api.ttapi.io/suno/v2/fetch?jobId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'TT-API-KEY: YOUR_TTAPI_KEY'

While the job is still running, the response status will be ON_QUEUE. Once generation finishes:

{
  "status": "SUCCESS",
  "message": "success",
  "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "action": "music",
    "progress": "100%",
    "mv": "chirp-v5",
    "quota": "6",
    "hookUrl": "https://your-app.example.com/webhooks/suno",
    "musics": [
      {
        "musicId": "xxxxxxxxxxxxxxxxx",
        "prompt": "[Verse] Neon headlights on a rainy street",
        "title": "Midnight Drive",
        "tags": "synthwave, female vocal, cinematic",
        "imageUrl": "https://cdn2.suno.ai/xxxxxxxxxxxxxxxxx.jpeg",
        "imageLargeUrl": "https://cdn2.suno.ai/xxxxxxxxxxxxxx.jpeg",
        "audioUrl": "https://cdn1.suno.ai/xxxxxxxxxxxxxxx.mp3",
        "videoUrl": "https://cdn1.suno.ai/xxxxxxxxxxxxxxx.mp4",
        "duration": 211.44,
        "negativeTags": "",
        "styleWeight": null,
        "weirdnessConstraint": null,
        "audioWeight": null,
        "createdAt": "2026-03-03T02:23:51.401Z"
      }
    ]
  }
}

For most production apps, the minimum implementation is: submit → store jobId → poll fetch → persist audioUrl, videoUrl, musicId, and metadata for any follow-up operations.

Suno API Parameters Reference

Core Generation Parameters (`POST /suno/v1/music`)

Parameter	Type	Description
`mv`	string	Model version. Use `chirp-v5` for the latest Suno v5 model.
`prompt`	string	Lyrics or style description for the AI music generation.
`tags`	string	Musical style tags, e.g. `synthwave, female vocal, cinematic`.
`title`	string	Title of the generated song.
`custom`	boolean	`true` to use custom lyrics mode; `false` for fully AI-generated content.
`instrumental`	boolean	`true` to generate music without vocals.
`hookUrl`	string	Optional webhook URL to receive results via callback instead of polling.

Advanced Audio Parameters

Parameter	Type	Description
`weirdnessConstraint`	number	Controls how far the AI music generation deviates from conventional musical patterns. A higher value produces more experimental, unconventional output; a lower value keeps the result closer to standard musical structure. Appears in the fetch result payload.
`styleWeight`	number	Controls how strongly the style tags influence the generated output relative to the prompt.
`audioWeight`	number	Balances audio fidelity and generation speed when applicable.
`negativeTags`	string	Style tags to suppress or avoid in the generated output.

Common Use Cases

🎧 AI Music Generation Apps

Build applications that generate complete songs from text prompts, including vocals and instrumentals, using Suno v5 models. Ideal for creative platforms, game soundtrack generators, and personalized music experiences.

✍️ Lyrics & Creative Tools

Integrate the Suno Lyrics API into writing tools, music platforms, or AI creative applications. Generate lyrics first, then feed them directly into the music generation step.

🔄 Async Music Processing Pipelines

Handle long-running AI music generation tasks using polling or webhook callbacks. Suitable for backend services, batch processing systems, and scalable architectures.

🎚️ Remix, Cover & Stems Workflows

Create remix tools, cover generation systems, or audio editing pipelines. Use the Stems API to separate vocals and instrumentals from any generated track for further processing.

📱 Content & Media Platforms

Add AI-generated music features to video platforms, social apps, or content creation tools. Generate background music, theme songs, or branded audio at scale.

What You Can Build with the Suno API

Goal	API Endpoint
Generate a full song from a text prompt	Suno Music API
Create lyrics before music generation	Suno Lyrics API
Continue and extend an existing track	Suno Extend API
Recreate a song in a new style	Suno Cover API
Upload reference audio before generation	Suno Upload API
Separate vocals and instrumentals	Suno Stems API
Full multi-track stem separation	Suno Stems All API
Poll async job status and retrieve results	Suno Fetch API
Add a vocal layer to an arrangement	Suno Add Vocals API
Trim an existing song by time range	Suno Crop API
Delete a selected time range from a song	Suno Remove Section API
Add a fade-in to an existing song	Suno Fade In API
Add a fade-out to an existing song	Suno Fade Out API
Change song speed while optionally preserving pitch	Suno Adjust Speed API
Export higher-quality WAV output	Suno WAV API

Core Suno API Endpoints

Use Case	Best Reference Page
Full song generation from a prompt	Suno Music API Reference
Lyrics generation before music	Suno Lyrics API Reference
Continue a strong song draft	Suno Extend API Reference
Restyle an existing song	Suno Cover API Reference
Upload source audio or reference material	Suno Upload API Reference
Split vocals and accompaniment	Suno Stems API Reference
Full-track stem separation	Suno Stems All API Reference
Poll async task status	Suno Fetch API Reference
Add a vocal layer to an arrangement	Suno Add Vocals API Reference
Trim a song by start and end time	Suno Crop API Reference
Add a fade-in effect	Suno Fade In API Reference
Add a fade-out effect	Suno Fade Out API Reference
Export higher-quality WAV output	Suno WAV API Reference

Common Suno API Workflows

Workflow	Recommended Path
Text prompt → full song	Lyrics (optional) → Music → Fetch
Reference audio → new output	Upload → downstream endpoint → Fetch
Continue a strong draft	Extend → Fetch
Restyle an existing song	Cover → Fetch
Separate vocals and backing track	Stems or Full Stems

Fetch vs Webhook: Choosing an Async Pattern

Most Suno API workflows are asynchronous. The two retrieval patterns are: Polling with Fetch — call GET /suno/v2/fetch?jobId=... on a loop until status is SUCCESS. Easier for first integrations and works with any HTTP client. Webhook Callback — pass a hookUrl in the generation request. TTAPI will POST the completed result to your endpoint. Better for production systems with a public callback URL already in place. For a full async design walkthrough, see Suno API Async Workflow.

Recommended First Production Path

Read Gateway & Auth — ensure your app sends a valid TT-API-KEY.
Complete the Suno API Quickstart — shortest path to a working integration.
Submit music generation via the Suno Music API.
Store the returned jobId and retrieve results via Suno Fetch or a hookUrl.
Add post-processing with Extend, Cover, Stems, or WAV export.

Error Codes & Troubleshooting

Common Error Status Codes

Status Code	Error Message	Meaning & Fix
`400`	`Job not exits.`, `mv cannot be empty.`	Invalid request parameters. Check and correct before retrying.
`400`	`Request parameter type mismatch`	JSON body malformed or parameter type mismatch. Validate your request schema.
`400`	`A technical issue with Suno is affecting everyone right now...`	Suno platform outage or maintenance. Retry after a delay.
`401`	`Wrong TT-API-KEY or email is not activated.`	Missing or invalid `TT-API-KEY`, or account email not activated.
`402`	`Insufficient balance in TT API.`	Account balance too low. Top up your TTAPI credits.
`403`	`Authorized Error:[Account Block]`	Calling account has been blocked. Contact support.
`404`	`Interface Not Found`	Request path did not match a valid endpoint. Check the URL.
`405`	`Request method not supported`	Wrong HTTP method used. Check `GET` vs `POST`.
`415`	`Content type not supported`	Set `Content-Type: application/json` in your request header.
`429`	`Too Many Requests`	Rate limited. Add retry logic with exponential backoff.
`499`	`You have reached the maximum of suno job queues.`	Suno queue full. Retry later.
`500`	`Submission failed, system exception.`	Server-side exception. Contact support if persistent.

Quick Troubleshooting Checklist

400 / 404 / 405 / 415 → Check request path, HTTP method, JSON body structure, and Content-Type header.
401 / 402 / 403 → Check TT-API-KEY validity, account activation, block status, and balance.
429 / 499 → Add retry logic with exponential backoff. Do not hammer the endpoint.
500 → Wait and retry. Contact the TTAPI team if the error persists.

Why Use TTAPI for Suno API Access

Unified gateway — access Suno and other AI models through a single API key and base URL
Latest model support — always on the newest Suno version, including chirp-v5
Standardized async workflow — consistent job submission, Fetch polling, and webhook callback patterns
Clear documentation — separated overview guides and endpoint references for faster development
Consistent billing — unified quota management across all supported audio and AI APIs
Production-ready — stable request handling and scalable infrastructure for high-volume use

Suno API FAQ

What is the Suno API?

The Suno API is the developer interface for AI music generation using Suno’s models. It accepts text prompts and returns fully generated audio tracks — complete with vocals, instrumentation, and lyrics. Through TTAPI, it also supports async workflows, webhook callbacks, stems separation, and multi-format audio export.

How do I generate music with the Suno API?

Submit a POST request to the Suno Music API with your prompt, style tags, and model version (chirp-v5 for the latest Suno v5 model). Store the returned jobId, then retrieve the generated audio via the Suno Fetch API or a webhook.

Which Suno model should I use?

Use chirp-v5 (Suno v5) for the highest quality output. It produces the most realistic vocals, best musical structure, and longest generation lengths available through the API. See the Music API reference for the full list of supported mv values.

What does the `weirdnessConstraint` parameter do?

The weirdnessConstraint parameter controls how far the AI music generation deviates from conventional musical patterns. A higher value produces more experimental and unconventional output. A lower value keeps the result closer to standard song structure and genre conventions. It can be set during music submission and appears in the fetch result payload under each music item.

How do I check job status?

Use the Suno Fetch API with your jobId to poll for status. While processing, status returns ON_QUEUE. When complete, status returns SUCCESS and the full audio URLs are included in the response.

Does the Suno API support webhooks?

Yes. Pass a hookUrl parameter when submitting any Suno job. TTAPI will deliver the completed result via HTTP POST to your endpoint, eliminating the need for polling. See Suno API Async Workflow for full webhook implementation details.

Can I generate instrumental music without vocals?

Yes. Set "instrumental": true in your music generation request. The Suno API will generate a full track without any vocal content.

Can I upload my own audio as a reference?

Yes. Use the Suno Upload API to upload source audio or reference material before passing it to a downstream generation endpoint.

Can I separate vocals and instruments from a generated track?

Yes. Use the Suno Stems API for two-track separation (vocals + instrumental), or the Suno Stems All API for full multi-track stem separation.

What pages should I read next?

Start with the Suno API Quickstart, then explore the Music API and Fetch API for the core generate-and-retrieve workflow. For async design decisions, read Suno API Async Workflow.

​Suno API Documentation — AI Music Generation, Lyrics & Audio

​What Is the Suno API?

​Get Started with Suno API

​Key Features of the Suno API

​🎵 AI Music Generation with Suno v5

​⚡ Asynchronous & Scalable Workflow

​🎚️ Stems & Vocal Separation

​🎼 Lyrics Generation & Custom Mode

​🧩 Developer-Friendly REST API

​Authentication & Base URL

​Suno API End-to-End Example

​Step 1 — Submit a Music Generation Request

​Step 2 — Read the Immediate Response

​Step 3 — Fetch the Generation Result

​Suno API Parameters Reference

​Core Generation Parameters (POST /suno/v1/music)

​Advanced Audio Parameters

​Common Use Cases

​🎧 AI Music Generation Apps

​✍️ Lyrics & Creative Tools

​🔄 Async Music Processing Pipelines

​🎚️ Remix, Cover & Stems Workflows

​📱 Content & Media Platforms

​What You Can Build with the Suno API

​Core Suno API Endpoints

​Common Suno API Workflows

​Fetch vs Webhook: Choosing an Async Pattern

​Recommended First Production Path

​Error Codes & Troubleshooting

​Common Error Status Codes

​Quick Troubleshooting Checklist

​Why Use TTAPI for Suno API Access

​Suno API FAQ

​What is the Suno API?

​How do I generate music with the Suno API?

​Which Suno model should I use?

​What does the weirdnessConstraint parameter do?

​How do I check job status?

​Does the Suno API support webhooks?

​Can I generate instrumental music without vocals?

​Can I upload my own audio as a reference?

​Can I separate vocals and instruments from a generated track?

​What pages should I read next?