runapi-suno 0.2.4 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b946388dec7aef3f7af7ff7d859b7f94dc119f836c2a5537d8875ea634be22b
-  data.tar.gz: a8416da674406ec542569bb7f953a6f5bc2c09848e6cc45825707476192151a4
+  metadata.gz: 7408c126663eb2e648020669baa1dc31570c6df7eb74a2d38856c8ba25eb7d3e
+  data.tar.gz: 69968db8a1c4d03cafe72847d036be448f8eadb2edc7797445660371c700807a
 SHA512:
-  metadata.gz: 9c92a126f53ab0471d08b2f99299b627ce0f9532e24c376e8110b21984ea7eb3866c414ca14ac4a72a79ceed283e91ae271c84461ef74200dc95c5a294392cf5
-  data.tar.gz: 5959bfa9a1f62749536cfc9a0d0f6adcea7fdf656b9330814e0b8830acd853f82384758468ec126dcc8b275fd9966583f63a6beb11f21cc29f32fa4e4e19c204
+  metadata.gz: 3cfaaa5a15a681d6ce11f36c8c04d116a245191f2148da349d71b0429fc931421e315d9bfe81faebabde0dc077afe7779969fa1eccc728510d43c5f3dda280f6
+  data.tar.gz: 0c40c4d0cd2e6a45dc2c30614217b994caf48ce3e6871f3c8945e918bbae174f66b0fae6e3a11452f5dadcf48093f721e2045dca0c9014972395d8e3c34b652b

data/README.md

@@ -0,0 +1,45 @@
+# Suno AI API Ruby SDK for RunAPI
+
+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.
+
+This suno ai api README is the Ruby package guide inside the public `suno-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/suno; for API reference, use https://runapi.ai/docs#suno; for SDK docs, use https://runapi.ai/docs#sdk-suno.
+
+## Install
+
+```bash
+gem install runapi-suno
+```
+
+## Quick start
+
+```ruby
+require "runapi-suno"
+
+client = RunApi::Suno::Client.new
+task = client.generations.create(
+  # Pass the Suno JSON request body from https://runapi.ai/docs#suno.
+)
+status = client.generations.get(task.id)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion. In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.
+
+## Language notes
+
+Use Ruby keyword arguments and the `RunApi::Suno` error classes when building music jobs, Rails workers, or scripts. The available resources include generations, extensions, upload and extensions, covers, upload and covers, instrumentals, vocals, vocal removals, midi, wav conversions, music videos, lyrics, timestamped lyrics, section replacements, mashups, sounds, personas, and styles. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/suno
+- SDK docs: https://runapi.ai/docs#sdk-suno
+- Product docs: https://runapi.ai/docs#suno
+- Pricing and rate limits: https://runapi.ai/models/suno/v4
+- Provider comparison: https://runapi.ai/providers/suno
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/suno-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/suno/client.rb

@@ -2,17 +2,61 @@
 
 module RunApi
   module Suno
-    class Client
-      attr_reader :text_to_music, :extend_music, :generate_artwork, :cover_audio,
-        :add_instrumental, :add_vocals, :separate_audio_stems, :generate_midi,
-        :convert_audio, :visualize_music, :generate_lyrics, :get_timestamped_lyrics,
-        :replace_section, :create_mashup, :text_to_sound, :generate_persona, :boost_style
+    # Suno music platform client covering song generation, extension, covers, stems,
+    # MIDI, lyrics, mashups, sound effects, visualization, personas, and voice cloning.
+    #
+    # @example Generate a song from a text prompt
+    #   client = RunApi::Suno::Client.new(api_key: "sk-your-api-key")
+    #   result = client.text_to_music.run(
+    #     prompt: "A chill lo-fi beat with soft vocals",
+    #     model: "suno-v4.5-plus"
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToMusic] generates songs from a text prompt with configurable vocal mode, style, and persona
+      attr_reader :text_to_music
+      # @return [Resources::ExtendMusic] continues an existing track from a specified timestamp
+      attr_reader :extend_music
+      # @return [Resources::GenerateArtwork] creates cover artwork for an existing music task
+      attr_reader :generate_artwork
+      # @return [Resources::CoverAudio] re-records vocals over an uploaded audio file with a new style or voice
+      attr_reader :cover_audio
+      # @return [Resources::AddInstrumental] generates and adds an instrumental backing track to uploaded audio
+      attr_reader :add_instrumental
+      # @return [Resources::AddVocals] generates and adds vocals to an uploaded instrumental track
+      attr_reader :add_vocals
+      # @return [Resources::SeparateAudioStems] splits a track into individual instrument stems
+      attr_reader :separate_audio_stems
+      # @return [Resources::GenerateMidi] extracts per-instrument MIDI note data from a generated track
+      attr_reader :generate_midi
+      # @return [Resources::ConvertAudio] converts a generated track to WAV format
+      attr_reader :convert_audio
+      # @return [Resources::VisualizeMusic] generates a music visualization video from an existing track
+      attr_reader :visualize_music
+      # @return [Resources::GenerateLyrics] produces AI-generated lyrics from a text prompt
+      attr_reader :generate_lyrics
+      # @return [Resources::GetTimestampedLyrics] retrieves word-level timing alignment for a track (synchronous)
+      attr_reader :get_timestamped_lyrics
+      # @return [Resources::ReplaceSection] re-generates a time range within an existing track
+      attr_reader :replace_section
+      # @return [Resources::CreateMashup] blends two audio tracks into a single new composition
+      attr_reader :create_mashup
+      # @return [Resources::TextToSound] generates sound effects from a text description
+      attr_reader :text_to_sound
+      # @return [Resources::VoiceToValidationPhrase] step 1 of voice cloning: extracts a validation phrase
+      attr_reader :voice_to_validation_phrase
+      # @return [Resources::RegenerateValidationPhrase] step 2 (optional) of voice cloning: requests a new phrase
+      attr_reader :regenerate_validation_phrase
+      # @return [Resources::GenerateVoice] step 3 of voice cloning: trains a custom voice
+      attr_reader :generate_voice
+      # @return [Resources::CheckVoice] step 4 of voice cloning: checks whether a custom voice is ready (synchronous)
+      attr_reader :check_voice
+      # @return [Resources::GeneratePersona] creates a reusable style or voice persona from a track's vocals (synchronous)
+      attr_reader :generate_persona
+      # @return [Resources::BoostStyle] generates style/genre tags from a text description (synchronous)
+      attr_reader :boost_style
 
       def initialize(api_key: nil, **options)
-        @api_key = Core::Auth.resolve_api_key(api_key)
-
-        client_options = Core::ClientOptions.new(api_key: @api_key, **options)
-        http = client_options.http_client || Core::HttpClient.new(client_options)
+        super
 
         @text_to_music = Resources::TextToMusic.new(http)
         @extend_music = Resources::ExtendMusic.new(http)
@@ -29,6 +73,10 @@ module RunApi
         @replace_section = Resources::ReplaceSection.new(http)
         @create_mashup = Resources::CreateMashup.new(http)
         @text_to_sound = Resources::TextToSound.new(http)
+        @voice_to_validation_phrase = Resources::VoiceToValidationPhrase.new(http)
+        @regenerate_validation_phrase = Resources::RegenerateValidationPhrase.new(http)
+        @generate_voice = Resources::GenerateVoice.new(http)
+        @check_voice = Resources::CheckVoice.new(http)
         @generate_persona = Resources::GeneratePersona.new(http)
         @boost_style = Resources::BoostStyle.new(http)
       end

data/lib/runapi/suno/resources/add_instrumental.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates and adds an instrumental backing track to uploaded audio.
       class AddInstrumental
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/add_vocals.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates and adds vocals to an uploaded instrumental track.
       class AddVocals
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/boost_style.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates style/genre tags from a text description for use in style fields. Synchronous (run only).
       class BoostStyle
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/check_voice.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Step 4 of voice cloning: checks whether a custom voice is ready for use. Synchronous (run only).
+      class CheckVoice
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/suno/check_voice"
+        RESPONSE_CLASS = Types::CheckVoiceResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(**params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_check_voice!(params, self)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/suno/resources/convert_audio.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Converts a generated track to WAV format.
       class ConvertAudio
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/cover_audio.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Re-records vocals over an uploaded audio file with a new style or voice.
       class CoverAudio
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/create_mashup.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Blends two audio tracks into a single new composition.
       class CreateMashup
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/extend_music.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Continues an existing track from a specified timestamp, inheriting or overriding its settings.
       class ExtendMusic
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/generate_artwork.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Creates cover artwork for an existing music task.
       class GenerateArtwork
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/generate_lyrics.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Produces AI-generated lyrics from a text prompt.
       class GenerateLyrics
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/generate_midi.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Extracts per-instrument MIDI note data from a generated track.
       class GenerateMidi
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/generate_persona.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Creates a reusable style or voice persona from an existing track's vocals. Synchronous (run only).
       class GeneratePersona
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/generate_voice.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Step 3 of voice cloning: trains a custom voice from the user's recording of the validation phrase.
+      class GenerateVoice
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/suno/generate_voice"
+        RESPONSE_CLASS = Types::VoiceGenerationResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedVoiceGenerationResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(**params)
+          task = create(**params)
+          poll_until_complete { get(task.id) }
+        end
+
+        def create(**params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params)
+        end
+
+        def get(id)
+          request(:get, "#{ENDPOINT}/#{id}")
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_generate_voice!(params, self)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/suno/resources/get_timestamped_lyrics.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Retrieves word-level timing alignment for a track. Synchronous (run only, no create/get polling).
       class GetTimestampedLyrics
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/regenerate_validation_phrase.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Step 2 (optional) of voice cloning: requests a new, easier validation phrase.
+      class RegenerateValidationPhrase
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/suno/regenerate_validation_phrase"
+        RESPONSE_CLASS = Types::ValidationPhraseResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedValidationPhraseResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(**params)
+          task = create(**params)
+          poll_until_complete { get(task.id) }
+        end
+
+        def create(**params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params)
+        end
+
+        def get(id)
+          request(:get, "#{ENDPOINT}/#{id}")
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_regenerate_validation_phrase!(params, self)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/suno/resources/replace_section.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Re-generates a time range within an existing track with new lyrics and style.
       class ReplaceSection
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/separate_audio_stems.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Splits a track into individual instrument stems (vocals, drums, bass, guitar, etc.).
       class SeparateAudioStems
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/text_to_music.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates songs from a text prompt with configurable vocal mode, style, and persona.
       class TextToMusic
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/text_to_sound.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates sound effects (not music) from a text description with optional looping and BPM control.
       class TextToSound
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/visualize_music.rb

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Generates a music visualization video from an existing track.
       class VisualizeMusic
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/suno/resources/voice_to_validation_phrase.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Step 1 of voice cloning: extracts a validation phrase from a voice recording for the user to re-record.
+      class VoiceToValidationPhrase
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/suno/voice_to_validation_phrase"
+        RESPONSE_CLASS = Types::ValidationPhraseResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedValidationPhraseResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(**params)
+          task = create(**params)
+          poll_until_complete { get(task.id) }
+        end
+
+        def create(**params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params)
+        end
+
+        def get(id)
+          request(:get, "#{ENDPOINT}/#{id}")
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_voice_to_validation_phrase!(params, self)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/suno/types.rb

@@ -2,18 +2,46 @@
 
 module RunApi
   module Suno
+    # Suno type definitions, response models, and enum constants.
     module Types
-      MODELS = %w[suno-v5.5 suno-v5 suno-v4.5-plus suno-v4.5-all suno-v4.5 suno-v4 suno-v3.5].freeze
+      # Suno music generation engine versions. V5.5 has highest quality; V4 is the earliest available.
+      MODELS = %w[suno-v5.5 suno-v5 suno-v4.5-plus suno-v4.5-all suno-v4.5 suno-v4].freeze
+      # Model versions that support sound effect generation (subset of MODELS).
       SOUND_MODELS = %w[suno-v5 suno-v5.5].freeze
+      # Musical keys (major and minor) for sound effect generation.
       SOUND_KEYS = %w[
         Cm C#m Dm D#m Em Fm F#m Gm G#m Am A#m Bm
         C C# D D# E F F# G G# A A# B
       ].freeze
-      VOCAL_GENDERS = %w[f m].freeze
-      PERSONA_MODELS = %w[style_persona voice_persona].freeze
+      VOCAL_GENDERS = %w[female male].freeze
+      # "style" applies genre/mood without changing voice; "voice" applies cloned voice characteristics.
+      PERSONA_TYPES = %w[style voice].freeze
+      # "source" inherits settings from the original track; "custom" requires explicit values.
+      PARAMETER_MODES = %w[source custom].freeze
+      # auto_lyrics: generates from prompt; exact_lyrics: sings literal lyrics; instrumental: no vocals.
+      VOCAL_MODES = %w[auto_lyrics exact_lyrics instrumental].freeze
+      # separate_vocal: isolates vocals+instrumental; split_stem: splits into all individual instruments.
       SEPARATE_AUDIO_STEMS_TYPES = %w[separate_vocal split_stem].freeze
+      # Language for the voice-cloning validation phrase the user must read back.
+      VALIDATION_PHRASE_LANGUAGES = %w[en zh es fr pt de ja ko hi ru].freeze
+      # Singing ability of the voice being cloned; calibrates model expectations.
+      SINGER_SKILL_LEVELS = %w[beginner intermediate advanced professional].freeze
 
+      # Metadata and URLs for a generated music track.
       class Audio < RunApi::Core::BaseModel
+        optional :id, String
+        optional :audio_url, String
+        optional :stream_audio_url, String
+        optional :image_url, String
+        optional :lyrics, String
+        optional :model_name, String
+        optional :title, String
+        optional :tags, [String]
+        optional :duration, Numeric
+      end
+
+      # Metadata and URLs for a generated sound effect (distinct from music Audio).
+      class SoundAudio < RunApi::Core::BaseModel
         optional :id, String
         optional :audio_url, String
         optional :stream_audio_url, String
@@ -21,14 +49,16 @@ module RunApi
         optional :prompt, String
         optional :model_name, String
         optional :title, String
-        optional :tags, [ String ]
+        optional :tags, [String]
         optional :duration, Numeric
       end
 
+      # A URL to a generated cover artwork image.
       class Cover < RunApi::Core::BaseModel
         required :url, String
       end
 
+      # Word-level timing alignment for a single word in a track.
       class AlignedWord < RunApi::Core::BaseModel
         required :word, String
         required :success
@@ -37,6 +67,7 @@ module RunApi
         required :palign, Numeric
       end
 
+      # URLs for each isolated instrument stem after separation. Only populated stems have URLs.
       class SeparatedAudio < RunApi::Core::BaseModel
         optional :vocal_url, String
         optional :instrumental_url, String
@@ -54,6 +85,7 @@ module RunApi
         optional :woodwinds_url, String
       end
 
+      # A single MIDI note event within an instrument track.
       class MidiNote < RunApi::Core::BaseModel
         required :pitch, Numeric
         required :start_time, Numeric
@@ -61,22 +93,26 @@ module RunApi
         required :velocity, Numeric
       end
 
+      # All notes for a single instrument extracted from a track.
       class MidiInstrument < RunApi::Core::BaseModel
         required :name, String
-        optional :notes, [ -> { MidiNote } ]
+        optional :notes, [-> { MidiNote }]
       end
 
+      # A section of generated lyrics with an optional section title (e.g. "Chorus", "Verse 1").
       class Lyric < RunApi::Core::BaseModel
         optional :title, String
         required :text, String
       end
 
+      # A reusable style or voice persona, referenced by ID in generation params.
       class Persona < RunApi::Core::BaseModel
         required :id, String
         required :name, String
         required :description, String
       end
 
+      # Base response for all Suno async tasks, carrying lifecycle status and generation progress.
       class AsyncTaskResponse < RunApi::Core::TaskResponse
         required :id, String
         required :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
@@ -84,99 +120,137 @@ module RunApi
         optional :error, String
       end
 
+      # Result of a text-to-music generation task.
       class TextToMusicResponse < AsyncTaskResponse
-        optional :audios, [ -> { Audio } ]
+        optional :audios, [-> { Audio }]
         optional :audio_url, String
       end
 
+      # Result of a music extension task. +original_task_id+ references the source track.
       class ExtendMusicResponse < AsyncTaskResponse
-        optional :audios, [ -> { Audio } ]
+        optional :audios, [-> { Audio }]
         optional :original_task_id, String
       end
 
+      # Result of an artwork generation task containing cover image URLs.
       class GenerateArtworkResponse < AsyncTaskResponse
-        optional :covers, [ -> { Cover } ]
+        optional :covers, [-> { Cover }]
       end
 
+      # Result of a cover audio task.
       class CoverAudioResponse < AsyncTaskResponse
-        optional :audios, [ -> { Audio } ]
+        optional :audios, [-> { Audio }]
       end
 
+      # Result of adding an instrumental backing track.
       class AddInstrumentalResponse < TextToMusicResponse; end
+      # Result of adding vocals to a track.
       class AddVocalsResponse < TextToMusicResponse; end
-      class TextToSoundResponse < TextToMusicResponse; end
 
+      # Result of a sound effect generation task (uses SoundAudio instead of Audio).
+      class TextToSoundResponse < AsyncTaskResponse
+        optional :audios, [-> { SoundAudio }]
+      end
+
+      # Result of a stem separation task.
       class SeparateAudioStemsResponse < AsyncTaskResponse
         optional :separated_audios, -> { SeparatedAudio }
       end
 
+      # Result of a MIDI extraction task with per-instrument note data.
       class GenerateMidiResponse < AsyncTaskResponse
-        optional :instruments, [ -> { MidiInstrument } ]
+        optional :instruments, [-> { MidiInstrument }]
       end
 
+      # Result of a WAV conversion task.
       class ConvertAudioResponse < AsyncTaskResponse
         optional :wav_url, String
         optional :original_task_id, String
       end
 
+      # Result of a music visualization task containing the generated video URL.
       class VisualizeMusicResponse < AsyncTaskResponse
         optional :video_url, String
         optional :original_task_id, String
       end
 
+      # Result of a lyrics generation task with sectioned lyrics.
       class GenerateLyricsResponse < AsyncTaskResponse
-        optional :lyrics, [ -> { Lyric } ]
+        optional :lyrics, [-> { Lyric }]
       end
 
+      # Synchronous response containing word-level timing data and waveform for a track.
       class GetTimestampedLyricsResponse < RunApi::Core::BaseModel
-        optional :aligned_words, [ -> { AlignedWord } ]
-        optional :waveform_data, [ Numeric ]
+        optional :aligned_words, [-> { AlignedWord }]
+        optional :waveform_data, [Numeric]
         optional :hoot_cer, Numeric
         optional :is_streamed
       end
 
+      # Result of a section replacement task.
       class ReplaceSectionResponse < AsyncTaskResponse
         optional :track, -> { Audio }
-        optional :audios, [ -> { Audio } ]
+        optional :audios, [-> { Audio }]
       end
 
+      # Synchronous result of persona creation.
       class GeneratePersonaResponse < RunApi::Core::BaseModel
         required :persona, -> { Persona }
         optional :error, String
       end
 
+      # Synchronous result of style tag generation. +style+ contains the generated tags string.
       class BoostStyleResponse < RunApi::Core::BaseModel
         optional :style, String
         optional :error, String
       end
 
+      # Result of a mashup task.
       class CreateMashupResponse < AsyncTaskResponse
         optional :audio, -> { Audio }
-        optional :audios, [ -> { Audio } ]
+        optional :audios, [-> { Audio }]
+      end
+
+      # Result of a voice-cloning validation phrase task. The user must re-record this phrase.
+      class ValidationPhraseResponse < AsyncTaskResponse
+        optional :provider_status, String
+        optional :validation_phrase, String
+      end
+
+      # Result of a voice generation (training) task. +voice_id+ is usable in subsequent generation params.
+      class VoiceGenerationResponse < AsyncTaskResponse
+        optional :provider_status, String
+        optional :voice_id, String
+      end
+
+      # Synchronous result indicating whether a custom voice is ready for use.
+      class CheckVoiceResponse < RunApi::Core::BaseModel
+        optional :is_available
+        optional :error, String
       end
 
       class CompletedTextToMusicResponse < TextToMusicResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedExtendMusicResponse < ExtendMusicResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedGenerateArtworkResponse < GenerateArtworkResponse
-        required :covers, [ -> { Cover } ]
+        required :covers, [-> { Cover }]
       end
 
       class CompletedCoverAudioResponse < CoverAudioResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedAddInstrumentalResponse < AddInstrumentalResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedAddVocalsResponse < AddVocalsResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedSeparateAudioStemsResponse < SeparateAudioStemsResponse
@@ -184,7 +258,7 @@ module RunApi
       end
 
       class CompletedGenerateMidiResponse < GenerateMidiResponse
-        required :instruments, [ -> { MidiInstrument } ]
+        required :instruments, [-> { MidiInstrument }]
       end
 
       class CompletedConvertAudioResponse < ConvertAudioResponse
@@ -196,7 +270,7 @@ module RunApi
       end
 
       class CompletedGenerateLyricsResponse < GenerateLyricsResponse
-        required :lyrics, [ -> { Lyric } ]
+        required :lyrics, [-> { Lyric }]
       end
 
       class CompletedReplaceSectionResponse < ReplaceSectionResponse
@@ -204,11 +278,19 @@ module RunApi
       end
 
       class CompletedCreateMashupResponse < CreateMashupResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { Audio }]
       end
 
       class CompletedTextToSoundResponse < TextToSoundResponse
-        required :audios, [ -> { Audio } ]
+        required :audios, [-> { SoundAudio }]
+      end
+
+      class CompletedValidationPhraseResponse < ValidationPhraseResponse
+        required :validation_phrase, String
+      end
+
+      class CompletedVoiceGenerationResponse < VoiceGenerationResponse
+        required :voice_id, String
       end
     end
   end

data/lib/runapi/suno/validators.rb

@@ -5,34 +5,34 @@ module RunApi
     module Validators
       module_function
 
+      MUSIC_PROMPT_SHAPE_ERROR = "choose a valid vocal_mode: auto_lyrics, exact_lyrics, or instrumental"
+
       def validate_text_to_music!(params, resource)
-        if param(resource, params, :custom_mode)
-          require_param!(resource, params, :style)
-          require_param!(resource, params, :title)
-        else
-          require_param!(resource, params, :prompt)
-        end
+        validate_music_prompt_shape!(params, resource)
         require_param!(resource, params, :model)
+        validate_optional!(resource, params, :vocal_mode, Types::VOCAL_MODES)
         validate_optional!(resource, params, :model, Types::MODELS)
         validate_optional!(resource, params, :vocal_gender, Types::VOCAL_GENDERS)
-        validate_optional!(resource, params, :persona_model, Types::PERSONA_MODELS)
+        validate_optional!(resource, params, :persona_type, Types::PERSONA_TYPES)
       end
 
       def validate_extend_music!(params, resource)
         unless %i[task_id audio_id audio_url upload_url].any? { |key| param(resource, params, key) }
           raise Core::ValidationError, "task_id, audio_id, audio_url, or upload_url is required"
         end
-        require_param!(resource, params, :default_param_flag)
+        require_param!(resource, params, :parameter_mode)
         require_param!(resource, params, :model)
 
-        if truthy?(param(resource, params, :default_param_flag))
+        validate_optional!(resource, params, :parameter_mode, Types::PARAMETER_MODES)
+        if param(resource, params, :parameter_mode) == "custom"
           require_param!(resource, params, :style)
           require_param!(resource, params, :title)
           require_param!(resource, params, :continue_at)
         end
+        validate_extend_music_prompt_shape!(params, resource)
         validate_optional!(resource, params, :model, Types::MODELS)
         validate_optional!(resource, params, :vocal_gender, Types::VOCAL_GENDERS)
-        validate_optional!(resource, params, :persona_model, Types::PERSONA_MODELS)
+        validate_optional!(resource, params, :persona_type, Types::PERSONA_TYPES)
       end
 
       def validate_generate_artwork!(params, resource)
@@ -42,15 +42,11 @@ module RunApi
       def validate_cover_audio!(params, resource)
         require_param!(resource, params, :upload_url)
         require_param!(resource, params, :model)
-        if param(resource, params, :custom_mode)
-          require_param!(resource, params, :style)
-          require_param!(resource, params, :title)
-        else
-          require_param!(resource, params, :prompt)
-        end
+        validate_music_prompt_shape!(params, resource)
+        validate_optional!(resource, params, :vocal_mode, Types::VOCAL_MODES)
         validate_optional!(resource, params, :model, Types::MODELS)
         validate_optional!(resource, params, :vocal_gender, Types::VOCAL_GENDERS)
-        validate_optional!(resource, params, :persona_model, Types::PERSONA_MODELS)
+        validate_optional!(resource, params, :persona_type, Types::PERSONA_TYPES)
       end
 
       def validate_add_instrumental!(params, resource)
@@ -60,7 +56,7 @@ module RunApi
       end
 
       def validate_add_vocals!(params, resource)
-        require_all!(resource, params, :upload_url, :prompt, :title, :negative_tags, :style, :model)
+        require_all!(resource, params, :upload_url, :lyrics, :title, :negative_tags, :style, :model)
         validate_optional!(resource, params, :model, Types::MODELS)
         validate_optional!(resource, params, :vocal_gender, Types::VOCAL_GENDERS)
       end
@@ -91,7 +87,7 @@ module RunApi
       end
 
       def validate_replace_section!(params, resource)
-        require_all!(resource, params, :task_id, :audio_id, :prompt, :tags, :title, :infill_start_time, :infill_end_time)
+        require_all!(resource, params, :task_id, :audio_id, :lyrics, :tags, :title, :infill_start_time, :infill_end_time)
         if param(resource, params, :infill_end_time).to_f <= param(resource, params, :infill_start_time).to_f
           raise Core::ValidationError, "infill_end_time must be greater than infill_start_time"
         end
@@ -103,14 +99,11 @@ module RunApi
           raise Core::ValidationError, "upload_url_list must contain exactly 2 URLs"
         end
         require_param!(resource, params, :model)
-        if param(resource, params, :custom_mode)
-          require_all!(resource, params, :style, :title)
-          require_param!(resource, params, :prompt) unless truthy?(param(resource, params, :instrumental))
-        else
-          require_param!(resource, params, :prompt)
-        end
+        validate_music_prompt_shape!(params, resource)
+        validate_optional!(resource, params, :vocal_mode, Types::VOCAL_MODES)
         validate_optional!(resource, params, :model, Types::MODELS)
         validate_optional!(resource, params, :vocal_gender, Types::VOCAL_GENDERS)
+        validate_optional!(resource, params, :persona_type, Types::PERSONA_TYPES)
       end
 
       def validate_text_to_sound!(params, resource)
@@ -123,6 +116,30 @@ module RunApi
         end
       end
 
+      def validate_voice_to_validation_phrase!(params, resource)
+        require_all!(resource, params, :voice_url, :vocal_start_seconds, :vocal_end_seconds)
+        validate_optional!(resource, params, :language, Types::VALIDATION_PHRASE_LANGUAGES)
+
+        start_seconds = param(resource, params, :vocal_start_seconds).to_i
+        end_seconds = param(resource, params, :vocal_end_seconds).to_i
+        return if end_seconds > start_seconds
+
+        raise Core::ValidationError, "vocal_end_seconds must be greater than vocal_start_seconds"
+      end
+
+      def validate_regenerate_validation_phrase!(params, resource)
+        require_param!(resource, params, :task_id)
+      end
+
+      def validate_generate_voice!(params, resource)
+        require_all!(resource, params, :task_id, :verify_url)
+        validate_optional!(resource, params, :singer_skill_level, Types::SINGER_SKILL_LEVELS)
+      end
+
+      def validate_check_voice!(params, resource)
+        require_param!(resource, params, :task_id)
+      end
+
       def validate_generate_persona!(params, resource)
         require_all!(resource, params, :task_id, :audio_id, :name, :description)
       end
@@ -131,6 +148,45 @@ module RunApi
         require_param!(resource, params, :description)
       end
 
+      def validate_music_prompt_shape!(params, resource)
+        mode = param(resource, params, :vocal_mode).to_s
+        has_prompt = truthy_presence?(param(resource, params, :prompt))
+        has_lyrics = truthy_presence?(param(resource, params, :lyrics))
+        has_style = truthy_presence?(param(resource, params, :style))
+        has_title = truthy_presence?(param(resource, params, :title))
+
+        valid_shape = case mode
+        when "auto_lyrics"
+          has_prompt && !has_lyrics && !has_style && !has_title
+        when "exact_lyrics"
+          !has_prompt && has_lyrics && has_style && has_title
+        when "instrumental"
+          !has_prompt && !has_lyrics && has_style && has_title
+        else
+          false
+        end
+        return if valid_shape
+
+        raise Core::ValidationError, MUSIC_PROMPT_SHAPE_ERROR
+      end
+
+      def validate_extend_music_prompt_shape!(params, resource)
+        return unless truthy_presence?(param(resource, params, :lyrics))
+
+        if truthy_presence?(param(resource, params, :prompt))
+          raise Core::ValidationError, "prompt cannot be combined with lyrics"
+        end
+
+        if truthy?(param(resource, params, :instrumental))
+          raise Core::ValidationError, "lyrics cannot be used when instrumental is true"
+        end
+
+        upload_mode = %i[audio_url upload_url].any? { |key| truthy_presence?(param(resource, params, key)) }
+        return if param(resource, params, :parameter_mode) == "custom" && upload_mode
+
+        raise Core::ValidationError, "lyrics can only be used when extending uploaded audio with custom parameters"
+      end
+
       def require_all!(resource, params, *keys)
         keys.each { |key| require_param!(resource, params, key) }
       end
@@ -148,7 +204,13 @@ module RunApi
       end
 
       def truthy?(value)
-        [ true, 1, "1", "true", "TRUE", "True" ].include?(value)
+        [true, 1, "1", "true", "TRUE", "True"].include?(value)
+      end
+
+      def truthy_presence?(value)
+        return !value.empty? if value.respond_to?(:empty?)
+
+        !value.nil?
       end
     end
   end

data/lib/runapi/suno.rb

@@ -18,6 +18,10 @@ require_relative "suno/resources/get_timestamped_lyrics"
 require_relative "suno/resources/replace_section"
 require_relative "suno/resources/create_mashup"
 require_relative "suno/resources/text_to_sound"
+require_relative "suno/resources/voice_to_validation_phrase"
+require_relative "suno/resources/regenerate_validation_phrase"
+require_relative "suno/resources/generate_voice"
+require_relative "suno/resources/check_voice"
 require_relative "suno/resources/generate_persona"
 require_relative "suno/resources/boost_style"
 require_relative "suno/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-suno
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,28 +15,34 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.4
-description: RunAPI Suno SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: 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.
 email:
 - contact@runapi.ai
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
+- README.md
 - lib/runapi-suno.rb
 - lib/runapi/suno.rb
 - lib/runapi/suno/client.rb
 - lib/runapi/suno/resources/add_instrumental.rb
 - lib/runapi/suno/resources/add_vocals.rb
 - lib/runapi/suno/resources/boost_style.rb
+- lib/runapi/suno/resources/check_voice.rb
 - lib/runapi/suno/resources/convert_audio.rb
 - lib/runapi/suno/resources/cover_audio.rb
 - lib/runapi/suno/resources/create_mashup.rb
@@ -45,12 +51,15 @@ files:
 - lib/runapi/suno/resources/generate_lyrics.rb
 - lib/runapi/suno/resources/generate_midi.rb
 - lib/runapi/suno/resources/generate_persona.rb
+- lib/runapi/suno/resources/generate_voice.rb
 - lib/runapi/suno/resources/get_timestamped_lyrics.rb
+- lib/runapi/suno/resources/regenerate_validation_phrase.rb
 - lib/runapi/suno/resources/replace_section.rb
 - lib/runapi/suno/resources/separate_audio_stems.rb
 - lib/runapi/suno/resources/text_to_music.rb
 - lib/runapi/suno/resources/text_to_sound.rb
 - lib/runapi/suno/resources/visualize_music.rb
+- lib/runapi/suno/resources/voice_to_validation_phrase.rb
 - lib/runapi/suno/types.rb
 - lib/runapi/suno/validators.rb
 homepage: https://runapi.ai/models/suno
@@ -58,7 +67,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/suno
-  documentation_uri: https://github.com/runapi-ai/suno-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/suno-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/suno-sdk
   changelog_uri: https://github.com/runapi-ai/suno-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -77,5 +86,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Suno API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Suno AI API Ruby SDK for RunAPI
 test_files: []