runapi-suno 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f676e53a763fe863f61cd2fbd16f0702c93f2d189f7369d1471e819dd01bfa79
-  data.tar.gz: 76e18fcc6c46fe6b0f97be04949db28868d9f4ea3bfe7efcf5aa5296ca9a6ff7
+  metadata.gz: 7408c126663eb2e648020669baa1dc31570c6df7eb74a2d38856c8ba25eb7d3e
+  data.tar.gz: 69968db8a1c4d03cafe72847d036be448f8eadb2edc7797445660371c700807a
 SHA512:
-  metadata.gz: 83832d65fe97b8d8bfa5eae30c1f095fe8ea13368f06242588d89e67aa31013e2cd9ef3b5b7ba14e760430b13d76cc83a942dafd7878b654f58d6a3ff0736b5a
-  data.tar.gz: 5973d5187e4c761c056f1cde61a2e68f6fab5be8d42988e66194989eaddaafda9e77b6b481d89ee5eea5d84997f86def8a6c57ac8ceebd34bd570701dbcb1866
+  metadata.gz: 3cfaaa5a15a681d6ce11f36c8c04d116a245191f2148da349d71b0429fc931421e315d9bfe81faebabde0dc077afe7779969fa1eccc728510d43c5f3dda280f6
+  data.tar.gz: 0c40c4d0cd2e6a45dc2c30614217b994caf48ce3e6871f3c8945e918bbae174f66b0fae6e3a11452f5dadcf48093f721e2045dca0c9014972395d8e3c34b652b

data/README.md

@@ -24,6 +24,8 @@ 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.
@@ -33,7 +35,7 @@ Use Ruby keyword arguments and the `RunApi::Suno` error classes when building mu
 - 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/v3.5
+- 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

data/lib/runapi/suno/client.rb

@@ -2,19 +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, :voice_to_validation_phrase,
-        :regenerate_validation_phrase, :generate_voice, :check_voice, :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)

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

@@ -3,6 +3,7 @@
 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
 

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

@@ -3,6 +3,7 @@
 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
 

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

@@ -3,6 +3,7 @@
 module RunApi
   module Suno
     module Resources
+      # Step 2 (optional) of voice cloning: requests a new, easier validation phrase.
       class RegenerateValidationPhrase
         include RunApi::Core::ResourceHelpers
 

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

@@ -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
 

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-suno
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        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,