# Suno API

## Authentication

All endpoints require a Bearer token in the Authorization header:

```
Authorization: Bearer your-api-key-here
```

## Pricing

**Suno Music -&#x20;**<mark style="color:$success;">**$0.06**</mark>\
**Suno Add Vocals -&#x20;**<mark style="color:$success;">**$0.06**</mark>\
**Suno Add Instrumental -&#x20;**<mark style="color:$success;">**$0.06**</mark>\
**Suno Extend -&#x20;**<mark style="color:$success;">**$0.06**</mark>\
**Suno Cover -**<mark style="color:$success;">**$0.06**</mark>\
**Suno Stems -&#x20;**<mark style="color:$success;">**$0.05**</mark>\
**Suno Stems All -&#x20;**<mark style="color:$success;">**$0.20**</mark>\
**Suno Lyrics -&#x20;**<mark style="color:$success;">**$0.012**</mark>

## 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:**&#x20;

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

&#x20;**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:**

```bash
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:**

```bash
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:**

```json
{
    "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):**

```bash
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):**

```bash
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)**

```bash
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)**

```bash
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:**

```json
{
    "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:**

```bash
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:**

```json
{
    "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:**

```bash
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:**

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

**Example Request:**

```bash
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:**

```json
{
    "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:**

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

**Example Request:**

```bash
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:**

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

**Example Request:**

```bash
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:**

```json
{
    "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:**

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

**Response:**

```json
{
    "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:**

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

**Example Request:**

```bash
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:**

```json
{
    "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:**

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

**Response:**

```json
{
    "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:**

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

**Response:**

```json
{
    "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:**

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

**Response:**

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

## Error Responses

All endpoints return detailed error information:

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

For validation errors:

```json
{
    "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
