runapi-suno 0.2.6 → 0.2.8

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

@@ -3,6 +3,7 @@
 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
 
@@ -14,19 +15,19 @@ module RunApi
           @http = http
         end
 
-        def run(**params)
-          task = create(**params)
-          poll_until_complete { get(task.id) }
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
         end
 
-        def create(**params)
+        def create(options: nil, **params)
           params = compact_params(params)
           validate_params!(params)
-          request(:post, ENDPOINT, body: params)
+          request(:post, ENDPOINT, body: params, options: options)
         end
 
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private

data/lib/runapi/suno/types.rb

@@ -2,21 +2,32 @@
 
 module RunApi
   module Suno
+    # Suno type definitions, response models, and enum constants.
     module Types
+      # 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[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
@@ -29,6 +40,7 @@ module RunApi
         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
@@ -41,10 +53,12 @@ module RunApi
         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
@@ -53,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
@@ -70,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
@@ -77,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 }]
       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 }
@@ -100,53 +120,66 @@ module RunApi
         optional :error, String
       end
 
+      # Result of a text-to-music generation task.
       class TextToMusicResponse < AsyncTaskResponse
         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 :original_task_id, String
       end
 
+      # Result of an artwork generation task containing cover image URLs.
       class GenerateArtworkResponse < AsyncTaskResponse
         optional :covers, [-> { Cover }]
       end
 
+      # Result of a cover audio task.
       class CoverAudioResponse < AsyncTaskResponse
         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
 
+      # 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 }]
       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 }]
       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]
@@ -154,36 +187,43 @@ module RunApi
         optional :is_streamed
       end
 
+      # Result of a section replacement task.
       class ReplaceSectionResponse < AsyncTaskResponse
         optional :track, -> { 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 }]
       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

data/lib/runapi/suno/validators.rb

@@ -5,15 +5,8 @@ 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)
-        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_type, Types::PERSONA_TYPES)
+        resource.send(:validate_contract!, CONTRACT["text-to-music"], params)
       end
 
       def validate_extend_music!(params, resource)
@@ -40,13 +33,7 @@ module RunApi
       end
 
       def validate_cover_audio!(params, resource)
-        require_param!(resource, params, :upload_url)
-        require_param!(resource, params, :model)
-        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)
+        resource.send(:validate_contract!, CONTRACT["cover-audio"], params)
       end
 
       def validate_add_instrumental!(params, resource)
@@ -87,10 +74,18 @@ module RunApi
       end
 
       def validate_replace_section!(params, resource)
-        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
+        resource.send(:validate_contract!, CONTRACT["replace-section"], params)
+        validate_replace_section_source!(params, resource)
+        start_time = replace_section_time!(params, resource, :infill_start_time)
+        end_time = replace_section_time!(params, resource, :infill_end_time)
+        if end_time <= start_time
           raise Core::ValidationError, "infill_end_time must be greater than infill_start_time"
         end
+
+        duration = end_time - start_time
+        return if duration.between?(6, 60)
+
+        raise Core::ValidationError, "replacement duration must be between 6 and 60 seconds"
       end
 
       def validate_create_mashup!(params, resource)
@@ -98,12 +93,7 @@ module RunApi
         unless upload_url_list.is_a?(Array) && upload_url_list.size == 2
           raise Core::ValidationError, "upload_url_list must contain exactly 2 URLs"
         end
-        require_param!(resource, params, :model)
-        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)
+        resource.send(:validate_contract!, CONTRACT["create-mashup"], params)
       end
 
       def validate_text_to_sound!(params, resource)
@@ -148,28 +138,6 @@ 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))
 
@@ -187,6 +155,30 @@ module RunApi
         raise Core::ValidationError, "lyrics can only be used when extending uploaded audio with custom parameters"
       end
 
+      def validate_replace_section_source!(params, resource)
+        has_existing_source = %i[task_id audio_id].any? { |key| truthy_presence?(param(resource, params, key)) }
+        has_uploaded_source = %i[upload_url model].any? { |key| truthy_presence?(param(resource, params, key)) }
+
+        if has_existing_source && has_uploaded_source
+          raise Core::ValidationError, "task_id/audio_id cannot be combined with upload_url/model"
+        end
+
+        if has_existing_source
+          require_all!(resource, params, :task_id, :audio_id)
+        elsif has_uploaded_source
+          require_all!(resource, params, :upload_url, :model)
+        else
+          raise Core::ValidationError, "task_id and audio_id, or upload_url and model are required"
+        end
+      end
+
+      def replace_section_time!(params, resource, key)
+        value = param(resource, params, key)
+        return value.to_f if value.is_a?(Numeric)
+
+        raise Core::ValidationError, "#{key} must be a number"
+      end
+
       def require_all!(resource, params, *keys)
         keys.each { |key| require_param!(resource, params, key) }
       end

data/lib/runapi/suno.rb

@@ -2,6 +2,7 @@
 
 require "runapi/core"
 require_relative "suno/types"
+require_relative "suno/contract_gen"
 require_relative "suno/validators"
 require_relative "suno/resources/text_to_music"
 require_relative "suno/resources/extend_music"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-suno
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
-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.
+        version: 0.2.10
+description: The Suno Ruby SDK is the language-specific package for Suno on RunAPI.
+  Use this package for song generation, lyrics, vocals, extension, and audio transformation
+  workflows when your application needs request bodies, task status lookup, and consistent
+  RunAPI errors in Ruby.
 email:
 - contact@runapi.ai
 executables: []
@@ -39,6 +39,7 @@ files:
 - lib/runapi-suno.rb
 - lib/runapi/suno.rb
 - lib/runapi/suno/client.rb
+- lib/runapi/suno/contract_gen.rb
 - lib/runapi/suno/resources/add_instrumental.rb
 - lib/runapi/suno/resources/add_vocals.rb
 - lib/runapi/suno/resources/boost_style.rb
@@ -66,9 +67,11 @@ homepage: https://runapi.ai/models/suno
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: suno
   homepage_uri: https://runapi.ai/models/suno
   documentation_uri: https://github.com/runapi-ai/suno-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/suno-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/suno-sdk/issues
   changelog_uri: https://github.com/runapi-ai/suno-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -86,5 +89,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Suno AI API Ruby SDK for RunAPI
+summary: Suno API Ruby SDK for RunAPI
 test_files: []