0.0
The project is in a healthy, maintained state
The suno ai api Ruby SDK is the language-specific package for Suno on RunAPI. Use this suno ai api package for song generation, lyrics, vocal, extension, and audio transformation flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

~> 0.2.5
 Project Readme

RunAPI

Suno API SDKs for JavaScript, Ruby, and Go on RunAPI, including music generation, voice validation phrase, and custom voice workflows.

npm RubyGems Go Reference License


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, voice validation phrase, custom voice, and related audio workflows.

Installation

npm install @runapi.ai/suno
# or
pnpm add @runapi.ai/suno
# or
yarn add @runapi.ai/suno

Quick Start

import { SunoClient } from '@runapi.ai/suno';

const client = new SunoClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://runapi.ai', // optional
});

const result = await client.textToMusic.run({
  prompt: 'A chill lo-fi beat with soft vocals',
  model: 'suno-v4.5-plus',
});

console.log('Music URL:', result.audios?.[0]?.audio_url);

Features

  • 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
  • Voice Validation Phrase: Generate and regenerate phrases for voice verification flows
  • Custom Voice Generation: Create reusable custom voices, check availability, and use voice_id as persona_id with persona_type: 'voice'
  • 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

API Reference

Client Initialization

const client = new SunoClient({
  apiKey: string;      // Required: Your RunAPI.ai API key
  baseUrl?: string;    // Optional: API base URL (defaults to production)
});

Music Generation

Prompt Brief

const result = await client.textToMusic.run({
  vocal_mode: 'auto_lyrics',
  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'
});

Exact Lyrics

const result = await client.textToMusic.run({
  vocal_mode: 'exact_lyrics',
  lyrics: '[Verse]\nSoft piano melodies flowing gently',
  style: 'Classical, Ambient',
  title: 'Peaceful Piano Meditation',
  model: 'suno-v5',
  persona_id: 'persona_123', // optional
  persona_type: 'voice', // optional, suno-v5 only
});

Manual Control (Create + Poll)

const task = await client.textToMusic.create({
  vocal_mode: 'instrumental',
  style: 'Electronic, Dance',
  title: 'Neon Pulse',
  model: 'suno-v4.5-plus',
});

const status = await client.textToMusic.get(task.id);
console.log('Status:', status.status);

Cover Audio

Transform uploaded audio into new styles:

const result = await client.coverAudio.run({
  upload_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  prompt: 'Transform into a jazz version',
  model: 'suno-v4.5-plus',
});

Generate Artwork

Generate cover images for existing generations:

const result = await client.generateArtwork.run({
  task_id: 'original-task-id',
});

Music Extension

Extend existing Suno generations:

const original = await client.textToMusic.run({
  prompt: 'A short intro melody',
  model: 'suno-v4.5-plus',
});

const extended = await client.extendMusic.run({
  audio_id: original.audios?.[0]?.id,
  parameter_mode: "source",
  model: 'suno-v4.5-plus',
  prompt: 'Continue with an uplifting chorus',
});

Upload and Extend Music

Extend uploaded audio files:

const result = await client.extendMusic.run({
  upload_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  parameter_mode: "source",
  model: 'suno-v4.5-plus',
  prompt: 'Continue with an uplifting chorus',
});

Add Instrumental

const result = await client.addInstrumental.run({
  upload_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  title: 'My Song',
  tags: 'Pop, Energetic, Upbeat',
  negative_tags: 'Heavy Metal, Aggressive',
  model: 'suno-v4.5-plus',
});

Add Vocals

Add AI-generated vocals to instrumental audio (suno-v4.5-plus/suno-v5 only):

const result = await client.addVocals.run({
  upload_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  lyrics: '[Verse]\nSoft romantic lyrics about summer love',
  title: 'Summer Love',
  style: 'Pop, Romantic',
  negative_tags: 'Screaming, Heavy Metal',
  model: 'suno-v4.5-plus',
});

Separate Audio Stems

const generation = await client.textToMusic.run({
  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);

MIDI Export

// 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(', '));

Convert Audio

const wav = await client.convertAudio.run({
  task_id: 'generation-task-id',
  audio_id: 'audio-id',
});

console.log('WAV URL:', wav.wav_url);

Visualize Music

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

// 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}`);
});

Replace Section

const result = await client.replaceSection.run({
  task_id: 'original-task-id',
  audio_id: 'audio-id',
  lyrics: '[Verse]\nA 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);

Voice Validation Phrase

Generate a phrase the user can read for a later voice verification step:

const phrase = await client.voiceToValidationPhrase.run({
  voice_url: 'https://file.runapi.ai/source-vocal.mp3',
  vocal_start_seconds: 2,
  vocal_end_seconds: 12,
  language: 'en',
});

console.log('Validation phrase:', phrase.validation_phrase);

Regenerate the phrase from a prior validation phrase task:

const replacement = await client.regenerateValidationPhrase.run({
  task_id: phrase.id,
});

console.log('Replacement phrase:', replacement.validation_phrase);

Create a reusable custom voice after the user records the validation phrase:

const customVoice = await client.generateVoice.run({
  task_id: phrase.id,
  verify_url: 'https://file.runapi.ai/verify-read.mp3',
  voice_name: 'Warm Test Voice',
  description: 'Warm vocal identity',
  style: 'Pop, Female Vocal',
  singer_skill_level: 'advanced',
});

const availability = await client.checkVoice.run({
  task_id: customVoice.id,
});

console.log('Voice available:', availability.is_available);
console.log('Use as voice persona_id:', customVoice.voice_id);

Use a completed voice_id as persona_id with persona_type: 'voice' on supported Suno v5 music generation endpoints.

Generate Persona & Boost Style

// First generate some music with vocals
const generation = await client.textToMusic.run({
  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);

Models

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 Stable model Stable, proven quality

Request Shapes

Choose vocal_mode for music, cover, and mashup requests.

Automatic Lyrics

Use auto_lyrics when prompt is a brief and lyrics should be generated automatically. Keep prompt briefs under 500 characters.

Exact Lyrics

Use exact_lyrics when lyrics is the text to sing.

Instrumental

Use instrumental for tracks without vocals.

Character Limits

Text Limits:

  • prompt: 500 characters
  • lyrics with suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5: 5000 characters
  • lyrics with suno-v4: 3000 characters

Style Limits:

  • suno-v4: 200 characters
  • suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5: 1000 characters

Title Limits:

  • suno-v4: 80 characters
  • suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5: 100 characters

Error Handling

import {
  SunoClient,
  AuthenticationError,
  InsufficientCreditsError,
  ValidationError,
  TaskFailedError,
} from '@runapi.ai/suno';

try {
  const result = await client.textToMusic.run({
    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');
  }
}

Advanced Usage

Callbacks

const result = await client.textToMusic.create({
  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;
}

Generation Stages

The webhook will be called at multiple stages:

  1. text_generated: Text content ready (title, lyrics, etc.)
  2. first_audio_ready: First audio completed
  3. all_audios_ready: All audios completed
  4. failed: Generation failed

Fine-Tuning Parameters

const result = await client.textToMusic.run({
  prompt: 'Energetic rock music',
  model: 'suno-v5',
  vocal_gender: 'male',        // 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.

License

MIT

Support

For issues and questions, please visit https://github.com/runapi-ai/runapi.ai