Suno API SDKs for JavaScript, Ruby, and Go on RunAPI.
The suno ai api SDK packages JavaScript, Ruby, and Go clients for Suno music generation on RunAPI. Use this suno ai api SDK for text-to-music, cover audio, music extension, stem separation, and related audio workflows.
npm install @runapi.ai/suno
# or
pnpm add @runapi.ai/suno
# or
yarn add @runapi.ai/sunoimport { SunoClient } from '@runapi.ai/suno';
const client = new SunoClient({
apiKey: 'your-api-key',
baseUrl: 'https://runapi.ai', // optional
});
const result = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A chill lo-fi beat with soft vocals',
model: 'suno-v4.5-plus',
});
console.log('Music URL:', result.audios?.[0]?.audio_url);- Music Generation: Create music from text prompts with multiple models
- Cover Audio: Transform uploaded audio into new styles
- Extend Music: Extend generated music with additional content
- Upload and Extend Music: Extend uploaded audio files
- AddInstrumental: Add instrumental backing to vocal tracks
- Separate Audio Stems: Separate vocals from instrumentals
- MIDI Export: Extract MIDI data from audio
- Convert Audio: Convert generated music to WAV format
- Visualize Music: Generate videos for your music
- Generate Lyrics: Generate and retrieve timestamped lyrics
- Replace Section: Replace specific sections of music
- Generate Persona & Boost Style: Manage custom voice personas and music styles
- Full TypeScript Support: Complete type definitions for all API endpoints
- Automatic Polling: Built-in polling for async music generation
- Error Handling: Comprehensive error types from @runapi.ai/core
const client = new SunoClient({
apiKey: string; // Required: Your RunAPI.ai API key
baseUrl?: string; // Optional: API base URL (defaults to production)
});const result = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A relaxing piano melody with soft ambient sounds',
model: 'suno-v4.5-plus', // or 'suno-v5', 'suno-v4.5-all', 'suno-v4.5', 'suno-v4', 'suno-v3.5'
});const result = await client.textToMusic.run({
custom_mode: true,
instrumental: false,
prompt: 'Soft piano melodies flowing gently',
style: 'Classical, Ambient',
title: 'Peaceful Piano Meditation',
model: 'suno-v5',
persona_id: 'persona_123', // optional
persona_model: 'voice_persona', // optional, suno-v5 only
});const task = await client.textToMusic.create({
custom_mode: false,
instrumental: true,
prompt: 'Upbeat electronic dance music',
model: 'suno-v4.5-plus',
});
const status = await client.textToMusic.get(task.id);
console.log('Status:', status.status);Transform uploaded audio into new styles:
const result = await client.coverAudio.run({
upload_url: 'https://example.com/audio.mp3',
custom_mode: false,
instrumental: false,
prompt: 'Transform into a jazz version',
model: 'suno-v4.5-plus',
});Generate cover images for existing generations:
const result = await client.generateArtwork.run({
task_id: 'original-task-id',
});Extend existing Suno generations:
const original = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A short intro melody',
model: 'suno-v4.5-plus',
});
const extended = await client.extendMusic.run({
audio_id: original.audios?.[0]?.id,
default_param_flag: false,
model: 'suno-v4.5-plus',
prompt: 'Continue with an uplifting chorus',
});Extend uploaded audio files:
const result = await client.extendMusic.run({
upload_url: 'https://example.com/audio.mp3',
default_param_flag: false,
model: 'suno-v4.5-plus',
prompt: 'Continue with an uplifting chorus',
});const result = await client.addInstrumental.run({
upload_url: 'https://example.com/addVocals.mp3',
title: 'My Song',
tags: 'Pop, Energetic, Upbeat',
negative_tags: 'Heavy Metal, Aggressive',
model: 'suno-v4.5-plus',
});Add AI-generated vocals to instrumental audio (suno-v4.5-plus/suno-v5 only):
const result = await client.addVocals.run({
upload_url: 'https://example.com/instrumental.mp3',
prompt: 'Soft romantic lyrics about summer love',
title: 'Summer Love',
style: 'Pop, Romantic',
negative_tags: 'Screaming, Heavy Metal',
model: 'suno-v4.5-plus',
});const generation = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A song with vocals',
model: 'suno-v4.5-plus',
});
const separation = await client.separateAudioStems.run({
task_id: generation.id,
audio_id: generation.audios?.[0]?.id,
});
console.log('Instrumental:', separation.separated_audios?.instrumental_url);
console.log('AddVocals:', separation.separated_audios?.vocal_url);// Requires a completed vocal-removal task with type: 'split_stem'
const midi = await client.generateMidi.run({
task_id: 'split-stem-vocal-removal-task-id',
});
console.log('Detected instruments:', generateMidi.instruments?.map(i => i.name).join(', '));const wav = await client.convertAudio.run({
task_id: 'generation-task-id',
audio_id: 'audio-id',
});
console.log('WAV URL:', wav.wav_url);const video = await client.visualizeMusic.run({
task_id: 'music-generation-id',
audio_id: 'audio-id',
prompt: 'A serene landscape with flowing water and mountains',
});
console.log('Video URL:', video.video_url);// Generate lyrics
const lyrics = await client.generateLyrics.run({
prompt: 'A love song about summer nights',
});
console.log('Lyrics:', lyrics.lyrics);
// Get timestamped lyrics
const timestamped = await client.getTimestampedLyrics.run({
task_id: 'generation-task-id',
audio_id: 'audio-id',
});
timestamped.aligned_words?.forEach(word => {
console.log(`[${word.start_time}s - ${word.end_time}s] ${word.word}`);
});const result = await client.replaceSection.run({
task_id: 'original-task-id',
audio_id: 'audio-id',
prompt: 'A powerful guitar solo',
tags: 'Rock, Energetic',
title: 'Epic Guitar Solo',
infill_start_time: 30.0,
infill_end_time: 45.0,
});
console.log('Replaced track:', result.track?.audio_url);// First generate some music with vocals
const generation = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A song with distinctive vocals',
model: 'suno-v4.5-plus',
});
// Generate a persona from the audio's voice
const { persona } = await client.generatePersona.run({
task_id: generation.id,
audio_id: generation.audios?.[0]?.id,
name: 'Warm Male Voice',
description: 'A warm, friendly male voice',
});
console.log('Persona ID:', persona.id);
// Generate a style description from a prompt
const { style } = await client.boostStyle.run({
name: 'Cinematic Epic',
description: 'Epic orchestral music with powerful crescendos',
});
console.log('Generated Style:', style);| Model | Description | Use Case |
|---|---|---|
suno-v5 |
Latest model | Highest quality, latest features |
suno-v4.5-plus |
Enhanced suno-v4.5 | Great quality, cost-efficient |
suno-v4.5-all |
suno-v4.5 with all features | Smarter prompts, audio upload max 1 min |
suno-v4.5 |
Mid-tier quality | Balanced quality and speed |
suno-v4 |
Previous generation | Stable, proven quality |
suno-v3.5 |
Legacy model | Fast generation, lower cost |
Simple Mode (custom_mode: false):
- Just provide a prompt
- Easiest to use
- Suno handles all style decisions
- Prompt limit: 500 characters
Custom Mode (custom_mode: true):
- Fine-grained control
- Specify style, title, persona
- Larger prompt limits (up to 5000 chars for suno-v5)
- Best for specific creative visions
Prompt Limits:
- Simple Mode: 500 characters
- Custom Mode (suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5): 5000 characters
- Custom Mode (suno-v4, suno-v3.5): 3000 characters
Style Limits:
- suno-v4, suno-v3.5: 200 characters
- suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5: 1000 characters
Title Limits:
- suno-v4, suno-v3.5: 80 characters
- suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5: 100 characters
import {
SunoClient,
AuthenticationError,
InsufficientCreditsError,
ValidationError,
TaskFailedError,
} from '@runapi.ai/suno';
try {
const result = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'A beautiful melody',
model: 'suno-v4.5-plus',
});
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof InsufficientCreditsError) {
console.error('Not enough credits');
} else if (error instanceof ValidationError) {
console.error('Invalid parameters');
} else if (error instanceof TaskFailedError) {
console.error('Music generation failed');
}
}const result = await client.textToMusic.create({
custom_mode: false,
instrumental: false,
prompt: 'Test music',
model: 'suno-v4.5-plus',
callback_url: 'https://your-domain.com/webhook',
});Webhook payload on completion:
{
id: string;
status: 'completed' | 'failed';
generation_stage: 'text_generated' | 'first_audio_ready' | 'all_audios_ready' | 'failed';
audios?: Audio[];
error?: string;
}The webhook will be called at multiple stages:
- text_generated: Text content ready (title, lyrics, etc.)
- first_audio_ready: First audio completed
- all_audios_ready: All audios completed
- failed: Generation failed
const result = await client.textToMusic.run({
custom_mode: false,
instrumental: false,
prompt: 'Energetic rock music',
model: 'suno-v5',
vocal_gender: 'm', // Male vocals
style_weight: 0.75, // 0-1, higher = more style adherence
weirdness_constraint: 0.50, // 0-1, higher = more creative/experimental
audio_weight: 0.65, // 0-1, audio consistency weight
});For full suno ai api documentation including all parameters and response formats, visit https://runapi.ai/docs#suno.
MIT
For issues and questions, please visit https://github.com/runapi-ai/runapi.ai