Skip to main content
POST
/
suno
/
v1
/
music
cURL
curl --request POST \
  --url https://api.ttapi.io/suno/v1/music \
  --header 'Content-Type: application/json' \
  --header 'TT-API-KEY: <api-key>' \
  --data '
{
  "custom": false,
  "instrumental": false,
  "mv": "chirp-v5",
  "gpt_description_prompt": "Night city lo-fi piano with rain ambience, soft vocal phrases, theme: \"Under the city lights\"",
  "prompt": "<string>",
  "title": "<string>",
  "tags": "rock, blues, hip-hop, r&b",
  "negative_tags": "<string>",
  "style_weight": 0.5,
  "weirdness_constraint": 0.5,
  "audio_weight": 0.5,
  "auto_lyrics": false,
  "vocal_gender": "Male",
  "persona_id": "<string>",
  "isStorage": false,
  "hookUrl": "<string>"
}
'
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "job_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

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.

Start here if you need the main endpoint for Suno API music generation. For the complete endpoint directory, workflow guidance, and related links, see the Suno API overview.

Authorizations

​
TT-API-KEY
string
header
required

You can obtain your API key from the TTAPI Dashboard.

Body

application/json
​
custom
boolean
default:false
required

Whether to use custom mode.

  • true: Audio will be generated from lyrics
  • false: Audio will be generated based on inspiration mode prompts
​
instrumental
boolean
default:false
required

Whether to generate instrumental music.

  • true: Generate instrumental-only music
  • false: Generate a track with vocals and lyrics
    • In inspiration mode, the gpt_description_prompt parameter is required
    • In custom mode, the prompt parameter is required
​
mv
enum<string>
default:chirp-v5
required

Model to use.

Available options:
chirp-v5-5,
chirp-v5,
chirp-v4-5+,
chirp-v4-5,
chirp-v4-5-all,
chirp-v4,
chirp-v3-5,
chirp-v3-0
​
gpt_description_prompt
string

Prompt for inspiration mode.

When not using custom mode (custom=false), this parameter is always required. Lyrics will be automatically generated from this prompt. Maximum length: 500 characters.

Example:

"Night city lo-fi piano with rain ambience, soft vocal phrases, theme: \"Under the city lights\""

​
prompt
string

Lyrics.

Used in custom mode (custom=true). Required when instrumental is false. The lyrics will be used and sung in the generated track.

​
title
string

Music title.

Used in custom mode (custom=true). Maximum length: 80 characters.

​
tags
string

Music style or genre.

Used in custom mode (custom=true).

Example:

"rock, blues, hip-hop, r&b"

​
negative_tags
string

Music styles or genres that should be excluded from generation.

Used in custom mode (custom=true).

​
style_weight
number

Music style weight, range: 0.00–1.00.

Used in custom mode. Valid range: 0 <= x <= 1.

Example:

0.5

​
weirdness_constraint
number

Audio creativity (weirdness) weight, range: 0.00–1.00.

Used in custom mode. Valid range: 0 <= x <= 1.

Example:

0.5

​
audio_weight
number

Audio weight, range: 0.00–1.00.

Used in custom mode. Valid range: 0 <= x <= 1.

Example:

0.5

​
auto_lyrics
boolean
default:false

Whether to automatically generate lyrics. Custom mode only.

  • true: The input lyrics will be creatively rewritten, similar to the inspiration mode prompt effect
  • false: Use the provided lyrics directly to generate the music
​
vocal_gender
enum<string>

Vocal gender.

  • Male: Male voice

  • Female: Female voice

Available options:
Male,
Female
​
persona_id
string

Music style ID. Custom mode only.

Use this parameter to generate music with a specific style.

​
isStorage
boolean
default:false

Whether to store the generated audio.

  • true: The audio will be stored and a TTAPI CDN URL will be returned
  • false: The original source URL will be returned
​
hookUrl
string

Callback notification URL

Response

Request successful

​
status
string
required
Example:

"SUCCESS"

​
message
string
required
Example:

"success"

​
data
object
required
Example:
{
  "job_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Last modified on April 17, 2026