Quick Start - API Box

Welcome to Suno API

Suno API enables you to create high-quality AI-generated music, lyrics, and audio content using state-of-the-art AI models. Whether you’re building music applications, automating creative workflows, or developing audio content, our API provides comprehensive tools for music generation and audio processing.

Generate Music

Create original music tracks with or without lyrics

Extend Music

Seamlessly extend existing music tracks

Generate Lyrics

Create creative lyrics from text prompts

Music Video

Convert audio tracks to visualized music videos

Upload & Cover

Transform uploaded audio into new styles

Upload & Extend

Upload audio files and seamlessly extend them

Vocal Separation

Separate vocals and instrumentals from music

WAV Conversion

Convert audio to high-quality WAV format

Get Lyrics

Retrieve timestamped synchronized lyrics

Add Instrumental

Add instrumental elements to existing audio tracks

Add Vocals

Generate vocal tracks for instrumental music

Boost Music Style

Enhance style descriptions with V4_5 conversational prompts

Authentication

All API requests require authentication using Bearer tokens. Please obtain your API key from the API Key Management Page.

Keep your API key secure and never share it publicly. If you suspect your key has been compromised, reset it immediately.

API Base URL

https://apibox.erweima.ai

Authentication Header

Authorization: Bearer YOUR_API_KEY

Quick Start Guide

Step 1: Generate Your First Music Track

Start with a simple music generation request:

curl -X POST "https://apibox.erweima.ai/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A peaceful and soothing piano piece with soft melodies",
    "customMode": false,
    "instrumental": true,
    "model": "V4_5ALL",
    "callBackUrl": "https://your-app.com/callback",
    "vocalGender": "m",
    "styleWeight": 0.65,
    "weirdnessConstraint": 0.3,
    "audioWeight": 0.7
  }'

const response = await fetch('https://apibox.erweima.ai/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A peaceful and soothing piano piece with soft melodies',
    customMode: false,
    instrumental: true,
    model: 'V4_5ALL',
    callBackUrl: 'https://your-app.com/callback',
    vocalGender: 'm',
    styleWeight: 0.65,
    weirdnessConstraint: 0.3,
    audioWeight: 0.7
  })
});

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

import requests

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

payload = {
    "prompt": "A peaceful and soothing piano piece with soft melodies",
    "customMode": False,
    "instrumental": True,
    "model": "V4_5ALL",
    "callBackUrl": "https://your-app.com/callback",
    "vocalGender": "m",
    "styleWeight": 0.65,
    "weirdnessConstraint": 0.3,
    "audioWeight": 0.7
}

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

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

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

$payload = [
    'prompt' => 'A peaceful and soothing piano piece with soft melodies',
    'customMode' => false,
    'instrumental' => true,
    'model' => 'V4_5ALL',
    'callBackUrl' => 'https://your-app.com/callback',
    'vocalGender' => 'm',
    'styleWeight' => 0.65,
    'weirdnessConstraint' => 0.3,
    'audioWeight' => 0.7
];

$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'];
?>

Step 2: Check Task Status

Use the returned task ID to check generation status:

curl -X GET "https://apibox.erweima.ai/api/v1/generate/record-info?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(`https://apibox.erweima.ai/api/v1/generate/record-info?taskId=${taskId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();

if (result.data.status === 'SUCCESS') {
  console.log('Generation complete!');
  console.log('Audio tracks:', result.data.response.data);
} else if (result.data.status === 'PENDING') {
  console.log('Still generating...');
} else {
  console.log('Generation failed:', result.data.status);
}

import requests
import time

def check_task_status(task_id, api_key):
    url = f"https://apibox.erweima.ai/api/v1/generate/record-info?taskId={task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, headers=headers)
    result = response.json()
    
    status = result['data']['status']
    
    if status == 'SUCCESS':
        print("Generation complete!")
        tracks = result['data']['response']['data']
        for i, track in enumerate(tracks):
            print(f"Track {i+1}: {track['audio_url']}")
        return tracks
    elif status == 'PENDING':
        print("Still generating...")
        return None
    else:
        print(f"Generation failed: {status}")
        return None

# Poll until complete
task_id = "YOUR_TASK_ID"
while True:
    tracks = check_task_status(task_id, "YOUR_API_KEY")
    if tracks:
        break
    time.sleep(30)  # Wait 30 seconds before checking again

Response Format

Success Response:

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

Task Status Response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e",
    "status": "SUCCESS",
    "response": {
      "data": [
        {
          "id": "8551****662c",
          "audio_url": "https://example.cn/****.mp3",
          "stream_audio_url": "https://example.cn/****",
          "image_url": "https://example.cn/****.jpeg",
          "prompt": "A peaceful and soothing piano piece",
          "title": "Peaceful Piano",
          "tags": "peaceful, soothing, piano",
          "duration": 198.44,
          "createTime": "2025-01-01 00:00:00"
        }
      ]
    }
  }
}

Core Features

Text-to-Music: Input text descriptions to generate corresponding musical compositions
Music Extension: Seamlessly create longer versions based on existing audio
Lyrics Generation: Generate structured lyrical content from creative prompts
Upload & Cover: Upload audio files and transform them into different musical styles
Upload & Extend: Upload audio files and seamlessly extend them while preserving style
Vocal Separation: Separate music into independent tracks like vocals and instrumentals with advanced stem separation
Format Conversion: Support for WAV and other high-quality audio format outputs
Music Videos: Convert audio to visualized music videos
Add Vocals: Generate vocal tracks for existing instrumental music
Add Instrumental: Create instrumental accompaniment for vocal tracks
Style Enhancement: Enhance and optimize existing music’s stylistic features with V4_5+ conversational prompts
Timestamped Lyrics: Retrieve synchronized lyrics for karaoke-style applications

AI Models

Choose the right model for your needs:

V4_5ALL

Extended CapabilitiesSupports longer lyrics (5000 chars) and style descriptions (1000 chars)

V4

Improved VocalsUp to 4 minutes, enhanced vocal quality

V4_5

Better Song StructureMax 1 minute, improved song organization

V4_5PLUS

Richer TonesUp to 8 minutes, new creative approaches

V5

Latest ModelEnhanced quality and capabilities

V5_5

Custom voice characterUnleash Your Voice: Custom Models Tailored to Your Unique Taste — same API limits as V5 where applicable

Generation Modes

customMode

boolean

required

Controls parameter complexity:

false: Simple mode, only requires prompt
true: Advanced mode, requires style and title

instrumental

boolean

required

Determines whether music contains vocals:

true: Instrumental only (no lyrics)
false: Contains vocals/lyrics

Key Parameters

prompt

string

required

Text description of the desired music. Be specific about genre, mood, and instruments.Character Limits:

Non-custom mode: 500 characters
Custom mode (V4): 3000 characters
Custom mode (V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL): 5000 characters

style

string

Music style specification (custom mode only).Examples: Jazz, Classical, Electronic, Pop, Rock, Hip-hopCharacter Limits:

V4: 200 characters
V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL: 1000 characters

title

string

Title for the generated music track (custom mode only).Maximum Length: 80 characters

Complete Workflow Example

Here’s a complete example of generating music with lyrics and waiting for completion:

JavaScript
Python

class SunoAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://apibox.erweima.ai/api/v1';
  }
  
  async generateMusic(prompt, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        customMode: options.customMode || false,
        instrumental: options.instrumental || false,
        model: options.model || 'V4_5ALL',
        style: options.style,
        title: options.title,
        negativeTags: options.negativeTags,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`Generation failed: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  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,
        defaultParamFlag: options.defaultParamFlag || false,
        model: options.model || 'V4_5ALL',
        prompt: options.prompt,
        style: options.style,
        title: options.title,
        continueAt: options.continueAt,
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`Extension failed: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async generateLyrics(prompt, callBackUrl) {
    const response = await fetch(`${this.baseUrl}/lyrics`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt,
        callBackUrl
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`Lyrics generation failed: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async addVocals(uploadUrl, prompt, style, title, negativeTags, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate/add-vocals`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        uploadUrl,
        prompt,
        style,
        title,
        negativeTags,
        model: options.model || 'V4_5PLUS',
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`Add vocals failed: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async addInstrumental(uploadUrl, title, tags, negativeTags, options = {}) {
    const response = await fetch(`${this.baseUrl}/generate/add-instrumental`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        uploadUrl,
        title,
        tags,
        negativeTags,
        model: options.model || 'V4_5PLUS',
        callBackUrl: options.callBackUrl || 'https://your-app.com/callback',
        vocalGender: options.vocalGender,
        styleWeight: options.styleWeight,
        weirdnessConstraint: options.weirdnessConstraint,
        audioWeight: options.audioWeight
      })
    });
    
    const result = await response.json();
    if (result.code !== 200) {
      throw new Error(`Add instrumental failed: ${result.msg}`);
    }
    
    return result.data.taskId;
  }
  
  async waitForCompletion(taskId, maxWaitTime = 600000) { // Max wait 10 minutes
    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.includes('FAILED') || status.status === 'SENSITIVE_WORD_ERROR') {
        throw new Error(`Generation failed: ${status.errorMessage || status.status}`);
      }
      
      // Wait 10 seconds before checking again
      await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    throw new Error('Generation timeout');
  }
  
  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 getRemainingCredits() {
    const response = await fetch(`${this.baseUrl}/generate/credit`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    return result.data.credits;
  }
}

// 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 music with lyrics
    console.log('Starting music generation...');
    const taskId = await api.generateMusic(
      'A nostalgic folk song about childhood memories',
      { 
        customMode: true,
        instrumental: false,
        model: 'V4_5',
        style: 'folk, acoustic guitar, nostalgic',
        title: 'Childhood Dreams'
      }
    );
    
    // Wait for completion
    console.log(`Task ID: ${taskId}. Waiting for completion...`);
    const result = await api.waitForCompletion(taskId);
    
    console.log('Music generation successful!');
    console.log('Generated tracks:');
    result.data.forEach((track, index) => {
      console.log(`Track ${index + 1}:`);
      console.log(`  Title: ${track.title}`);
      console.log(`  Audio URL: ${track.audio_url}`);
      console.log(`  Duration: ${track.duration} seconds`);
      console.log(`  Tags: ${track.tags}`);
    });
    
    // Extend the first track
    const firstTrack = result.data[0];
    console.log('\nExtending first track...');
    const extendTaskId = await api.extendMusic(firstTrack.id, {
      defaultParamFlag: true,
      prompt: 'Continue with a hopeful chorus',
      style: 'folk, uplifting',
      title: 'Childhood Dreams Extended',
      continueAt: 60,
      model: 'V4_5'
    });
    
    const extendResult = await api.waitForCompletion(extendTaskId);
    console.log('Music extension successful!');
    console.log('Extended track URL:', extendResult.data[0].audio_url);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

import requests
import time

class SunoAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://apibox.erweima.ai/api/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    def generate_music(self, prompt, **options):
        data = {
            'prompt': prompt,
            'customMode': options.get('customMode', False),
            'instrumental': options.get('instrumental', False),
            'model': options.get('model', 'V4_5ALL'),
            'callBackUrl': options.get('callBackUrl', 'https://your-app.com/callback')
        }
        
        if options.get('style'):
            data['style'] = options['style']
        if options.get('title'):
            data['title'] = options['title']
        if options.get('negativeTags'):
            data['negativeTags'] = options['negativeTags']
        if options.get('vocalGender'):
            data['vocalGender'] = options['vocalGender']
        if options.get('styleWeight'):
            data['styleWeight'] = options['styleWeight']
        if options.get('weirdnessConstraint'):
            data['weirdnessConstraint'] = options['weirdnessConstraint']
        if options.get('audioWeight'):
            data['audioWeight'] = options['audioWeight']
        
        response = requests.post(f'{self.base_url}/generate', 
                               headers=self.headers, json=data)
        result = response.json()
        
        if result['code'] != 200:
            raise Exception(f"Generation failed: {result['msg']}")
        
        return result['data']['taskId']
    
    def extend_music(self, audio_id, **options):
        data = {
            'audioId': audio_id,
            'defaultParamFlag': options.get('defaultParamFlag', False),
            'model': options.get('model', 'V4_5ALL'),
            'callBackUrl': options.get('callBackUrl', 'https://your-app.com/callback')
        }
        
        if options.get('prompt'):
            data['prompt'] = options['prompt']
        if options.get('style'):
            data['style'] = options['style']
        if options.get('title'):
            data['title'] = options['title']
        if options.get('continueAt'):
            data['continueAt'] = options['continueAt']
        if options.get('vocalGender'):
            data['vocalGender'] = options['vocalGender']
        if options.get('styleWeight'):
            data['styleWeight'] = options['styleWeight']
        if options.get('weirdnessConstraint'):
            data['weirdnessConstraint'] = options['weirdnessConstraint']
        if options.get('audioWeight'):
            data['audioWeight'] = options['audioWeight']
        
        response = requests.post(f'{self.base_url}/generate/extend', 
                               headers=self.headers, json=data)
        result = response.json()
        
        if result['code'] != 200:
            raise Exception(f"Extension failed: {result['msg']}")
        
        return result['data']['taskId']
    
    def generate_lyrics(self, prompt, callback_url):
        data = {
            'prompt': prompt,
            'callBackUrl': callback_url
        }
        
        response = requests.post(f'{self.base_url}/lyrics', 
                               headers=self.headers, json=data)
        result = response.json()
        
        if result['code'] != 200:
            raise Exception(f"Lyrics generation failed: {result['msg']}")
        
        return result['data']['taskId']
    
    def add_vocals(self, upload_url, prompt, style, title, negative_tags, **options):
        data = {
            'uploadUrl': upload_url,
            'prompt': prompt,
            'style': style,
            'title': title,
            'negativeTags': negative_tags,
            'model': options.get('model', 'V4_5PLUS'),
            'callBackUrl': options.get('callBackUrl', 'https://your-app.com/callback')
        }
        
        if options.get('vocalGender'):
            data['vocalGender'] = options['vocalGender']
        if options.get('styleWeight'):
            data['styleWeight'] = options['styleWeight']
        if options.get('weirdnessConstraint'):
            data['weirdnessConstraint'] = options['weirdnessConstraint']
        if options.get('audioWeight'):
            data['audioWeight'] = options['audioWeight']
        
        response = requests.post(f'{self.base_url}/generate/add-vocals', 
                               headers=self.headers, json=data)
        result = response.json()
        
        if result['code'] != 200:
            raise Exception(f"Add vocals failed: {result['msg']}")
        
        return result['data']['taskId']
    
    def add_instrumental(self, upload_url, title, tags, negative_tags, **options):
        data = {
            'uploadUrl': upload_url,
            'title': title,
            'tags': tags,
            'negativeTags': negative_tags,
            'model': options.get('model', 'V4_5PLUS'),
            'callBackUrl': options.get('callBackUrl', 'https://your-app.com/callback')
        }
        
        if options.get('vocalGender'):
            data['vocalGender'] = options['vocalGender']
        if options.get('styleWeight'):
            data['styleWeight'] = options['styleWeight']
        if options.get('weirdnessConstraint'):
            data['weirdnessConstraint'] = options['weirdnessConstraint']
        if options.get('audioWeight'):
            data['audioWeight'] = options['audioWeight']
        
        response = requests.post(f'{self.base_url}/generate/add-instrumental', 
                               headers=self.headers, json=data)
        result = response.json()
        
        if result['code'] != 200:
            raise Exception(f"Add instrumental failed: {result['msg']}")
        
        return result['data']['taskId']
    
    def wait_for_completion(self, task_id, max_wait_time=600):
        start_time = time.time()
        
        while time.time() - start_time < max_wait_time:
            status = self.get_task_status(task_id)
            
            if status['status'] == 'SUCCESS':
                return status['response']
            elif 'FAILED' in status['status'] or status['status'] == 'SENSITIVE_WORD_ERROR':
                error_msg = status.get('errorMessage', status['status'])
                raise Exception(f"Generation failed: {error_msg}")
            
            time.sleep(10)  # Wait 10 seconds
        
        raise Exception('Generation timeout')
    
    def get_task_status(self, task_id):
        response = requests.get(f'{self.base_url}/generate/record-info?taskId={task_id}',
                              headers={'Authorization': f'Bearer {self.api_key}'})
        return response.json()['data']
    
    def get_remaining_credits(self):
        response = requests.get(f'{self.base_url}/generate/credit',
                              headers={'Authorization': f'Bearer {self.api_key}'})
        return response.json()['data']['credits']

# Usage example
def main():
    api = SunoAPI('YOUR_API_KEY')
    
    try:
        # Check remaining credits
        credits = api.get_remaining_credits()
        print(f'Remaining credits: {credits}')
        
        # Generate music with lyrics
        print('Starting music generation...')
        task_id = api.generate_music(
            'A nostalgic folk song about childhood memories',
            customMode=True,
            instrumental=False,
            model='V4_5',
            style='folk, acoustic guitar, nostalgic',
            title='Childhood Dreams'
        )
        
        # Wait for completion
        print(f'Task ID: {task_id}. Waiting for completion...')
        result = api.wait_for_completion(task_id)
        
        print('Music generation successful!')
        print('Generated tracks:')
        for i, track in enumerate(result['data']):
            print(f"Track {i + 1}:")
            print(f"  Title: {track['title']}")
            print(f"  Audio URL: {track['audio_url']}")
            print(f"  Duration: {track['duration']} seconds")
            print(f"  Tags: {track['tags']}")
        
        # Extend the first track
        first_track = result['data'][0]
        print('\nExtending first track...')
        extend_task_id = api.extend_music(
            first_track['id'],
            defaultParamFlag=True,
            prompt='Continue with a hopeful chorus',
            style='folk, uplifting',
            title='Childhood Dreams Extended',
            continueAt=60,
            model='V4_5'
        )
        
        extend_result = api.wait_for_completion(extend_task_id)
        print('Music extension successful!')
        print(f"Extended track URL: {extend_result['data'][0]['audio_url']}")
        
    except Exception as error:
        print(f'Error: {error}')

if __name__ == '__main__':
    main()

Status Codes and Task Status

PENDING

Processing

Task is waiting for processing or currently generating

TEXT_SUCCESS

Partial Complete

Lyrics/text generation successfully completed

FIRST_SUCCESS

Partial Complete

First track generation completed

SUCCESS

Complete

All tracks generated successfully

CREATE_TASK_FAILED

Error

Task creation failed

GENERATE_AUDIO_FAILED

Error

Audio generation failed

SENSITIVE_WORD_ERROR

Error

Content filtered due to sensitive words

HTTP Status Codes

200

Success

Request successful

400

Bad Request

Invalid parameters or missing required fields

401

Unauthorized

No access permission, check API key

404

Not Found

Invalid request method or path

405

Rate Limited

Call limit exceeded

413

Content Too Long

Prompt or theme too long

429

Insufficient Credits

Account credits insufficient

455

Maintenance

System maintenance in progress

500

Server Error

Internal server error

Best Practices

Prompt Engineering

Be specific about genre, mood, and instruments
Use descriptive adjectives for better style control
Include tempo and energy level descriptions
Reference musical eras or specific artists for style guidance

Model Selection

V4_5ALL: Best for projects requiring longer lyrics and style descriptions
V4: Choose when vocal quality is most important
V4_5: Use for better song structure with max 1 min duration
V4_5PLUS: Select for highest quality and longest tracks

Performance Optimization

Use callbacks instead of frequent polling
Start with non-custom mode for simple needs
Implement proper error handling for generation failures
Cache generated content as files expire after 14-15 days

Content Guidelines

Avoid using copyrighted material in prompts
Use original lyrics and music descriptions
Be mindful of content policies for lyrical content
Test prompt variations to avoid sensitive word filters

Error Handling

Content Policy Violation (Code 400)

try {
  const taskId = await api.generateMusic('copyrighted lyrics');
} catch (error) {
  if (error.data.code === 400) {
    console.log('Please use only original content');
  }
}

Insufficient Credits (Code 429)

try {
  const taskId = await api.generateMusic('original composition');
} catch (error) {
  if (error.data.code === 429) {
    console.log('Please add more credits to your account');
  }
}

Rate Limiting (Code 405)

const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));

async function generateWithRetry(prompt, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await api.generateMusic(prompt, options);
    } catch (error) {
      if (error.data.code === 405 && i < maxRetries - 1) {
        await delay(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

Support

Need help? Our technical support team is here to assist you.

Email: support@api.box
Documentation: Check detailed API documentation and examples
API Status: View our status page for real-time API health information

Ready to start creating amazing AI music? Get your API key and start creating today!

​Welcome to Suno API

Generate Music

Extend Music

Generate Lyrics

Music Video

Upload & Cover

Upload & Extend

Vocal Separation

WAV Conversion

Get Lyrics

Add Instrumental

Add Vocals

Boost Music Style

​Authentication

​API Base URL

​Authentication Header

​Quick Start Guide

​Step 1: Generate Your First Music Track

​Step 2: Check Task Status

​Response Format

​Core Features

​AI Models

V4_5ALL

V4

V4_5

V4_5PLUS

V5

V5_5

​Generation Modes

​Key Parameters

​Complete Workflow Example

​Status Codes and Task Status

​HTTP Status Codes

​Best Practices

​Error Handling

​Support

Welcome to Suno API

Authentication

API Base URL

Authentication Header

Quick Start Guide

Step 1: Generate Your First Music Track

Step 2: Check Task Status

Response Format

Core Features

AI Models

Generation Modes

Key Parameters

Complete Workflow Example

Status Codes and Task Status

HTTP Status Codes

Best Practices

Error Handling

Support