> ## 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

> Complete Suno API developer documentation. Generate AI music, songs, and lyrics via REST API. Supports Suno v5, async jobs, webhook callbacks, and stems separation. Start building free.

# 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](/grids/en/start/suno-api-quickstart).

> **New to Suno API?** Jump to the [End-to-End Example](#suno-api-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](/grids/en/start/suno-api-quickstart) — fastest path to a working integration
* [Music Generation API](/api/en/suno/suno_music) — submit a song generation job
* [Fetch API (Get Results)](/api/en/suno/suno_fetch_v2) — poll for async results
* [Suno API Async Workflow](/grids/en/start/suno-api-async-workflow) — deep dive on job handling
* [Suno API Workflow Guide](/grids/en/start/suno-api-workflows) — full workflow patterns
* [Audio Pricing](/grids/en/start/pricing/audio#suno) — 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](/grids/en/development/authentication).

***

## Suno API End-to-End Example

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

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

### Step 1 — Submit a Music Generation Request

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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](/api/en/suno/suno_music)                   |
| Create lyrics before music generation               | [Suno Lyrics API](/api/en/suno/suno_lyrics)                 |
| Continue and extend an existing track               | [Suno Extend API](/api/en/suno/suno_extend)                 |
| Recreate a song in a new style                      | [Suno Cover API](/api/en/suno/suno_cover)                   |
| Upload reference audio before generation            | [Suno Upload API](/api/en/suno/suno_upload)                 |
| Separate vocals and instrumentals                   | [Suno Stems API](/api/en/suno/suno_stems)                   |
| Full multi-track stem separation                    | [Suno Stems All API](/api/en/suno/suno_stems_all)           |
| Poll async job status and retrieve results          | [Suno Fetch API](/api/en/suno/suno_fetch_v2)                |
| Add a vocal layer to an arrangement                 | [Suno Add Vocals API](/api/en/suno/suno_add_vocals)         |
| Trim an existing song by time range                 | [Suno Crop API](/api/en/suno/suno_crop)                     |
| Delete a selected time range from a song            | [Suno Remove Section API](/api/en/suno/suno_remove_section) |
| Add a fade-in to an existing song                   | [Suno Fade In API](/api/en/suno/suno_fade_in)               |
| Add a fade-out to an existing song                  | [Suno Fade Out API](/api/en/suno/suno_fade_out)             |
| Change song speed while optionally preserving pitch | [Suno Adjust Speed API](/api/en/suno/suno_adjust_speed)     |
| Export higher-quality WAV output                    | [Suno WAV API](/api/en/suno/suno_wav)                       |

***

## Core Suno API Endpoints

| Use Case                                  | Best Reference Page                                           |
| :---------------------------------------- | :------------------------------------------------------------ |
| Full song generation from a prompt        | [Suno Music API Reference](/api/en/suno/suno_music)           |
| Lyrics generation before music            | [Suno Lyrics API Reference](/api/en/suno/suno_lyrics)         |
| Continue a strong song draft              | [Suno Extend API Reference](/api/en/suno/suno_extend)         |
| Restyle an existing song                  | [Suno Cover API Reference](/api/en/suno/suno_cover)           |
| Upload source audio or reference material | [Suno Upload API Reference](/api/en/suno/suno_upload)         |
| Split vocals and accompaniment            | [Suno Stems API Reference](/api/en/suno/suno_stems)           |
| Full-track stem separation                | [Suno Stems All API Reference](/api/en/suno/suno_stems_all)   |
| Poll async task status                    | [Suno Fetch API Reference](/api/en/suno/suno_fetch_v2)        |
| Add a vocal layer to an arrangement       | [Suno Add Vocals API Reference](/api/en/suno/suno_add_vocals) |
| Trim a song by start and end time         | [Suno Crop API Reference](/api/en/suno/suno_crop)             |
| Add a fade-in effect                      | [Suno Fade In API Reference](/api/en/suno/suno_fade_in)       |
| Add a fade-out effect                     | [Suno Fade Out API Reference](/api/en/suno/suno_fade_out)     |
| Export higher-quality WAV output          | [Suno WAV API Reference](/api/en/suno/suno_wav)               |

***

## Common Suno API Workflows

| Workflow                          | Recommended Path                                                                                                       |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| Text prompt → full song           | [Lyrics](/api/en/suno/suno_lyrics) (optional) → [Music](/api/en/suno/suno_music) → [Fetch](/api/en/suno/suno_fetch_v2) |
| Reference audio → new output      | [Upload](/api/en/suno/suno_upload) → downstream endpoint → [Fetch](/api/en/suno/suno_fetch_v2)                         |
| Continue a strong draft           | [Extend](/api/en/suno/suno_extend) → [Fetch](/api/en/suno/suno_fetch_v2)                                               |
| Restyle an existing song          | [Cover](/api/en/suno/suno_cover) → [Fetch](/api/en/suno/suno_fetch_v2)                                                 |
| Separate vocals and backing track | [Stems](/api/en/suno/suno_stems) or [Full Stems](/api/en/suno/suno_stems_all)                                          |

***

## 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](/grids/en/start/suno-api-async-workflow).

***

## Recommended First Production Path

1. Read [Gateway & Auth](/grids/en/development/authentication) — ensure your app sends a valid `TT-API-KEY`.
2. Complete the [Suno API Quickstart](/grids/en/start/suno-api-quickstart) — shortest path to a working integration.
3. Submit music generation via the [Suno Music API](/api/en/suno/suno_music).
4. Store the returned `jobId` and retrieve results via [Suno Fetch](/api/en/suno/suno_fetch_v2) or a `hookUrl`.
5. Add post-processing with [Extend](/api/en/suno/suno_extend), [Cover](/api/en/suno/suno_cover), [Stems](/api/en/suno/suno_stems), or [WAV export](/api/en/suno/suno_wav).

***

## 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](/api/en/suno/suno_music) 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](/api/en/suno/suno_fetch_v2) 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](/api/en/suno/suno_music) 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](/api/en/suno/suno_fetch_v2) 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](/grids/en/start/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](/api/en/suno/suno_upload) 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](/api/en/suno/suno_stems) for two-track separation (vocals + instrumental), or the [Suno Stems All API](/api/en/suno/suno_stems_all) for full multi-track stem separation.

***

### What pages should I read next?

Start with the [Suno API Quickstart](/grids/en/start/suno-api-quickstart), then explore the [Music API](/api/en/suno/suno_music) and [Fetch API](/api/en/suno/suno_fetch_v2) for the core generate-and-retrieve workflow. For async design decisions, read [Suno API Async Workflow](/grids/en/start/suno-api-async-workflow).