Suno API

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer your-api-key-here

Pricing

Suno Music - $0.06 Suno Add Vocals - $0.06 Suno Add Instrumental - $0.06 Suno Extend - $0.06 Suno Cover -$0.06 Suno Stems - $0.05 Suno Stems All - $0.20 Suno Lyrics - $0.012

Available Models

Music Generation Models:

chirp-v3-0 - Version 3.0
chirp-v3-5 - Version 3.5
chirp-v4 - Version 4.0
chirp-auk - Version 4.5
chirp-bluejay - Version 4.5+
chirp-crow - Version 5.0

Lyrics Generation Models:

remi-v1 - Primary lyrics model
default - Default lyrics model

Model Limits:

v3.5, v4 - Prompt 3,000 characters, Style 200 characters

v4.5, 4.5 Plus & v5 - Prompt 5,000 characters, Style 1,000 characters

In simple mode prompt regardless of the model can not be more than 500 characters

Available Endpoints

1. Music Generation

Generate music using simple or custom mode in a unified endpoint.

Endpoint: POST /suno/music

Simple Mode Example:

curl -X POST "https://api.unifically.com/suno/music" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "mv": "chirp-bluejay",
    "custom": false,
    "gpt_description_prompt": "[Verse 1]\nHello world\n[Chorus]\nThis is my song",
    "make_instrumental": true,
    "title": "My First Song"
}'

Custom Mode Example:

curl -X POST "https://api.unifically.com/suno/music" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "mv": "chirp-bluejay",
    "custom": true,
    "make_instrumental": true,
    "prompt": "An upbeat pop song with electronic elements",
    "title": "Custom Song",
    "negative_tags": "metal, jazz",
    "advanced_settings": {
        "style_weight": 0.7,
        "weirdness_constraint": 0.3,
        "vocal_gender": "f"
    }
}'

Response:

{
    "success": true,
    "data": {
        "clips": [
            {
                "status": "submitted",
                "title": "My First Song",
                "id": "4b514310-36ef-4c45-8e37-28b05a233930",
                "major_model_version": "v4.5",
                "model_name": "chirp-bluejay",
                "created_at": "2025-09-22T05:14:19.463Z"
            },
            {
                "status": "submitted", 
                "title": "My First Song",
                "id": "a970da4a-8b4f-4112-8276-cba4446f6335",
                "major_model_version": "v4.5",
                "model_name": "chirp-bluejay",
                "created_at": "2025-09-22T05:14:19.463Z"
            }
        ]
    }
}

2. Extend Music

Extend an existing song or upload audio to extend it.

Endpoint: POST /suno/extend

Extend Existing Clip Example (Simple):

curl -X POST "https://api.unifically.com/suno/extend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "make_instrumental": true,
    "custom": false,
    "mv": "chirp-bluejay",
    "clip_id": "69ad968a-23c4-40e0-9cdc-80f9649c5209",
    "continue_at": 99.6,
    "gpt_description_prompt": "prompt"
}'

Upload and Extend Example (Custom):

curl -X POST "https://api.unifically.com/suno/extend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "custom": true,
    "mv": "chirp-bluejay",
    "audio_url": "https://example.com/audio.mp3",
    "continue_at": 60,
    "prompt": "Lyrics",
    "title": "Extended Version",
    "advanced_settings": {
        "audio_weight": 0.8,
        "vocal_gender": "m"
    }
}'

Response: Same format as Music Generation

3. Cover Generation

Generate a cover version of an existing song or uploaded audio.

Endpoint: POST /suno/cover

Request Body:

Cover Existing Clip Example (Simple)

curl -X POST "https://api.unifically.com/suno/cover" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "make_instrumental": true,
    "custom": false,
    "clip_id": "5a6bb955-1536-4f43-877a-b4aa9fb18a4e",
    "gpt_description_prompt": "My custom cover lyrics"
}'

Upload and Cover Example (Custom)

curl -X POST "https://api.unifically.com/suno/cover" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "make_instrumental": true,
    "custom": true,
    "audio_url": "https://example.com/audio.mp3",
    "prompt": "Jazz style cover",
    "title": "My Cover Version",
    "advanced_settings": {
        "audio_weight": 0.8,
        "vocal_gender": "m"
    }
}'

Response: Same format as Music Generation

4. Add Vocals

Add vocals to uploaded music (only works with uploaded audio, not Suno-generated).

Endpoint: POST /suno/add-vocals

Request Body:

{
    "mv": "required",                           // Model version (see Available Models above)
    "clip_id": "required",                      // ID of uploaded audio clip
    "prompt": "optional",                       // prompt
    "make_instrumental": "optional",            // Boolean: Generate instrumental version
    "title": "optional",                        // Title for the result
    "start_s": "optional",                      // Number: Start time in seconds for vocal overlay
    "end_s": "optional",                        // Number: End time in seconds for vocal overlay
    "advanced_settings": {                      // Optional advanced controls
        "style_weight": "optional",             // Number 0.0-1.0: Style adherence
        "weirdness_constraint": "optional",     // Number 0.0-1.0: Experimental level
        "audio_weight": "optional",             // Number 0.0-1.0: Audio quality priority
        "vocal_gender": "optional"              // String: "m" or "f"
    }
}

Example Request:

curl -X POST "https://api.unifically.com/suno/add-vocals" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "mv": "chirp-bluejay",
    "clip_id": "ec0be483-2de2-4abc-a5ce-3d8258f52ed4",
    "gpt_description_prompt": "[Verse 1]\nNew vocal lyrics here",
    "start_s": 10,
    "end_s": 60
}'

Response: Same format as Music Generation

5. Add Instrumental

Add instrumental backing to uploaded music (only works with uploaded audio, not Suno-generated).

Endpoint: POST /suno/add-instrumental

Request Body, Custom mode:

{
    "mv": "required",                           // Model version (see Available Models above)
    "clip_id": "required",                      // ID of uploaded audio clip
    "prompt": "optional",                       // Description
    "make_instrumental": "optional",            // Boolean: Generate instrumental version
    "title": "optional",                        // Title for the result
    "start_s": "optional",                      // Number: Start time in seconds for instrumental overlay
    "end_s": "optional",                        // Number: End time in seconds for instrumental overlay
    "advanced_settings": {                      // Optional advanced controls
        "style_weight": "optional",             // Number 0.0-1.0: Style adherence
        "weirdness_constraint": "optional",     // Number 0.0-1.0: Experimental level
        "audio_weight": "optional",             // Number 0.0-1.0: Audio quality priority
        "vocal_gender": "optional"              // String: "m" or "f"
    }
}

Simple mode:

curl -X POST "https://api.unifically.com/suno/add-instrumental" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "mv": "chirp-bluejay",
    "clip_id": "ec0be483-2de2-4abc-a5ce-3d8258f52ed4",
    "gpt_description_prompt": "Hip-hop beats with 808 bass",
    "start_s": "optional",
    "end_s": "optional"
}'

Response: Same format as Music Generation

6. Extract Stems (Vocals and Instrumental)

Extract vocals and instrumental tracks from a song.

Endpoint: POST /suno/stems

Request Body:

{
    "clip_id": "required",       // ID of song to extract stems from
    "title": "optional"          // Title for stem extraction
}

Example Request:

curl -X POST "https://api.unifically.com/suno/stems" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "clip_id": "1901ec96-72c6-4c26-8e56-91028ca6070d",
    "title": "My Stems"
}'

Response:

{
    "success": true,
    "data": {
        "clips": [
            {
                "title": "My Stems",
                "id": "stem-id-1",
                "stem_type_group_name": "Two"
            },
            {
                "title": "My Stems", 
                "id": "stem-id-2",
                "stem_type_group_name": "Two"
            }
        ]
    }
}

7. Extract All Stems

Extract all available stems from a song (vocals, instrumental, drums, bass, etc.).

Endpoint: POST /suno/stems-all

Request Body:

{
    "clip_id": "required",       // ID of song to extract all stems from
    "title": "optional"          // Title for stem extraction
}

Example Request:

curl -X POST "https://api.unifically.com/suno/stems-all" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "clip_id": "1901ec96-72c6-4c26-8e56-91028ca6070d",
    "title": "All My Stems"
}'

Response: Same format as Extract Stems

8. Generate Lyrics

Generate lyrics based on a description. Returns IDs that can be used to fetch the completed lyrics.

Endpoint: POST /suno/lyrics

Request Body:

{
    "prompt": "required",    // Description of lyrics to generate
    "mv": "required"         // Lyrics model version (see Available Models above)
}

Example Request:

curl -X POST "https://api.unifically.com/suno/lyrics" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "prompt": "A chill rock song about summer days",
    "mv": "remi-v1"
}'

Response:

{
    "success": true,
    "data": {
        "lyrics_request_id": "d67ddf79-9fd6-4459-8051-bf1b245fa9a4",
        "lyrics_a_id": "98a79972-43a9-438f-a9ca-d3bf114eea1d",
        "lyrics_b_id": "9052d98c-6481-4c9b-bd8b-c9ee30a83dc3"
    }
}

9. Fetch Lyrics

Fetch the completed lyrics using the lyrics ID from the generate endpoint.

Endpoint: GET /suno/lyrics/:lyricsId

Example Request:

curl "https://api.unifically.com/suno/lyrics/98a79972-43a9-438f-a9ca-d3bf114eea1d" \
  -H "Authorization: Bearer your-api-key"

Response:

{
    "success": true,
    "data": {
        "text": "[Verse]\nBack on the run again\nBut I was blue in the morning\nTried to let it go\nNow I guess I'm holding on\n\n[Prechorus]\nAnd the summer days come\nAnd the summer days go\nWhere do you go?\n\n[Chorus]\nCan you feel it?\nCan you feel it?\nCan you feel it?\nCan you feel it?\nCan you feel it?\nCan you feel it?",
        "title": "Blue in the Morning",
        "status": "complete",
        "error_message": "",
        "tags": [
            "acoustic",
            "rock",
            "chill"
        ]
    }
}

10. Convert to WAV

Convert a song to WAV format and get download URL.

Endpoint: POST /suno/wav

Request Body:

{
    "clip_id": "required"    // ID of song to convert
}

Example Request:

curl -X POST "https://api.unifically.com/suno/wav" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "clip_id": "5e01ffc9-ecf9-431c-b4b0-2f88ed9ffe20"
}'

Response:

{
    "success": true,
    "data": {
        "wav_url": "https://cdn1.suno.ai/converted.wav"
    }
}

10. Get Feed Info

Get detailed information about generation tasks (includes audio/video URLs when ready).

Endpoint: GET /suno/feed/:taskIds

Example Request:

curl "https://api.unifically.com/suno/feed/task1,task2,task3" \
  -H "Authorization: Bearer your-api-key"

Response:

{
    "success": true,
    "data": {
        "clips": [
            {
                "status": "complete",
                "title": "My Song",
                "id": "4b514310-36ef-4c45-8e37-28b05a233930",
                "video_url": "https://cdn1.suno.ai/video.mp4",
                "audio_url": "https://cdn1.suno.ai/audio.mp3",
                "image_url": "https://cdn1.suno.ai/image.jpg",
                "image_large_url": "https://cdn1.suno.ai/image_large.jpg",
                "major_model_version": "v4.5",
                "model_name": "chirp-bluejay",
                "duration": 120.5,
                "created_at": "2025-09-22T05:14:19.463Z",
                "metadata": {
                    "type": "gen"  // "gen" for Suno-generated, "upload" for uploaded audio
                }
            }
        ]
    }
}

11. Get Timestamped Lyrics

Get timestamped/aligned lyrics for a song.

Endpoint: GET /suno/aligned_lyrics/:taskId

Example Request:

curl "https://api.unifically.com/suno/aligned_lyrics/64ea9bb1-e8d0-4395-a4c4-b70d2fa0e3b4" \
  -H "Authorization: Bearer your-api-key"

Response:

{
    "success": true,
    "data": {
        "segments": [
            {
                "start": 0.0,
                "end": 3.2,
                "text": "[Verse 1]"
            },
            {
                "start": 3.2,
                "end": 8.5,
                "text": "Hello world, this is my song"
            }
        ]
    }
}

12. Get Downbeats

Get timing information for song downbeats.

Endpoint: GET /suno/downbeats/:taskId

Example Request:

curl "https://api.unifically.com/suno/downbeats/3544bab1-ac87-4e27-b632-7aac52150099" \
  -H "Authorization: Bearer your-api-key"

Response:

{
    "success": true,
    "data": {
        "downbeats": [0.0, 0.6, 1.2, 1.8, 2.4, 3.0]
    }
}

Error Responses

All endpoints return detailed error information:

{
    "success": false,
    "data": {
        "message": "Failed model quick validation"
    }
}

For validation errors:

{
    "success": false,
    "data": {
        "message": "custom parameter is required (true for custom mode, false for simple mode)"
    }
}

Advanced Settings

For custom mode endpoints, advanced settings provide fine-grained control:

style_weight (0.0-1.0): Controls how closely the generation follows the style description
weirdness_constraint (0.0-1.0): Controls experimental/creative freedom (0 = conservative, 1 = experimental)
audio_weight (0.0-1.0): Prioritizes audio quality vs style matching
vocal_gender ("m" or "f"): Specifies preferred vocal gender

PreviousGet Task

Last updated 1 day ago