runapi-suno 0.4.2 → 0.4.4

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

@@ -1,6 +1,9 @@
 module RunApi
   module Suno
     module Resources
+      # Adds a timed sample from an uploaded audio file to a music request.
+      #
+      # @deprecated Use {RunApi::Suno::Resources::MusicFromSample} instead.
       class AddSamples < AudioAction
         ENDPOINT = "/api/v1/suno/add_samples"
         ACTION = "add-samples"

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Exports an existing track to a downloadable audio file.
+      class AudioExports
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/audio_exports"
+        RESPONSE_CLASS = Types::AudioExportResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedAudioExportResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
+        end
+
+        def create(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_audio_exports!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,8 @@ module RunApi
   module Suno
     module Resources
       # Generates style/genre tags from a text description for use in style fields. Synchronous (run only).
+      #
+      # @deprecated Use {RunApi::Suno::Resources::StyleExpansions} instead.
       class BoostStyle
         include RunApi::Core::ResourceHelpers
 

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

@@ -4,6 +4,9 @@ module RunApi
   module Suno
     module Resources
       # Step 4 of voice cloning: checks whether a custom voice is ready for use. Synchronous (run only).
+      #
+      # @deprecated Use {RunApi::Suno::Resources::Voices} instead; its +get+ reports the
+      #   voice resource status directly.
       class CheckVoice
         include RunApi::Core::ResourceHelpers
 

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

@@ -4,6 +4,8 @@ module RunApi
   module Suno
     module Resources
       # Converts a generated track to WAV format.
+      #
+      # @deprecated Use {RunApi::Suno::Resources::AudioExports} instead.
       class ConvertAudio
         include RunApi::Core::ResourceHelpers
 

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

@@ -4,6 +4,9 @@ module RunApi
   module Suno
     module Resources
       # Creates a reusable style or voice persona from an existing track's vocals. Synchronous (run only).
+      #
+      # @deprecated Use {RunApi::Suno::Resources::Personas} instead, which returns an
+      #   account-owned persona resource that later requests reference by ID.
       class GeneratePersona
         include RunApi::Core::ResourceHelpers
 

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

@@ -4,6 +4,9 @@ module RunApi
   module Suno
     module Resources
       # Step 3 of voice cloning: trains a custom voice from the user's recording of the validation phrase.
+      #
+      # @deprecated Use {RunApi::Suno::Resources::Voices} instead, which creates a
+      #   reusable voice resource from a recording directly.
       class GenerateVoice
         include RunApi::Core::ResourceHelpers
 

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

@@ -4,6 +4,8 @@ module RunApi
   module Suno
     module Resources
       # Retrieves word-level timing alignment for a track. Synchronous (run only, no create/get polling).
+      #
+      # @deprecated Use {RunApi::Suno::Resources::TimestampedLyrics} instead.
       class GetTimestampedLyrics
         include RunApi::Core::ResourceHelpers
 

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Creates music guided by a sample of an uploaded audio file.
+      class MusicFromSample
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/music_from_sample"
+        RESPONSE_CLASS = Types::MusicFromSampleResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedMusicFromSampleResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
+        end
+
+        def create(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_music_from_sample!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Renders a visualization video for an existing track.
+      class MusicVisualizations
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/music_visualizations"
+        RESPONSE_CLASS = Types::MusicVisualizationResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedMusicVisualizationResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
+        end
+
+        def create(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_music_visualizations!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Creates and retrieves the personas a music request can reuse.
+      #
+      # A persona is an account-owned resource: create it once, then pass its ID in
+      # the persona_id field of music generation params. Holding the resource ID
+      # instead of the creating request keeps a workflow resumable after that request
+      # is gone. A request handled inline returns the persona; a request accepted for
+      # deferred execution is followed to its stored result.
+      class Personas
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/personas"
+        RESPONSE_CLASS = Types::PersonaCreationResponse
+        RESOURCE_RESPONSE_CLASS = Types::PersonaResourceResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          run_hybrid(ENDPOINT, body: params, options: options, response_class: RESPONSE_CLASS)
+        end
+
+        # Submits a persona request. A request handled inline carries the finished
+        # persona; a request accepted for deferred execution carries its task ID
+        # and status, plus Location and Retry-After response headers.
+        def create(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        def subscribe(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          subscribe_hybrid(ENDPOINT, body: params, options: options, response_class: RESPONSE_CLASS)
+        end
+
+        # Retrieves a persona resource by its account-owned ID.
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options, response_class: RESOURCE_RESPONSE_CLASS)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_personas!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Expands a style description into genre tags for use in style fields.
+      # Synchronous (run only, no create/get polling).
+      class StyleExpansions
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/style_expansions"
+        RESPONSE_CLASS = Types::BoostStyleResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_style_expansions!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Retrieves word-level timing alignment for an existing track.
+      # Synchronous (run only, no create/get polling).
+      class TimestampedLyrics
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/timestamped_lyrics"
+        RESPONSE_CLASS = Types::TimestampedLyricsResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_timestamped_lyrics!(params, self)
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,8 @@ module RunApi
   module Suno
     module Resources
       # Generates a music visualization video from an existing track.
+      #
+      # @deprecated Use {RunApi::Suno::Resources::MusicVisualizations} instead.
       class VisualizeMusic
         include RunApi::Core::ResourceHelpers
 

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Resources
+      # Creates and retrieves voices a music request can reuse.
+      #
+      # A voice is an account-owned resource: create it from a recording, then pass its
+      # ID wherever a voice persona is accepted. +get+ reports whether the voice is
+      # ready, so readiness needs no separate request.
+      class Voices
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/voices"
+        RESPONSE_CLASS = Types::VoiceCreationResponse
+        RESOURCE_RESPONSE_CLASS = Types::VoiceResourceResponse
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(options: nil, **params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params, options: options)
+        end
+
+        # Retrieves a voice resource by its account-owned ID.
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options, response_class: RESOURCE_RESPONSE_CLASS)
+        end
+
+        private
+
+        def validate_params!(params)
+          Validators.validate_voices!(params, self)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/suno/types/completed_responses.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Types
+      class CompletedTextToMusicResponse < TextToMusicResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedExtendMusicResponse < ExtendMusicResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedGenerateArtworkResponse < GenerateArtworkResponse
+        required :covers, [-> { Cover }]
+      end
+
+      class CompletedCoverAudioResponse < CoverAudioResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedAddInstrumentalResponse < AddInstrumentalResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedAddVocalsResponse < AddVocalsResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedSeparateAudioStemsResponse < SeparateAudioStemsResponse
+        required :separated_audios, -> { SeparatedAudio }
+      end
+
+      class CompletedGenerateMidiResponse < GenerateMidiResponse
+        required :instruments, [-> { MidiInstrument }]
+      end
+
+      class CompletedConvertAudioResponse < ConvertAudioResponse
+        required :wav_url, String
+      end
+
+      class CompletedVisualizeMusicResponse < VisualizeMusicResponse
+        required :video_url, String
+      end
+
+      class CompletedGenerateLyricsResponse < GenerateLyricsResponse
+        required :lyrics, [-> { Lyric }]
+      end
+
+      class CompletedBlendLyricsResponse < BlendLyricsResponse
+        required :lyrics, [-> { Lyric }]
+      end
+
+      class CompletedReplaceSectionResponse < ReplaceSectionResponse
+        required :track, -> { Audio }
+      end
+
+      class CompletedCreateMashupResponse < CreateMashupResponse
+        required :audios, [-> { Audio }]
+      end
+
+      class CompletedTextToSoundResponse < TextToSoundResponse
+        required :audios, [-> { SoundAudio }]
+      end
+
+      class CompletedValidationPhraseResponse < ValidationPhraseResponse
+        required :validation_phrase, String
+      end
+
+      class CompletedVoiceGenerationResponse < VoiceGenerationResponse
+        required :voice_id, String
+      end
+    end
+  end
+end

data/lib/runapi/suno/types/resource_responses.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Suno
+    module Types
+      module ResourceStatus
+        AVAILABLE = "available"
+        FAILED = "failed"
+
+        ALL = [AVAILABLE, FAILED].freeze
+      end
+
+      # Billing envelope for a resource lookup. Resource provenance remains opaque.
+      class ResourceBilling < RunApi::Core::BaseModel
+      end
+
+      class PersonaResource < RunApi::Core::BaseModel
+        required :id, String
+        optional :name, String
+        optional :description, String
+      end
+
+      class VoiceResource < RunApi::Core::BaseModel
+        required :id, String
+        optional :name, String
+      end
+
+      class PersonaCreationResponse < RunApi::Core::BaseModel
+        optional :persona, -> { PersonaResource }
+        optional :id, String
+        optional :status, String
+        optional :error, String
+        optional :billing, RunApi::Core::TaskBillingFacts
+      end
+
+      class VoiceCreationResponse < RunApi::Core::BaseModel
+        required :voice, -> { VoiceResource }
+        optional :billing, RunApi::Core::TaskBillingFacts
+      end
+
+      class TimestampedLyricsResponse < RunApi::Core::BaseModel
+        optional :aligned_words, [-> { AlignedWord }]
+        optional :waveform_data, [Numeric]
+        optional :hoct_cer, Numeric
+        optional :is_streamed
+        optional :billing, RunApi::Core::TaskBillingFacts
+      end
+
+      class PersonaResourceResponse < RunApi::Core::BaseModel
+        required :persona, -> { PersonaResource }
+        required :status, String, enum: -> { ResourceStatus::ALL }
+        required :billing, ResourceBilling
+      end
+
+      class VoiceResourceResponse < RunApi::Core::BaseModel
+        required :voice, -> { VoiceResource }
+        required :status, String, enum: -> { ResourceStatus::ALL }
+        required :billing, ResourceBilling
+      end
+
+      class AudioExportResponse < AsyncTaskResponse
+        optional :wav_url, String
+        optional :original_task_id, String
+      end
+
+      class MusicVisualizationResponse < AsyncTaskResponse
+        optional :video_url, String
+        optional :original_task_id, String
+      end
+
+      class MusicFromSampleResponse < AsyncTaskResponse
+        optional :audios, [-> { Audio }]
+      end
+
+      class CompletedAudioExportResponse < AudioExportResponse
+        required :wav_url, String
+      end
+
+      class CompletedMusicVisualizationResponse < MusicVisualizationResponse
+        required :video_url, String
+      end
+
+      class CompletedMusicFromSampleResponse < MusicFromSampleResponse
+        required :audios, [-> { Audio }]
+      end
+    end
+  end
+end

data/lib/runapi/suno/types.rb

@@ -5,7 +5,7 @@ module RunApi
     # 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
+      MODELS = %w[suno-v6 suno-v6-wild suno-v6-mini 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.
@@ -251,74 +251,6 @@ module RunApi
         optional :error, String
         optional :billing, RunApi::Core::TaskBillingFacts
       end
-
-      class CompletedTextToMusicResponse < TextToMusicResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedExtendMusicResponse < ExtendMusicResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedGenerateArtworkResponse < GenerateArtworkResponse
-        required :covers, [-> { Cover }]
-      end
-
-      class CompletedCoverAudioResponse < CoverAudioResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedAddInstrumentalResponse < AddInstrumentalResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedAddVocalsResponse < AddVocalsResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedSeparateAudioStemsResponse < SeparateAudioStemsResponse
-        required :separated_audios, -> { SeparatedAudio }
-      end
-
-      class CompletedGenerateMidiResponse < GenerateMidiResponse
-        required :instruments, [-> { MidiInstrument }]
-      end
-
-      class CompletedConvertAudioResponse < ConvertAudioResponse
-        required :wav_url, String
-      end
-
-      class CompletedVisualizeMusicResponse < VisualizeMusicResponse
-        required :video_url, String
-      end
-
-      class CompletedGenerateLyricsResponse < GenerateLyricsResponse
-        required :lyrics, [-> { Lyric }]
-      end
-
-      class CompletedBlendLyricsResponse < BlendLyricsResponse
-        required :lyrics, [-> { Lyric }]
-      end
-
-      class CompletedReplaceSectionResponse < ReplaceSectionResponse
-        required :track, -> { Audio }
-      end
-
-      class CompletedCreateMashupResponse < CreateMashupResponse
-        required :audios, [-> { Audio }]
-      end
-
-      class CompletedTextToSoundResponse < TextToSoundResponse
-        required :audios, [-> { SoundAudio }]
-      end
-
-      class CompletedValidationPhraseResponse < ValidationPhraseResponse
-        required :validation_phrase, String
-      end
-
-      class CompletedVoiceGenerationResponse < VoiceGenerationResponse
-        required :voice_id, String
-      end
     end
   end
 end

data/lib/runapi/suno/validators.rb

@@ -133,6 +133,34 @@ module RunApi
         require_param!(resource, params, :description)
       end
 
+      def validate_personas!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["personas"], params)
+      end
+
+      def validate_voices!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["voices"], params)
+      end
+
+      def validate_style_expansions!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["style-expansions"], params)
+      end
+
+      def validate_timestamped_lyrics!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["timestamped-lyrics"], params)
+      end
+
+      def validate_audio_exports!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["audio-exports"], params)
+      end
+
+      def validate_music_visualizations!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["music-visualizations"], params)
+      end
+
+      def validate_music_from_sample!(params, resource)
+        resource.send(:validate_contract!, CONTRACT["music-from-sample"], params)
+      end
+
       def validate_extend_music_prompt_shape!(params, resource)
         return unless truthy_presence?(param(resource, params, :lyrics))
 

data/lib/runapi/suno.rb

@@ -2,6 +2,8 @@
 
 require "runapi/core"
 require_relative "suno/types"
+require_relative "suno/types/completed_responses"
+require_relative "suno/types/resource_responses"
 require_relative "suno/contract_gen"
 require_relative "suno/validators"
 require_relative "suno/resources/text_to_music"
@@ -31,6 +33,13 @@ 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/resources/personas"
+require_relative "suno/resources/voices"
+require_relative "suno/resources/style_expansions"
+require_relative "suno/resources/timestamped_lyrics"
+require_relative "suno/resources/audio_exports"
+require_relative "suno/resources/music_visualizations"
+require_relative "suno/resources/music_from_sample"
 require_relative "suno/client"
 
 module RunApi