Documentation Index
Fetch the complete documentation index at: https://docs.ttapi.io/llms.txt
Use this file to discover all available pages before exploring further.
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
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 |
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"
}'
{
"status": "SUCCESS",
"message": "success",
"data": {
"jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
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'
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"
}
]
}
}
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.
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 |
| 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 |
| 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.