Suno Music Format (Music)

Suno Music Format

Overview

Please note

This interface is not the official Suno API. It is a Suno proxy API implemented based on the open-source project Suno-API by the author Plato.

We’re very grateful for the author’s contribution, which makes it easy for us to use Suno’s powerful features. If you have time, please give the author a Star.

📝 Introduction

Suno Music API provides a set of music generation and processing capabilities, including:

• Generate songs from prompts (inspiration mode, custom mode)
• Continue existing songs
• Concatenate multiple audio clips
• Generate lyrics
• Upload audio

With the API, you can easily integrate AI music generation into your application.

💡 Request Examples

Generate Songs ✅

curl --location 'https://4All API地址/suno/submit/music' \
--header 'Authorization: Bearer $NEWAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt":"[Verse]\nWalking down the streets\nBeneath the city lights\nNeon signs flickering\nLighting up the night\nHeart beating faster\nLike a drum in my chest\nI'\''m alive in this moment\nFeeling so blessed\n\nStilettos on the pavement\nStepping with grace\nSurrounded by the people\nMoving at their own pace\nThe rhythm of the city\nIt pulses in my veins\nLost in the energy\nAs my worries drain\n\n[Verse 2]\nConcrete jungle shining\nWith its dazzling glow\nEvery corner hiding secrets that only locals know\nA symphony of chaos\nBut it'\''s music to my ears\nThe hustle and the bustle\nWiping away my fears",
    "tags":"emotional punk",
    "mv":"chirp-v4",
    "title":"City Lights"
}'

Response example:

{
  "code":"success",
  "message":"",
  "data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}

Generate Lyrics ✅

curl --location 'https://4All API地址/suno/submit/lyrics' \
--header 'Authorization: Bearer $NEWAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt":"dance"
}'

Response example:

{
  "code":"success",
  "message":"",
  "data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}

Upload Audio ❌

curl --location 'https://4All API地址/suno/uploads/audio-url' \
--header 'Authorization: Bearer $NEWAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "url":"http://cdnimg.example.com/ai/2024-06-18/d416d9c3c34eb22c7d8c094831d8dbd0.mp3"
}'

Response example:

{
  "code":"success",
  "message":"",
  "data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}

Song Concatenation ❌

curl --location 'https://4All API地址/suno/submit/concat' \
--header 'Authorization: Bearer $NEWAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "clip_id":"extend 后的 歌曲ID",
    "is_infill": false
}'

Response example:

{
  "code":"success",
  "message":"",
  "data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}

Query Task Status ✅

Batch Query

curl --location 'https://4All API地址/suno/fetch' \
--header 'Authorization: Bearer $NEWAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "ids":["task_id"],
    "action":"MUSIC"
}'

Response example:

{
  "code":"success",
  "message":"",
  "data":[
    {
      "task_id":"346c5d10-a4a1-4f49-a851-66a7dae6cfaf",
      "notify_hook":"",
      "action":"MUSIC",
      "status":"IN_PROGRESS",
      "fail_reason":"",
      "submit_time":1716191749,
      "start_time":1716191786,
      "finish_time":0,
      "progress":"0%",
      "data":[
        {
          "id":"e9893d04-6a63-4007-8473-64b706eca4d1",
          "title":"Electric Dance Party",
          "status":"streaming",
          "metadata":{
            "tags":"club banger high-energy edm",
            "prompt":"略",
            "duration":null,
            "error_type":null,
            "error_message":null,
            "audio_prompt_id":null,
            "gpt_description_prompt":"miku dance"
          },
          "audio_url":"https://audiopipe.suno.ai/?item_id=e9893d04-6a63-4007-8473-64b706eca4d1",
          "image_url":"https://cdn1.suno.ai/image_e9893d04-6a63-4007-8473-64b706eca4d1.png",
          "video_url":"",
          "model_name":"chirp-v3",
          "image_large_url":"https://cdn1.suno.ai/image_large_e9893d04-6a63-4007-8473-64b706eca4d1.png",
          "major_model_version":"v3"
        }
      ]
    }
  ]
}

Single Query

curl --location 'https://4All API地址/suno/fetch/{{task_id}}' \
--header 'Authorization: Bearer $NEWAPI_API_KEY'

Response example:

{
  "code":"success",
  "message":"",
  "data":{
    "task_id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
    "notify_hook":"",
    "action":"LYRICS",
    "status":"SUCCESS",
    "fail_reason":"",
    "submit_time":1716192124,
    "start_time":1716192124,
    "finish_time":1716192124,
    "progress":"100%",
    "data":{
      "id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
      "text":"略",
      "title":"Electric Fantasy",
      "status":"complete"
    }
  }
}

📮 Request

All requests must include authentication information in the request headers:

Authorization: Bearer $NEWAPI_API_KEY

Endpoints

Generate Songs

POST /suno/submit/music

Generate a new song. Supports inspiration mode, custom mode, and continuation.

Generate Lyrics

POST /suno/submit/lyrics

Generate lyrics from a prompt.

Upload Audio

POST /suno/uploads/audio-url

Upload an audio file.

Song Concatenation

POST /suno/submit/concat

Concatenate multiple audio clips into a complete song.

Batch Query Task Status

POST /suno/fetch

Retrieve the status and results of multiple tasks in batches.

Query Single Task Status

GET /suno/fetch/{{task_id}}

Query the status and results of a single task.

Request Body Parameters

Generate Songs

prompt

• Type: String
• Required: Not required in inspiration mode, required in custom mode
• Description: Lyrics content; must be provided in custom mode

mv

• Type: String
• Required: No
• Description: Model version. Optional values: chirp-v3-0, chirp-v3-5. Defaults to chirp-v3-0

title

• Type: String
• Required: Not required in inspiration mode, required in custom mode
• Description: Song title; must be provided in custom mode

tags

• Type: String
• Required: Not required in inspiration mode, required in custom mode
• Description: Song style tags, separated by commas; must be provided in custom mode

make_instrumental

• Type: Boolean
• Required: No
• Description: Whether to generate instrumental music. true generates instrumental music

task_id

• Type: String
• Required: Required for continuation
• Description: The task ID of the song to continue

continue_at

• Type: Float
• Required: Required for continuation
• Description: The timestamp, in seconds, from which to continue the song

continue_clip_id

• Type: String
• Required: Required for continuation
• Description: The clip ID of the song to continue

gpt_description_prompt

• Type: String
• Required: Required in inspiration mode, not required in other modes
• Description: Text description of the inspiration source

notify_hook

• Type: String
• Required: No
• Description: Callback URL for completion notification when the song generation finishes

Generate Lyrics

prompt

• Type: String
• Required: Yes
• Description: The theme or keywords for the lyrics

notify_hook

• Type: String
• Required: No
• Description: Callback URL for completion notification when lyric generation finishes

Upload Audio

url

• Type: String
• Required: Yes
• Description: The URL of the audio file to upload

Song Concatenation

clip_id

• Type: String
• Required: Yes
• Description: The ID of the song clip to concatenate

is_infill

• Type: Boolean
• Required: No
• Description: Whether this is infill mode

Task Query

ids

• Type: String[]
• Required: Yes
• Description: List of task IDs to query

action

• Type: String
• Required: No
• Description: Task type. Optional values: MUSIC, LYRICS

📥 Response

All endpoints return a unified JSON response format:

{
  "code":"success",
  "message":"",
  "data":"{{RESULT}}"
}

Success Response

Basic Response Fields

code

• Type: String
• Description: Request status. success indicates success

message

• Type: String
• Description: Error message when the request fails

data

• Type: Varies by endpoint
• Description: Returned data on success
• Generate Songs, Generate Lyrics, Upload Audio, and Song Concatenation endpoints: returns a task ID string
• Task Query endpoints: returns a task object or an array of task objects

Task-Related Objects

Task Object

task_id

• Type: String
• Description: Task ID

notify_hook

• Type: String
• Description: Callback URL after task completion

action

• Type: String
• Description: Task type. Optional values: MUSIC, LYRICS

status

• Type: String
• Description: Task status. Optional values: IN_PROGRESS, SUCCESS, FAIL

fail_reason

• Type: String
• Description: Reason the task failed

submit_time

• Type: Integer
• Description: Task submission timestamp

start_time

• Type: Integer
• Description: Task start timestamp

finish_time

• Type: Integer
• Description: Task completion timestamp

progress

• Type: String
• Description: Task progress percentage

data

• Type: Varies by task type
• Description:
• Music generation tasks: array of song objects
• Lyrics generation tasks: lyrics object

Song Object

id

• Type: String
• Description: Song ID

title

• Type: String
• Description: Song title

status

• Type: String
• Description: Song status

metadata

• Type: Object
• Description: Song metadata
• tags: Song style tags
• prompt: Lyrics used to generate the song
• duration: Song duration
• error_type: Error type
• error_message: Error message
• audio_prompt_id: Audio prompt ID
• gpt_description_prompt: Inspiration source description

audio_url

• Type: String
• Description: URL of the song audio

image_url

• Type: String
• Description: URL of the song cover image

video_url

• Type: String
• Description: URL of the song video

model_name

• Type: String
• Description: Name of the model used to generate the song

major_model_version

• Type: String
• Description: Major model version

Lyrics Object

id

• Type: String
• Description: Lyrics ID

text

• Type: String
• Description: Lyrics content

title

• Type: String
• Description: Lyrics title

status

• Type: String
• Description: Lyrics status

🌟 Best Practices

• Provide song or lyrics generation prompts that are as detailed and specific as possible; avoid being too vague or abstract
• When querying task status, it is recommended to poll every 2-5 seconds to avoid excessive frequency
• In inspiration mode, you only need to provide the gpt_description_prompt parameter; the API will automatically generate lyrics, title, tags, and more
• Custom mode requires the prompt, title, and tags parameters, giving you finer control over the song
• Use the latest model version whenever possible (for example, chirp-v4) for better results
• Using callback notifications (notify_hook) can reduce polling frequency and improve efficiency
• Music continuation and concatenation can build on existing music to create richer, more complete works
• Be sure to handle possible exceptions and errors, such as network timeouts and parameter validation failures