Skip to main content

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 Quickstart

This guide is the fastest path to a working Suno API integration on TTAPI. It is designed for teams that want to go from API key to first completed song without reading every endpoint page first. For the complete docs hub, start with the Suno API docs overview.

​
What this quickstart covers

  • Getting your TT-API-KEY
  • Choosing the first Suno endpoint to call
  • Creating lyrics or going straight to music generation
  • Fetching asynchronous results
  • Continuing the workflow with cover, extend, stems, or export steps

​
1. Prepare your account

Before you call Suno endpoints, make sure you have:
  • A valid TT-API-KEY
  • Access to the TTAPI gateway described in Gateway & Auth
  • Enough quota for the endpoints you plan to use in Audio Pricing
The standard gateway pattern is:
  • Base URL: https://api.ttapi.io
  • Header: TT-API-KEY
  • Response flow: submit request -> store data.job_id -> fetch result or wait for hookUrl

​
2. Pick your starting endpoint

Use the endpoint that matches your real starting asset:
Starting pointBest first endpoint
You have only a prompt or song ideaSuno Music API
You want help writing lyrics firstSuno Lyrics API
You already have reference audioSuno Upload API
You want to reuse an existing song structureSuno Extend API or Suno Cover API

​
3. Submit your first generation request

The most common first integration starts with Suno Music API. 
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"
  }'
If the request is accepted, you should receive an immediate task response: 
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
Store data.jobId immediately. You will use that same value as the jobId query parameter when calling Fetch V2.

​
4. Fetch the result with the returned job ID

Once you have the task ID, fetch the latest status and final media payload like this: 
curl --request GET 'https://api.ttapi.io/suno/v2/fetch?jobId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'TT-API-KEY: YOUR_TTAPI_KEY'
The fetch endpoint can return ON_QUEUE, SUCCESS, or FAILED. A completed music task looks like this: 
{
  "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 a first production-ready flow, persist at least:
  • data.jobId from the submit response
  • status and progress from fetch
  • musicId, audioUrl, videoUrl, and createdAt from the final musics array

​
5. Decide between polling and webhooks

Many Suno integrations are built around background jobs. That means your app usually needs to choose one of these patterns:
  • Poll Fetch V2 until the job is finished
  • Or pass a hookUrl during submission and receive a callback when the task completes
Polling is usually the easiest way to ship the first integration. Webhooks are usually better once your backend already has a stable callback endpoint and retry handling. If you are designing a job queue, retry logic, or webhook handler, read the Suno async workflow guide.

​
6. Add the most useful follow-up endpoints

Once the first generation flow works, these are usually the next endpoints teams adopt:

​
Common integration mistakes

  • Starting with the wrong endpoint instead of matching the real source asset
  • Treating async jobs as if they return final media immediately
  • Forgetting to store data.job_id for result polling
  • Using Suno Stems API when you actually need the more detailed Full Stems API
  • Skipping pricing review before enabling higher-cost post-processing endpoints
Last modified on April 17, 2026