Suno API

https://docs.sunoapi.org
Admin
Suno API is a platform providing affordable and stable AI music API services for generating music,...
Tokens:154,428
Snippets:1,011
Trust Score:7.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete Suno API Workflow Example

Source: https://docs.sunoapi.org/suno-api/quickstart

This example demonstrates a full workflow using the Suno API, including generating lyrics, music, extending tracks, and separating vocals. It also includes error handling.

```python
from suno_api import SunoApi

api = SunoApi("YOUR_API_KEY")

def main():
    try:
        credits = api.get_remaining_credits()
        print(f'Remaining credits: {credits}')
        
        # Generate lyrics first
        print('Generating lyrics...')
        lyrics_task_id = api.generate_lyrics(
            'A song about adventure and discovery, uplifting and inspiring'
        )
        
        lyrics_result = api.wait_for_completion(lyrics_task_id)
        print('Lyrics generated:', lyrics_result['data'][0]['text'])
        
        # Generate music with custom parameters
        print('Generating music...')
        music_task_id = api.generate_music(
            prompt=lyrics_result['data'][0]['text'],
            customMode=True,
            style='Folk Pop',
            title='Adventure Song',
            instrumental=False,
            model='V4_5',
            callBackUrl='https://your-server.com/music-callback'
        )
        
        # Wait for completion
        music_result = api.wait_for_completion(music_task_id)
        print('Music generated successfully!')
        
        for i, track in enumerate(music_result['data']):
            print(f'Track {i + 1}:')
            print(f'  Title: {track["title"]}')
            print(f'  Duration: {track["duration"]}s')
            print(f'  Audio URL: {track["audio_url"]}')
        
        # Extend the first track
        original_track = music_result['data'][0]
        print('Extending music...')
        extend_task_id = api.extend_music(
            original_track['id'],
            defaultParamFlag=True,
            prompt='Continue with a beautiful instrumental outro',
            continueAt=original_track['duration'] - 30,
            model='V4_5'
        )
        
        extended_result = api.wait_for_completion(extend_task_id)
        print('Extended version created:', extended_result['data'][0]['audio_url'])
        
        # Separate vocals
        print('Separating vocals...')
        separation_task_id = api.separate_vocals(music_task_id, original_track['id'])
        separation_result = api.wait_for_completion(separation_task_id)
        
        print('Vocal separation completed:')
        vocal_info = separation_result['vocal_removal_info']
        print(f'  Instrumental: {vocal_info["instrumental_url"]}')
        print(f'  Vocals only: {vocal_info["vocal_url"]}')
        
    except Exception as error:
        print(f'Error: {error}')

if __name__ == '__main__':
    main()

```

--------------------------------

### Successful WAV Conversion Response Example

Source: https://docs.sunoapi.org/suno-api/get-wav-conversion-details

This example shows the structure of a successful response when retrieving WAV conversion details. It includes task identifiers, music details, callback URL, completion time, audio URL, and status flags.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "988e****c8d3",
    "musicId": "8551****662c",
    "musicIndex": 0,
    "callbackUrl": "https://api.example.com/callback",
    "completeTime": "2025-01-01 00:10:00",
    "response": {
      "audioWavUrl": "https://example.com/s/04e6****e727.wav"
    },
    "successFlag": "SUCCESS",
    "createTime": "2025-01-01 00:00:00",
    "errorCode": null,
    "errorMessage": null
  }
}
```

--------------------------------

### Success Callback Example

Source: https://docs.sunoapi.org/suno-api/replace-section-callbacks

This is an example of a success callback payload received when a replace music section task completes successfully.

```APIDOC
## Request Format

### Success Callback

When the replacement task completes successfully:

```json
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "A calm and relaxing piano track.",
        "model_name": "chirp-v3-5",
        "title": "Relaxing Piano",
        "tags": "Jazz",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}
```
```

--------------------------------

### OpenAPI Response Schema Example

Source: https://docs.sunoapi.org/suno-api/generate-mashup

This is an example of a successful response from the Suno API, detailing the structure of generated audio data and task information.

```json
{
  "task_id": "2fac****9f72",
  "data": [
    {
      "id": "8551****662c",
      "audio_url": "https://example.cn/****.mp3",
      "source_audio_url": "https://example.cn/****.mp3",
      "stream_audio_url": "https://example.cn/****",
      "source_stream_audio_url": "https://example.cn/****",
      "image_url": "https://example.cn/****.jpeg",
      "source_image_url": "https://example.cn/****.jpeg",
      "prompt": "[Verse] Night city lights shining bright",
      "model_name": "chirp-v3-5",
      "title": "Iron Man",
      "tags": "electrifying, rock",
      "createTime": "2025-01-01 00:00:00",
      "duration": 198.44
    }
  ]
}
```

--------------------------------

### Audio Extend Callback Example

Source: https://docs.sunoapi.org/suno-api/upload-and-extend-audio

This JSON structure is an example of the callback received when the audio generation task is complete. It includes the task ID and status.

```json
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {

```

--------------------------------

### Suno API Task Completion Response Example

Source: https://docs.sunoapi.org/suno-api/get-cover-suno-details

This example shows a successful response for a music task, including the task ID, completion time, and generated image URLs.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "21aee3c3c2a01fa5e030b3799fa4dd56",
    "parentTaskId": "73d6128b3523a0079df10da9471017c8",
    "callbackUrl": "https://api.example.com/callback",
    "completeTime": "2025-01-15T10:35:27.000Z",
    "response": {
      "images": [
        "https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png",
        "https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
      ]
    },
    "successFlag": 1,
    "createTime": "2025-01-15T10:33:01.000Z",
    "errorCode": 200,
    "errorMessage": ""
  }
}
```

--------------------------------

### Python Flask Callback Server for Music Generation

Source: https://docs.sunoapi.org/suno-api/generate-music-callbacks

Implement a Flask application to handle music generation callbacks. This example parses JSON data from POST requests, logs task details, and processes successful generations or errors. It includes an example of downloading generated audio files.

```python
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/generate-music-callback', methods=['POST'])
def handle_callback():
    data = request.json
    
    code = data.get('code')
    msg = data.get('msg')
    callback_data = data.get('data', {})
    task_id = callback_data.get('task_id')
    callback_type = callback_data.get('callbackType')
    music_data = callback_data.get('data', [])
    
    print(f"Received music generation callback: {task_id}, type: {callback_type}, status: {code}, message: {msg}")
    
    if code == 200:
        # Task completed successfully
        print("Music generation completed")
        
        print(f"Generated {len(music_data)} music tracks:")
        for i, music in enumerate(music_data):
            print(f"Music {i + 1}:")
            print(f"  Title: {music.get('title')}")
            print(f"  Duration: {music.get('duration')} seconds")
            print(f"  Tags: {music.get('tags')}")
            print(f"  Audio URL: {music.get('audio_url')}")
            print(f"  Cover URL: {music.get('image_url')}")
            
            # Download audio file example
            try:
                audio_url = music.get('audio_url')
                if audio_url:
                    response = requests.get(audio_url)
                    if response.status_code == 200:
                        filename = f"generated_music_{task_id}_{i + 1}.mp3"
                        with open(filename, "wb") as f:
                            f.write(response.content)
                        print(f"Audio saved as {filename}")
            except Exception as e:
                print(f"Audio download failed: {e}")
                
    else:
        # Task failed
        print(f"Music generation failed: {msg}")
        
        # Handle failure cases...
        if code == 400:
            print("Parameter error or content violation")
        elif code == 451:
            print("File download failed")
        elif code == 500:
            print("Server internal error")
    
    # Return 200 status code to confirm callback received
    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)
```

--------------------------------

### Replace Section Request Example

Source: https://docs.sunoapi.org/suno-api/replace-section

Example of a request body for the replace section functionality. Includes task ID, audio ID, prompt, tags, and time interval for replacement.

```json
{
  "taskId": "2fac****9f72",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "prompt": "A calm and relaxing piano track.",
  "tags": "Jazz",
  "title": "Relaxing Piano",
  "negativeTags": "Rock",
  "infillStartS": 10.5,
  "infillEndS": 20.75,
  "callBackUrl": "https://example.com/callback"
}
```

--------------------------------

### Successful MIDI Details Response

Source: https://docs.sunoapi.org/cn/suno-api/get-midi-details

This example shows a successful response containing task details and MIDI data, including instrument information and note timings.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "recordTaskId": "-1",
    "audioId": "e231****-****-****-****-****8cadc7dc",
    "callbackUrl": "https://example.callback",
    "completeTime": 1760335255000,
    "midiData": {
      "state": "complete",
      "instruments": [
        {
          "name": "Drums",
          "notes": [
            {
              "pitch": 73,
              "start": 0.036458333333333336,
              "end": 0.18229166666666666,
              "velocity": 1
            },
            {
              "pitch": 61,
              "start": 0.046875,
              "end": 0.19270833333333334,
              "velocity": 1
            }
          ]
        },
        {
          "name": "Electric Bass (finger)",
          "notes": [
            {
              "pitch": 44,
              "start": 7.6875,
              "end": 7.911458333333333,
              "velocity": 1
            }
          ]
        }
      ]
    },
    "successFlag": 1,
    "createTime": 1760335251000,
    "errorCode": null,
    "errorMessage": null
  }
}
```

--------------------------------

### Success Callback Example

Source: https://docs.sunoapi.org/suno-api/replace-section-callbacks

This JSON structure represents a successful completion callback for a replace music section task. It includes task details, generated audio, and metadata.

```json
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "A calm and relaxing piano track.",
        "model_name": "chirp-v3-5",
        "title": "Relaxing Piano",
        "tags": "Jazz",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}
```

--------------------------------

### Complete Music Generation Workflow (JavaScript)

Source: https://docs.sunoapi.org/suno-api/quickstart

This example demonstrates a full music generation workflow, including generating music, extending it, and separating vocals. It logs the results to the console.

```javascript
musicResult.data.forEach((track, index) => {
          console.log(`Track ${index + 1}:`);
          console.log(`  Title: ${track.title}`);
          console.log(`  Duration: ${track.duration}s`);
          console.log(`  Audio URL: ${track.audio_url}`);
        });
        
        // Extend the first track
        const originalTrack = musicResult.data[0];
        console.log('Extending music...');
        const extendTaskId = await api.extendMusic(originalTrack.id, {
          defaultParamFlag: true,
          prompt: 'Continue with a beautiful instrumental outro',
          continueAt: originalTrack.duration - 30, // Extend from 30s before end
          model: 'V4_5'
        });
        
        const extendedResult = await api.waitForCompletion(extendTaskId);
        console.log('Extended version created:', extendedResult.data[0].audio_url);
        
        // Separate vocals
        console.log('Separating vocals...');
        const separationTaskId = await api.separateVocals(musicTaskId, originalTrack.id);
        const separationResult = await api.waitForCompletion(separationTaskId);
        
        console.log('Vocal separation completed:');
        console.log(`  Instrumental: ${separationResult.vocal_removal_info.instrumental_url}`);
        console.log(`  Vocals only: ${separationResult.vocal_removal_info.vocal_url}`);
        
      } catch (error) {
        console.error('Error:', error.message);
      }
    }

    main();
```

--------------------------------

### Get MIDI Details

Source: https://docs.sunoapi.org/suno-api/get-midi-details

Fetches the MIDI data for a given task ID. The response includes the state of the MIDI generation, a list of instruments, and for each instrument, a list of notes with their pitch, start time, end time, and velocity. It also provides task status flags, creation and completion times, and error information if applicable.

```APIDOC
## GET /v1/midi/details

### Description
Retrieves the MIDI data associated with a specific task.

### Method
GET

### Endpoint
/v1/midi/details

### Parameters
#### Query Parameters
- **taskId** (string) - Required - The unique identifier for the task for which to retrieve MIDI details.

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code, expected to be 200 for success.
- **msg** (string) - A message indicating the status of the request, e.g., "success".
- **data** (object) - Contains the MIDI details and task information.
  - **taskId** (string) - The ID of the task.
  - **recordTaskId** (string) - Related task ID, possibly for recording purposes.
  - **audioId** (string) - The ID of the generated audio, if applicable.
  - **callbackUrl** (string) - The URL to which a callback will be sent upon task completion.
  - **completeTime** (integer) - Timestamp in milliseconds when the task was completed.
  - **midiData** (object) - Object containing the MIDI data.
    - **state** (string) - The completion state of the MIDI generation (e.g., "complete").
    - **instruments** (array) - An array of instrument objects.
      - **name** (string) - The name of the instrument (e.g., "Drums", "Electric Bass (finger)").
      - **notes** (array) - An array of note objects for the instrument.
        - **pitch** (integer) - MIDI note number (0-127).
        - **start** (number) - Note start time in seconds.
        - **end** (number) - Note end time in seconds.
        - **velocity** (number) - Note velocity/intensity (0-1).
  - **successFlag** (integer) - Task status flag: 0 = Pending, 1 = Success, 2 = Failed to create task, 3 = MIDI generation failed.
  - **createTime** (integer) - Task creation timestamp in milliseconds.
  - **errorCode** (string, nullable) - Error code if the task failed.
  - **errorMessage** (string, nullable) - Error message if the task failed.

#### Response Example
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "recordTaskId": "-1",
    "audioId": "e231****-****-****-****-****8cadc7dc",
    "callbackUrl": "https://example.callback",
    "completeTime": 1760335255000,
    "midiData": {
      "state": "complete",
      "instruments": [
        {
          "name": "Drums",
          "notes": [
            {
              "pitch": 73,
              "start": 0.036458333333333336,
              "end": 0.18229166666666666,
              "velocity": 1
            },
            {
              "pitch": 61,
              "start": 0.046875,
              "end": 0.19270833333333334,
              "velocity": 1
            }
          ]
        },
        {
          "name": "Electric Bass (finger)",
          "notes": [
            {
              "pitch": 44,
              "start": 7.6875,
              "end": 7.911458333333333,
              "velocity": 1
            }
          ]
        }
      ]
    },
    "successFlag": 1,
    "createTime": 1760335251000,
    "errorCode": null,
    "errorMessage": null
  }
}
```

### Error Handling
#### Error Response (500)
- $ref: '#/components/responses/Error'

```

--------------------------------

### Suno API Usage Example

Source: https://docs.sunoapi.org/suno-api/quickstart

Demonstrates a complete workflow: checking credits, generating lyrics, generating music with custom parameters, and waiting for the music generation to complete. Replace 'YOUR_API_KEY' with your actual API key.

```javascript
// Usage example
async function main() {
  const api = new SunoAPI('YOUR_API_KEY');
  
  try {
    // Check remaining credits
    const credits = await api.getRemainingCredits();
    console.log(`Remaining credits: ${credits}`);
    
    // Generate lyrics first
    console.log('Generating lyrics...');
    const lyricsTaskId = await api.generateLyrics(
      'A song about adventure and discovery, uplifting and inspiring'
    );
    
    const lyricsResult = await api.waitForCompletion(lyricsTaskId);
    console.log('Lyrics generated:', lyricsResult.data[0].text);
    
    // Generate music with custom parameters
    console.log('Generating music...');
    const musicTaskId = await api.generateMusic({
      prompt: lyricsResult.data[0].text,
      customMode: true,
      style: 'Folk Pop',
      title: 'Adventure Song',
      instrumental: false,
      model: 'V4_5',
      callBackUrl: 'https://your-server.com/music-callback'
    });
    
    // Wait for completion
    const musicResult = await api.waitForCompletion(musicTaskId);
    console.log('Music generated successfully!');
    
```

--------------------------------

### Failure Callback Example

Source: https://docs.sunoapi.org/suno-api/replace-section-callbacks

This is an example of a failure callback payload received when a replace music section task fails.

```APIDOC
### Failure Callback

When the replacement task fails:

```json
{
  "code": 501,
  "msg": "Audio generation failed.",
  "data": {
    "callbackType": "error",
    "task_id": "2fac****9f72",
    "error": "Generation failed due to technical issues"
  }
}
```
```

--------------------------------

### Generate First Song with JavaScript

Source: https://docs.sunoapi.org/suno-api/quickstart

Use the fetch API in JavaScript to send a POST request for music generation. Replace YOUR_API_KEY and update the callBackUrl.

```javascript
const response = await fetch('https://api.sunoapi.org/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A peaceful acoustic guitar melody with soft vocals, folk style',
    customMode: false,
    instrumental: false,
    model: 'V4_5ALL',
    callBackUrl: 'https://your-server.com/callback'
  })
});

const data = await response.json();
console.log('Task ID:', data.data.taskId);
```

--------------------------------

### Generate First Song with cURL

Source: https://docs.sunoapi.org/suno-api/quickstart

Make a POST request to the /api/v1/generate endpoint to create music. Ensure you replace YOUR_API_KEY and update the callBackUrl.

```bash
curl -X POST "https://api.sunoapi.org/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A peaceful acoustic guitar melody with soft vocals, folk style",
    "customMode": false,
    "instrumental": false,
    "model": "V4_5ALL",
    "callBackUrl": "https://your-server.com/callback"
  }'
```

--------------------------------

### Generate First Song with PHP

Source: https://docs.sunoapi.org/suno-api/quickstart

Use cURL in PHP to send a POST request for music generation. Replace YOUR_API_KEY and update the callBackUrl.

```php
<?php
$url = 'https://api.sunoapi.org/api/v1/generate';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$payload = [
    'prompt' => 'A peaceful acoustic guitar melody with soft vocals, folk style',
    'customMode' => false,
    'instrumental' => false,
    'model' => 'V4_5ALL',
    'callBackUrl' => 'https://your-server.com/callback'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Task ID: " . $result['data']['taskId'];
?>
```

--------------------------------

### Get WAV Conversion Details

Source: https://docs.sunoapi.org/suno-api/get-wav-conversion-details

Use this endpoint to get the status and details of a WAV conversion task. You need to provide the taskId obtained from the Convert to WAV Format endpoint.

```APIDOC
## Get WAV Conversion Details

### Description
Retrieves the status and details of a WAV conversion task using its unique task ID.

### Method
GET

### Endpoint
/api/v1/wav/record-info

### Parameters
#### Query Parameters
- **taskId** (string) - Required - The task ID returned from the Convert to WAV Format endpoint. Used to retrieve details about the conversion process, including status and download URL if available.

### Response
#### Success Response (200)
- **code** (integer) - Status code indicating success or failure.
- **msg** (string) - Message indicating the result of the request.
- **data** (object) - Contains the details of the WAV conversion task.
  - **taskId** (string) - Task ID.
  - **musicId** (string) - The ID of the source music track that was converted to WAV format.
  - **musicIndex** (integer) - Music index, 0 or 1.
  - **callbackUrl** (string) - The callback URL that was provided in the conversion request.
  - **completeTime** (string) - The timestamp when the conversion was completed.
  - **response** (object) - Contains the response details.
    - **audioWavUrl** (string) - WAV format audio file URL.
  - **successFlag** (string) - Task status (e.g., PENDING, SUCCESS, GENERATE_WAV_FAILED).
  - **createTime** (string) - The timestamp when the task was created.

### Request Example
```http
GET /api/v1/wav/record-info?taskId=988e****c8d3 HTTP/1.1
Host: api.sunoapi.org
Authorization: Bearer YOUR_API_KEY
```

### Response Example
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "988e****c8d3",
    "musicId": "example_music_id",
    "musicIndex": 0,
    "callbackUrl": "https://example.com/callback",
    "completeTime": "2023-10-27T10:00:00Z",
    "response": {
      "audioWavUrl": "https://api.sunoapi.org/audio/example.wav"
    },
    "successFlag": "SUCCESS",
    "createTime": "2023-10-27T09:55:00Z"
  }
}
```
```

--------------------------------

### Generate First Song with Python

Source: https://docs.sunoapi.org/suno-api/quickstart

Utilize the requests library in Python to perform a POST request for music generation. Replace YOUR_API_KEY and update the callBackUrl.

```python
import requests

url = "https://api.sunoapi.org/api/v1/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "prompt": "A peaceful acoustic guitar melody with soft vocals, folk style",
    "customMode": False,
    "instrumental": False,
    "model": "V4_5ALL",
    "callBackUrl": "https://your-server.com/callback"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Task ID: {result['data']['taskId']}")
```

--------------------------------

### OpenAPI Specification for Get Remaining Credits

Source: https://docs.sunoapi.org/suno-api/get-remaining-credits

This OpenAPI 3.0 specification defines the GET request for the `/api/v1/generate/credit` endpoint. It includes details on authentication, request parameters, and response schemas for successful requests and errors.

```yaml
openapi: 3.0.0
info:
  title: intro
  description: API documentation for audio generation services
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@sunoapi.org
servers:
  - url: https://api.sunoapi.org
    description: API Server
security:
  - BearerAuth: []
tags:
  - name: Music Generation
    description: Endpoints for creating and managing music generation tasks
  - name: Lyrics Generation
    description: Endpoints for lyrics generation and management
  - name: WAV Conversion
    description: Endpoints for converting music to WAV format
  - name: Vocal Removal
    description: Endpoints for vocal removal from music tracks
  - name: Music Video Generation
    description: Endpoints for generating MP4 videos from music tracks
  - name: Account Management
    description: Endpoints for account and credits management
paths:
  /api/v1/generate/credit:
    get:
      summary: Get Remaining Credits
      operationId: get-remaining-credits
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: integer
                        description: >-
                          The number of credits currently available in your
                          account.  

                          - Each API operation consumes a specific number of
                          credits depending on the feature.  

                          - Additional credits can be purchased from your
                          account dashboard.
                        example: 100
              example:
                code: 200
                msg: success
                data: 100
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: |- 
            # Status Codes

            - ✅ 200 - Request successful
            - ⚠️ 400 - Invalid parameters
            - ⚠️ 401 - Unauthorized access
            - ⚠️ 404 - Invalid request method or path
            - ⚠️ 405 - Rate limit exceeded
            - ⚠️ 413 - Theme or prompt too long
            - ⚠️ 429 - Insufficient credits
            - ⚠️ 430 - Your call frequency is too high. Please try again later. 
            - ⚠️ 455 - System maintenance
            - ❌ 500 - Server error
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 404
            - 405
            - 413
            - 429
            - 430
            - 455
            - 500
        msg:
          type: string
          description: Error message when code != 200
          example: success
  responses:
    Error:
      description: Server error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        # 🔑 API Authentication


        All endpoints require authentication using Bearer Token.


        ## Get API Key


        1. Visit the [API Key Management Page](https://sunoapi.org/api-key) to
        obtain your API Key


        ## Usage


        Add to request headers:

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        > **⚠️ Note:**

        > - Keep your API Key secure and do not share it with others

        > - If you suspect your API Key has been compromised, reset it
        immediately from the management page

```

--------------------------------

### JavaScript Suno API Client and Workflow Example

Source: https://docs.sunoapi.org/cn/suno-api/quickstart

This JavaScript code defines a SunoAPI class for interacting with the Suno API and demonstrates a full workflow. It includes methods for checking credits, generating lyrics, generating music with custom parameters, waiting for task completion, and extending music tracks. Ensure you replace 'YOUR_API_KEY' with your actual API key and provide valid callback URLs.

```javascript
class SunoAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.sunoapi.org/api/v1';
  }
  
  async generateMusic(options) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(options)
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`生成失败: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async generateLyrics(prompt) {
    const response = await fetch(`${this.baseUrl}/lyrics`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        callBackUrl: 'https://your-server.com/lyrics-callback'
      })
    });
    
    const result = await response.json();
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 600000) { // 最长等待10分钟
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getTaskStatus(taskId);
      
      if (status.status === 'SUCCESS') {
        return status.response;
      } else if (status.status === 'FAILED') {
        throw new Error(`生成失败: ${status.errorMessage}`);
      }
      
      // 等待30秒后再次检查
      await new Promise(resolve => setTimeout(resolve, 30000));
    }
    
    throw new Error('生成超时');
  }
  
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/generate/record-info?taskId=${taskId}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    return result.data;
  }
  
  async extendMusic(audioId, options) {
    const response = await fetch(`${this.baseUrl}/generate/extend`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        audioId,
        ...options
      })
    });
    
    const result = await response.json();
    return result.data.taskId;
  }
  
  async separateVocals(taskId, audioId) {
    const response = await fetch(`${this.baseUrl}/vocal-removal/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        taskId,
        audioId,
        callBackUrl: 'https://your-server.com/vocal-callback'
      })
    });
    
    const result = await response.json();
    return result.data.taskId;
  }
  
  async getRemainingCredits() {
    const response = await fetch(`${this.baseUrl}/get-credits`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    return result.data.credits;
  }
}

// 使用示例
async function main() {
  const api = new SunoAPI('YOUR_API_KEY');
  
  try {
    // 检查剩余积分
    const credits = await api.getRemainingCredits();
    console.log(`剩余积分: ${credits}`);
    
    // 首先生成歌词
    console.log('正在生成歌词...');
    const lyricsTaskId = await api.generateLyrics(
      '一首关于冒险和发现的歌曲，振奋人心且鼓舞人心'
    );
    
    const lyricsResult = await api.waitForCompletion(lyricsTaskId);
    console.log('歌词已生成:', lyricsResult.data[0].text);
    
    // 使用自定义参数生成音乐
    console.log('正在生成音乐...');
    const musicTaskId = await api.generateMusic({
      prompt: lyricsResult.data[0].text,
      customMode: true,
      style: '民谣流行',
      title: '冒险之歌',
      instrumental: false,
      model: 'V4_5',
      callBackUrl: 'https://your-server.com/music-callback'
    });
    
    // 等待完成
    const musicResult = await api.waitForCompletion(musicTaskId);
    console.log('音乐生成成功！');
    
    musicResult.data.forEach((track, index) => {
      console.log(`音轨 ${index + 1}:`);
      console.log(`  标题: ${track.title}`);
      console.log(`  时长: ${track.duration}秒`);
      console.log(`  音频URL: ${track.audio_url}`);
    });
    
    // 扩展第一个音轨
    const originalTrack = musicResult.data[0];
    console.log('正在扩展音乐...');

```

--------------------------------

### Callback Example for Music Extension Completion

Source: https://docs.sunoapi.org/suno-api/extend-music

This JSON structure represents a callback received when music extension generation is complete. It includes status, task details, and information about the generated audio and its sources.

```json
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "8551****662c",
        "audio_url": "https://example.cn/****.mp3",
        "source_audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "source_stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "source_image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man",
        "tags": "electrifying, rock",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}
```

--------------------------------

### Get Remaining Credits

Source: https://docs.sunoapi.org/llms.txt

Retrieve the current balance of available credits for your account.

```APIDOC
## GET /v1/account/credits

### Description
Retrieve the current balance of available credits for your account.

### Method
GET

### Endpoint
/v1/account/credits

### Response
#### Success Response (200)
- **credits** (integer) - The number of remaining credits.
```

--------------------------------

### MIDI Generation Task Creation Response (200 OK)

Source: https://docs.sunoapi.org/suno-api/generate-midi

This example shows a successful response when creating a MIDI generation task. It includes a task ID that can be used to query the task status.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
```

--------------------------------

### Get Timestamped Lyrics

Source: https://docs.sunoapi.org/llms.txt

Retrieve timestamped lyrics for synchronized display during audio playback.

```APIDOC
## GET /v1/lyrics/timestamped

### Description
Retrieve timestamped lyrics for synchronized display during audio playback.

### Method
GET

### Endpoint
/v1/lyrics/timestamped

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier for the lyrics generation task.

### Response
#### Success Response (200)
- **lyrics** (array) - An array of objects, where each object contains the text of a lyric line and its corresponding timestamp.
```

--------------------------------

### Get Lyrics Generation Details

Source: https://docs.sunoapi.org/cn/suno-api/get-lyrics-generation-details

Fetches the details of a lyrics generation task by its ID.

```APIDOC
## GET /api/v1/lyrics/record-info

### Description
Retrieves the detailed information for a specific lyrics generation task.

### Method
GET

### Endpoint
/api/v1/lyrics/record-info

### Parameters
#### Query Parameters
- **taskId** (string) - Required - The task ID returned from the lyrics generation interface. Used to fetch detailed information for a specific lyrics generation task.

### Response
#### Success Response (200)
- **taskId** (string) - The task ID.
- **param** (string) - The parameters used for the generation task.
- **response** (object) - The response details, including generated lyrics.
  - **taskId** (string) - The task ID.
  - **data** (array) - An array of generated lyrics objects.
    - **text** (string) - The content of the lyrics.
    - **title** (string) - The title of the lyrics.
    - **status** (string) - The generation status (complete, failed).
    - **errorMessage** (string) - The error message, if the status is 'failed'.
- **status** (string) - The overall task status (PENDING, SUCCESS, CREATE_TASK_FAILED, GENERATE_LYRICS_FAILED, CALLBACK_EXCEPTION, SENSITIVE_WORD_ERROR).
- **type** (string) - The type of the task (e.g., LYRICS).
- **errorCode** (number) - The error code, if the task failed.
- **errorMessage** (string) - The error message, if the task failed.

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "11dc****8b0f",
    "param": "{\"prompt\": \"A song about peaceful night in the city\"}",
    "response": {
      "taskId": "11dc****8b0f",
      "data": [
        {
          "text": "[Verse]\n我穿越城市黑暗夜\n心中燃烧梦想的烈火",
          "title": "钢铁侠",
          "status": "complete",
          "errorMessage": ""
        }
      ]
    },
    "status": "SUCCESS",
    "type": "LYRICS",
    "errorCode": null,
    "errorMessage": null
  }
}
```
```

--------------------------------

### Get Music Cover Details

Source: https://docs.sunoapi.org/llms.txt

Retrieves detailed information about music cover generation tasks.

```APIDOC
## Get Music Cover Details

### Description
Retrieves detailed information about music cover generation tasks.

### Method
GET

### Endpoint
/v1/get_cover_details/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the music cover generation task.

### Response
#### Success Response (200)
- **id** (string) - The ID of the task.
- **status** (string) - The status of the task.
- **cover_image_url** (string) - The URL of the generated cover image.

#### Response Example
```json
{
  "id": "task_mno345",
  "status": "completed",
  "cover_image_url": "https://sunoapi.org/covers/image.jpg"
}
```
```

--------------------------------

### Success Response Format

Source: https://docs.sunoapi.org/suno-api/quickstart

This is an example of a successful response from the API, typically returned after initiating a generation task.

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "suno_task_abc123"
  }
}
```

--------------------------------

### Handle Music Generation Callbacks

Source: https://docs.sunoapi.org/suno-api/quickstart

Set up a webhook endpoint to receive automatic notifications when music generation is complete. This example shows how to process successful generation and failure messages.

```javascript
// Your callback endpoint
app.post('/music-callback', (req, res) => {
  const { code, data } = req.body;
  
  if (code === 200) {
    console.log('Music ready:', data.data);
    data.data.forEach(track => {
      console.log(`Title: ${track.title}`);
      console.log(`Audio: ${track.audio_url}`);
    });
  } else {
    console.log('Generation failed:', req.body.msg);
  }
  
  res.status(200).json({ status: 'received' });
});
```

--------------------------------

### Get Audio Separation Details

Source: https://docs.sunoapi.org/llms.txt

Retrieve detailed information about a vocal separation task, including status and download links.

```APIDOC
## GET /v1/audio/separation/details

### Description
Retrieve detailed information about a vocal separation task, including status and download links.

### Method
GET

### Endpoint
/v1/audio/separation/details

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier for the audio separation task.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the audio separation task.
- **status** (string) - The current status of the task.
- **download_links** (object) - An object containing URLs to download the separated audio stems (e.g., vocals, instrumental).
```
Tokens:
Raw