@runapi.ai/suno 0.2.6 → 0.2.7

package/dist/index.d.ts

@@ -1,32 +1,57 @@
-import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, ClientOptions } from '@runapi.ai/core';
+import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, BaseClient, ClientOptions } from '@runapi.ai/core';
 export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundError, RateLimitError, RunApiError, ServiceUnavailableError, TaskFailedError, TaskTimeoutError, TimeoutError, ValidationError } from '@runapi.ai/core';
 
+/** Suno music generation engine version. V5.5 has highest quality; V4 is the earliest available. */
 type SunoModel = 'suno-v5.5' | 'suno-v5' | 'suno-v4.5-plus' | 'suno-v4.5-all' | 'suno-v4.5' | 'suno-v4';
+/** Model versions that support sound effect generation (subset of SunoModel). */
 type SoundModel = 'suno-v5' | 'suno-v5.5';
+/** Language for the voice-cloning validation phrase the user must read back. */
 type ValidationPhraseLanguage = 'en' | 'zh' | 'es' | 'fr' | 'pt' | 'de' | 'ja' | 'ko' | 'hi' | 'ru';
+/** Musical key for sound effect generation (major and minor keys). */
 type SoundKey = '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';
 type VocalGender = 'male' | 'female';
+/** `style` applies genre/mood without changing the voice; `voice` applies cloned voice characteristics. */
 type PersonaType = 'style' | 'voice';
+/** `source` inherits style/title/continue_at from the original track; `custom` requires explicit values. */
 type ParameterMode = 'source' | 'custom';
+/**
+ * Controls how vocals are generated.
+ * - `auto_lyrics`: generates lyrics automatically from the `prompt` field
+ * - `exact_lyrics`: sings the exact text in the `lyrics` field
+ * - `instrumental`: produces music with no vocals
+ */
 type VocalMode = 'auto_lyrics' | 'exact_lyrics' | 'instrumental';
 type TaskStatus = AsyncTaskStatus;
+/** Progress phase of a multi-step music generation task. */
 type GenerationStage = 'text_generated' | 'first_audio_ready' | 'all_audios_ready' | 'failed';
+/** Singing ability of the voice being cloned; calibrates model expectations during voice generation. */
 type SingerSkillLevel = 'beginner' | 'intermediate' | 'advanced' | 'professional';
+/**
+ * Fields shared across most Suno music generation endpoints.
+ * `style_weight`, `weirdness_constraint`, and `audio_weight` are 0-1 knobs (2 decimal places)
+ * that tune style adherence, creative deviation, and audio fidelity respectively.
+ */
 interface SunoBaseParams {
     callback_url?: string;
     model?: SunoModel;
     vocal_gender?: VocalGender;
+    /** 0-1; higher values enforce stricter style adherence. */
     style_weight?: number;
+    /** 0-1; higher values allow more creative deviation from the prompt. */
     weirdness_constraint?: number;
+    /** 0-1; higher values prioritize audio fidelity over stylistic variation. */
     audio_weight?: number;
 }
+/** Auto-lyrics variant: generates lyrics automatically from `prompt`. */
 interface TextToMusicPromptParams extends SunoBaseParams {
     vocal_mode: 'auto_lyrics';
+    /** Song brief used for automatic lyrics generation. */
     prompt: string;
     lyrics?: never;
     style?: never;
     title?: never;
 }
+/** Exact-lyrics variant: sings the literal `lyrics` text with explicit style/title. */
 interface TextToMusicLyricsParams extends SunoBaseParams {
     vocal_mode: 'exact_lyrics';
     prompt?: never;
@@ -35,11 +60,14 @@ interface TextToMusicLyricsParams extends SunoBaseParams {
     title: string;
     persona_id?: string;
     persona_type?: PersonaType;
+    /** Styles to avoid (e.g. "heavy metal, screamo"). */
     negative_tags?: string;
     duration_seconds?: number;
+    /** Timestamp in seconds to continue generation from. */
     continue_at?: number;
     endpoint?: string;
 }
+/** Instrumental variant: produces music with no vocals. Requires explicit style/title. */
 interface TextToMusicInstrumentalParams extends SunoBaseParams {
     vocal_mode: 'instrumental';
     prompt?: never;
@@ -53,30 +81,49 @@ interface TextToMusicInstrumentalParams extends SunoBaseParams {
     continue_at?: number;
     endpoint?: string;
 }
+/**
+ * Params for text-to-music generation. The discriminated union on `vocal_mode` determines
+ * which fields are required: `auto_lyrics` needs `prompt`, `exact_lyrics` needs `lyrics` + `style` + `title`,
+ * and `instrumental` needs `style` + `title`.
+ */
 type TextToMusicParams = TextToMusicPromptParams | TextToMusicLyricsParams | TextToMusicInstrumentalParams;
+/**
+ * Params for extending an existing track from a specified timestamp.
+ * Provide exactly one source: `task_id`, `audio_id`, `audio_url`, or `upload_url`.
+ * `parameter_mode` controls whether to inherit the source track's settings (`source`)
+ * or override style, title, and continue_at (`custom`).
+ */
 interface ExtendMusicParams extends SunoBaseParams {
     task_id?: string;
     audio_id?: string;
     audio_url?: string;
     upload_url?: string;
     parameter_mode: ParameterMode;
+    /** When true, produces an instrumental extension with no vocals. */
     instrumental?: boolean;
     prompt?: string;
     lyrics?: string;
+    /** Required when parameter_mode is `custom`. */
     style?: string;
+    /** Required when parameter_mode is `custom`. Max ~80-100 characters. */
     title?: string;
+    /** Required when parameter_mode is `custom`. Seconds, must be > 0 and < source duration. */
     continue_at?: number;
     persona_id?: string;
     persona_type?: PersonaType;
     model?: SunoModel;
     negative_tags?: string;
 }
+/** Params for generating cover artwork for an existing music task. */
 interface GenerateArtworkParams {
+    /** Source music task ID to generate artwork for. */
     task_id: string;
     callback_url?: string;
     [key: string]: unknown;
 }
+/** Cover audio with auto-generated lyrics from a prompt. */
 interface CoverAudioPromptParams extends SunoBaseParams {
+    /** URL of the audio file to re-record vocals over. */
     upload_url: string;
     vocal_mode: 'auto_lyrics';
     prompt: string;
@@ -85,6 +132,7 @@ interface CoverAudioPromptParams extends SunoBaseParams {
     title?: never;
     negative_tags?: string;
 }
+/** Cover audio with exact lyrics sung over the uploaded track. */
 interface CoverAudioLyricsParams extends SunoBaseParams {
     upload_url: string;
     vocal_mode: 'exact_lyrics';
@@ -96,6 +144,7 @@ interface CoverAudioLyricsParams extends SunoBaseParams {
     persona_type?: PersonaType;
     negative_tags?: string;
 }
+/** Cover audio as instrumental (no vocals) over the uploaded track. */
 interface CoverAudioInstrumentalParams extends SunoBaseParams {
     upload_url: string;
     vocal_mode: 'instrumental';
@@ -107,98 +156,166 @@ interface CoverAudioInstrumentalParams extends SunoBaseParams {
     persona_type?: PersonaType;
     negative_tags?: string;
 }
+/**
+ * Params for re-recording vocals over an uploaded audio file. Discriminated on `vocal_mode`
+ * the same way as {@link TextToMusicParams}.
+ */
 type CoverAudioParams = CoverAudioPromptParams | CoverAudioLyricsParams | CoverAudioInstrumentalParams;
+/**
+ * Params for generating and adding an instrumental backing track to uploaded audio.
+ * `tags` and `negative_tags` control the generated style; pass empty strings if no preference.
+ */
 interface AddInstrumentalParams extends SunoBaseParams {
     model?: SunoModel;
     upload_url: string;
     title: string;
+    /** Styles to avoid (required, but can be empty string). */
     negative_tags: string;
+    /** Style/genre tags for the generated instrumental. */
     tags: string;
 }
+/** Params for generating and adding vocals to an uploaded instrumental track. */
 interface AddVocalsParams extends SunoBaseParams {
     model?: SunoModel;
     upload_url: string;
+    /** Vocal lyrics to sing over the instrumental. */
     lyrics: string;
     title: string;
+    /** Styles to avoid (required, but can be empty string). */
     negative_tags: string;
     style: string;
 }
+/** Params for splitting a track into individual instrument stems (vocals, drums, bass, etc.). */
 interface SeparateAudioStemsParams {
     task_id: string;
     audio_id: string;
+    /** `separate_vocal` isolates vocals+instrumental; `split_stem` splits into all individual instruments. */
     type?: 'separate_vocal' | 'split_stem' | string;
     callback_url?: string;
 }
+/** Params for extracting per-instrument MIDI note data from a generated track. */
 interface GenerateMidiParams {
     task_id: string;
     callback_url?: string;
 }
+/** Params for converting a generated track to WAV format. */
 interface ConvertAudioParams {
     task_id: string;
     audio_id?: string;
     callback_url?: string;
 }
+/** Params for generating a music visualization video from an existing track. */
 interface VisualizeMusicParams {
     task_id: string;
     audio_id?: string;
     prompt?: string;
     callback_url?: string;
+    /** Author name displayed in the visualization video. */
     author?: string;
+    /** Domain name watermark overlaid on the video. */
     domain_name?: string;
 }
+/** Params for AI-powered lyrics generation from a text prompt. */
 interface GenerateLyricsParams {
     prompt: string;
     callback_url?: string;
 }
+/** Params for retrieving word-level timing alignment for a track. Synchronous -- use `run()` directly. */
 interface GetTimestampedLyricsParams {
     task_id: string;
     audio_id: string;
     callback_url?: string;
 }
+/**
+ * Params for re-generating a time range within an existing track with new lyrics and style.
+ * `infill_start_time` and `infill_end_time` define the section boundaries in seconds.
+ */
 interface ReplaceSectionParams {
     task_id: string;
     audio_id: string;
+    /** Replacement lyrics for the specified section. */
     lyrics: string;
+    /** Style/genre tags for the replacement section. */
     tags: string;
     title: string;
+    /** Section start time in seconds. */
     infill_start_time: number;
+    /** Section end time in seconds. */
     infill_end_time: number;
     callback_url?: string;
     negative_tags?: string;
+    /** Complete song lyrics for context; helps maintain coherence across sections. */
     full_lyrics?: string;
 }
+/**
+ * Params for creating a reusable persona from an existing track's vocals.
+ * The persona can be referenced by ID in subsequent generation params. Synchronous -- use `run()` directly.
+ */
 interface GeneratePersonaParams {
+    /** Source task ID containing reference vocals. */
     task_id: string;
     audio_id: string;
     name: string;
     description: string;
 }
+/**
+ * Params for generating style/genre tags from a text description.
+ * Useful for filling `style` fields in other params. Synchronous -- use `run()` directly.
+ */
 interface BoostStyleParams {
+    /** Style description to generate tags from (e.g. "upbeat summer pop with acoustic guitar"). */
     description: string;
     name?: string;
 }
+/**
+ * Params for sound effect generation (not music -- use {@link TextToMusicParams} for songs).
+ * Supports loopable audio, BPM control, and musical key selection.
+ */
 interface TextToSoundParams {
     callback_url?: string;
     model: SoundModel;
+    /** Sound description, max 500 characters. */
     prompt: string;
+    /** When true, generates seamlessly loopable audio. */
     sound_loop?: boolean;
+    /** BPM (1-300) for rhythmic sound effects. */
     sound_tempo?: number;
     sound_key?: SoundKey;
+    /** When true, captures lyric subtitles from the generated audio. */
     grab_lyrics?: boolean;
 }
+/**
+ * Step 1 of voice cloning: upload a voice recording and specify vocal segment boundaries.
+ * Returns a validation phrase the user must re-record and submit via {@link GenerateVoiceParams}.
+ *
+ * Voice cloning workflow: VoiceToValidationPhrase -> RegenerateValidationPhrase (optional) -> GenerateVoice -> CheckVoice.
+ */
 interface VoiceToValidationPhraseParams {
+    /** URL of the source voice recording. */
     voice_url: string;
+    /** Start of the vocal segment in the recording (seconds). */
     vocal_start_seconds: number;
+    /** End of the vocal segment in the recording (seconds). */
     vocal_end_seconds: number;
     language?: ValidationPhraseLanguage;
     callback_url?: string;
 }
+/**
+ * Step 2 (optional) of voice cloning: requests a new, easier validation phrase for an
+ * in-progress voice cloning task, if the original phrase was too difficult.
+ */
 interface RegenerateValidationPhraseParams {
+    /** Task ID from a prior VoiceToValidationPhrase call. */
     task_id: string;
     callback_url?: string;
 }
+/**
+ * Step 3 of voice cloning: submits the user's recording of the validation phrase to train a custom voice.
+ * `task_id` is from the prior VoiceToValidationPhrase task; `verify_url` is the user's recording.
+ */
 interface GenerateVoiceParams {
     task_id: string;
+    /** URL of the user's recording of the validation phrase. */
     verify_url: string;
     voice_name?: string;
     description?: string;
@@ -206,10 +323,17 @@ interface GenerateVoiceParams {
     singer_skill_level?: SingerSkillLevel;
     callback_url?: string;
 }
+/**
+ * Step 4 (final) of voice cloning: checks whether a custom voice from GenerateVoice is ready.
+ * Synchronous -- use `run()` directly.
+ */
 interface CheckVoiceParams {
+    /** Task ID from a prior GenerateVoice call. */
     task_id: string;
 }
+/** Mashup with auto-generated lyrics. */
 interface CreateMashupPromptParams extends SunoBaseParams {
+    /** Exactly two audio URLs to blend into one composition. */
     upload_url_list: [string, string];
     model?: SunoModel;
     vocal_mode: 'auto_lyrics';
@@ -218,6 +342,7 @@ interface CreateMashupPromptParams extends SunoBaseParams {
     style?: never;
     title?: never;
 }
+/** Mashup with exact lyrics sung over the blended tracks. */
 interface CreateMashupLyricsParams extends SunoBaseParams {
     upload_url_list: [string, string];
     model?: SunoModel;
@@ -229,6 +354,7 @@ interface CreateMashupLyricsParams extends SunoBaseParams {
     persona_id?: string;
     persona_type?: PersonaType;
 }
+/** Mashup as instrumental (no vocals). */
 interface CreateMashupInstrumentalParams extends SunoBaseParams {
     upload_url_list: [string, string];
     model?: SunoModel;
@@ -240,29 +366,39 @@ interface CreateMashupInstrumentalParams extends SunoBaseParams {
     persona_id?: string;
     persona_type?: PersonaType;
 }
+/**
+ * Params for blending exactly two audio tracks into a single new composition.
+ * Discriminated on `vocal_mode` the same way as {@link TextToMusicParams}.
+ */
 type CreateMashupParams = CreateMashupPromptParams | CreateMashupLyricsParams | CreateMashupInstrumentalParams;
+/** Initial response from task creation with the assigned task ID. */
 interface TaskCreateResponse {
     id: string;
     status?: string;
     [key: string]: unknown;
 }
+/** Metadata and URLs for a generated music track. */
 interface Audio {
     id: string;
     audio_url?: string;
+    /** Progressive streaming URL; available before the full file is ready. */
     stream_audio_url?: string;
     image_url?: string;
     lyrics?: string;
     model_name?: string;
     title?: string;
     tags?: string[];
+    /** Track duration in seconds. */
     duration?: number;
     [key: string]: unknown;
 }
+/** Metadata and URLs for a generated sound effect (distinct from music {@link Audio}). */
 interface SoundAudio {
     id: string;
     audio_url?: string;
     stream_audio_url?: string;
     image_url?: string;
+    /** The prompt that was used to generate this sound effect. */
     prompt?: string;
     model_name?: string;
     title?: string;
@@ -270,6 +406,7 @@ interface SoundAudio {
     duration?: number;
     [key: string]: unknown;
 }
+/** Base response for all Suno async tasks, carrying lifecycle status and generation progress. */
 interface AsyncTaskResponse {
     id: string;
     status: TaskStatus;
@@ -277,28 +414,36 @@ interface AsyncTaskResponse {
     error?: string;
     [key: string]: unknown;
 }
+/** Result of a text-to-music generation task. */
 interface TextToMusicResponse extends AsyncTaskResponse {
     audios?: Audio[];
 }
+/** Result of a music extension task. `original_task_id` references the source track. */
 interface ExtendMusicResponse extends AsyncTaskResponse {
     original_task_id?: string;
     audios?: Audio[];
 }
+/** Result of an artwork generation task containing cover image URLs. */
 interface GenerateArtworkResponse extends AsyncTaskResponse {
     covers?: Array<{
         url: string;
     }>;
 }
+/** Result of a cover audio task. */
 interface CoverAudioResponse extends AsyncTaskResponse {
     audios?: Audio[];
 }
+/** Result of adding an instrumental backing track. */
 interface AddInstrumentalResponse extends TextToMusicResponse {
 }
+/** Result of adding vocals to a track. */
 interface AddVocalsResponse extends TextToMusicResponse {
 }
+/** Result of a sound effect generation task (uses {@link SoundAudio} instead of {@link Audio}). */
 interface TextToSoundResponse extends AsyncTaskResponse {
     audios?: SoundAudio[];
 }
+/** URLs for each isolated instrument stem after separation. Only populated stems have URLs. */
 interface SeparatedAudio {
     vocal_url?: string;
     instrumental_url?: string;
@@ -315,80 +460,107 @@ interface SeparatedAudio {
     synth_url?: string;
     woodwinds_url?: string;
 }
+/** Result of a stem separation task. */
 interface SeparateAudioStemsResponse extends AsyncTaskResponse {
     separated_audios?: SeparatedAudio;
 }
+/** A single MIDI note event within an instrument track. */
 interface MidiNote {
+    /** MIDI pitch number (0-127). */
     pitch: number;
     start_time: number;
     end_time: number;
+    /** Note velocity (0-1 normalized). */
     velocity: number;
 }
+/** All notes for a single instrument extracted from a track. */
 interface MidiInstrument {
     name: string;
     notes: MidiNote[];
 }
+/** Result of a MIDI extraction task with per-instrument note data. */
 interface GenerateMidiResponse extends AsyncTaskResponse {
     instruments?: MidiInstrument[];
 }
+/** Result of a WAV conversion task. */
 interface ConvertAudioResponse extends AsyncTaskResponse {
+    /** Download URL for the converted WAV file. */
     wav_url?: string;
     original_task_id?: string;
 }
+/** Result of a music visualization task containing the generated video URL. */
 interface VisualizeMusicResponse extends AsyncTaskResponse {
     video_url?: string;
     original_task_id?: string;
 }
+/** Result of a lyrics generation task with sectioned lyrics. */
 interface GenerateLyricsResponse extends AsyncTaskResponse {
+    /** Generated lyrics, split by section (e.g. "Chorus", "Verse 1"). */
     lyrics?: Array<{
         title?: string;
         text: string;
     }>;
 }
+/** Word-level timing alignment for a single word in a track. */
 interface AlignedWord {
     word: string;
+    /** Whether alignment succeeded for this word. */
     success: boolean;
     start_time: number;
     end_time: number;
+    /** Alignment confidence score. */
     palign: number;
 }
+/** Synchronous response containing word-level timing data and waveform for a track. */
 interface GetTimestampedLyricsResponse {
     aligned_words?: AlignedWord[];
+    /** Waveform amplitude data for visualization. */
     waveform_data?: number[];
+    /** Character error rate of the lyrics alignment. */
     hoot_cer?: number;
     is_streamed?: boolean;
     [key: string]: unknown;
 }
+/** Result of a section replacement task. */
 interface ReplaceSectionResponse extends AsyncTaskResponse {
     track?: Audio;
 }
+/** A reusable style or voice persona, referenced by ID in generation params. */
 interface Persona {
     id: string;
     name: string;
     description: string;
     [key: string]: unknown;
 }
+/** Synchronous result of persona creation. */
 interface GeneratePersonaResponse {
     persona: Persona;
     error?: string;
     [key: string]: unknown;
 }
+/** Synchronous result of style tag generation. `style` contains the generated tags string. */
 interface BoostStyleResponse {
     style: string;
     error?: string;
     [key: string]: unknown;
 }
+/** Result of a mashup task. */
 interface CreateMashupResponse extends AsyncTaskResponse {
     audios?: Audio[];
 }
+/** Result of a voice-cloning validation phrase task. The user must re-record this phrase. */
 interface ValidationPhraseResponse extends AsyncTaskResponse {
     provider_status?: string;
+    /** The validation phrase text the user must read back for voice cloning. */
     validation_phrase?: string;
 }
+/** Result of a voice generation (training) task. `voice_id` is usable in subsequent generation params. */
 interface VoiceGenerationResponse extends AsyncTaskResponse {
     provider_status?: string;
+    /** Custom voice identifier, usable as persona in subsequent music generation. */
     voice_id?: string;
 }
+/** Synchronous result indicating whether a custom voice is ready for use. */
 interface CheckVoiceResponse {
     is_available?: boolean;
     error?: string;
@@ -464,168 +636,520 @@ type CompletedVoiceGenerationResponse = VoiceGenerationResponse & {
     voice_id: string;
 };
 
+/** Generates songs from a text prompt with configurable vocal mode, style, and persona. */
 declare class TextToMusic {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a text to music task and wait until complete.
+     * @param params Text to music parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed text to music response.
+     */
     run(params: TextToMusicParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToMusicResponse>;
+    /**
+     * Create a text to music task; returns immediately with a task id.
+     * @param params Text to music parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: TextToMusicParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a text to music task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current text to music task status.
+     */
     get(id: string, options?: RequestOptions): Promise<TextToMusicResponse>;
 }
 
+/** Continues an existing track from a specified timestamp, inheriting or overriding its settings. */
 declare class ExtendMusic {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create an extend music task and wait until complete.
+     * @param params Extend music parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed extend music response.
+     */
     run(params: ExtendMusicParams, options?: RequestOptions & PollingOptions): Promise<CompletedExtendMusicResponse>;
+    /**
+     * Create an extend music task; returns immediately with a task id.
+     * @param params Extend music parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: ExtendMusicParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of an extend music task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current extend music task status.
+     */
     get(id: string, options?: RequestOptions): Promise<ExtendMusicResponse>;
 }
 
+/** Creates cover artwork for an existing music task. */
 declare class GenerateArtwork {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a generate artwork task and wait until complete.
+     * @param params Generate artwork parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed generate artwork response.
+     */
     run(params: GenerateArtworkParams, options?: RequestOptions & PollingOptions): Promise<CompletedGenerateArtworkResponse>;
+    /**
+     * Create a generate artwork task; returns immediately with a task id.
+     * @param params Generate artwork parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: GenerateArtworkParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a generate artwork task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current generate artwork task status.
+     */
     get(id: string, options?: RequestOptions): Promise<GenerateArtworkResponse>;
 }
 
+/** Re-records vocals over an uploaded audio file with a new style or voice. */
 declare class CoverAudio {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a cover audio task and wait until complete.
+     * @param params Cover audio parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed cover audio response.
+     */
     run(params: CoverAudioParams, options?: RequestOptions & PollingOptions): Promise<CompletedCoverAudioResponse>;
+    /**
+     * Create a cover audio task; returns immediately with a task id.
+     * @param params Cover audio parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: CoverAudioParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a cover audio task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current cover audio task status.
+     */
     get(id: string, options?: RequestOptions): Promise<CoverAudioResponse>;
 }
 
+/** Generates and adds an instrumental backing track to uploaded audio. */
 declare class AddInstrumental {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create an add instrumental task and wait until complete.
+     * @param params Add instrumental parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed add instrumental response.
+     */
     run(params: AddInstrumentalParams, options?: RequestOptions & PollingOptions): Promise<CompletedAddInstrumentalResponse>;
+    /**
+     * Create an add instrumental task; returns immediately with a task id.
+     * @param params Add instrumental parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: AddInstrumentalParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of an add instrumental task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current add instrumental task status.
+     */
     get(id: string, options?: RequestOptions): Promise<AddInstrumentalResponse>;
 }
 
+/** Generates and adds vocals to an uploaded instrumental track. */
 declare class AddVocals {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create an add vocals task and wait until complete.
+     * @param params Add vocals parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed add vocals response.
+     */
     run(params: AddVocalsParams, options?: RequestOptions & PollingOptions): Promise<CompletedAddVocalsResponse>;
+    /**
+     * Create an add vocals task; returns immediately with a task id.
+     * @param params Add vocals parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: AddVocalsParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of an add vocals task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current add vocals task status.
+     */
     get(id: string, options?: RequestOptions): Promise<AddVocalsResponse>;
 }
 
+/** Splits a track into individual instrument stems (vocals, drums, bass, guitar, etc.). */
 declare class SeparateAudioStems {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a separate audio stems task and wait until complete.
+     * @param params Separate audio stems parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed separate audio stems response.
+     */
     run(params: SeparateAudioStemsParams, options?: RequestOptions & PollingOptions): Promise<CompletedSeparateAudioStemsResponse>;
+    /**
+     * Create a separate audio stems task; returns immediately with a task id.
+     * @param params Separate audio stems parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: SeparateAudioStemsParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a separate audio stems task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current separate audio stems task status.
+     */
     get(id: string, options?: RequestOptions): Promise<SeparateAudioStemsResponse>;
 }
 
+/** Extracts per-instrument MIDI note data from a generated track. */
 declare class GenerateMidi {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a generate midi task and wait until complete.
+     * @param params Generate midi parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed generate midi response.
+     */
     run(params: GenerateMidiParams, options?: RequestOptions & PollingOptions): Promise<CompletedGenerateMidiResponse>;
+    /**
+     * Create a generate midi task; returns immediately with a task id.
+     * @param params Generate midi parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: GenerateMidiParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a generate midi task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current generate midi task status.
+     */
     get(id: string, options?: RequestOptions): Promise<GenerateMidiResponse>;
 }
 
+/** Converts a generated track to WAV format. */
 declare class ConvertAudio {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a convert audio task and wait until complete.
+     * @param params Convert audio parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed convert audio response.
+     */
     run(params: ConvertAudioParams, options?: RequestOptions & PollingOptions): Promise<CompletedConvertAudioResponse>;
+    /**
+     * Create a convert audio task; returns immediately with a task id.
+     * @param params Convert audio parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: ConvertAudioParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a convert audio task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current convert audio task status.
+     */
     get(id: string, options?: RequestOptions): Promise<ConvertAudioResponse>;
 }
 
+/** Generates a music visualization video from an existing track. */
 declare class VisualizeMusic {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a visualize music task and wait until complete.
+     * @param params Visualize music parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed visualize music response.
+     */
     run(params: VisualizeMusicParams, options?: RequestOptions & PollingOptions): Promise<CompletedVisualizeMusicResponse>;
+    /**
+     * Create a visualize music task; returns immediately with a task id.
+     * @param params Visualize music parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: VisualizeMusicParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a visualize music task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current visualize music task status.
+     */
     get(id: string, options?: RequestOptions): Promise<VisualizeMusicResponse>;
 }
 
+/** Produces AI-generated lyrics from a text prompt. */
 declare class GenerateLyrics {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a generate lyrics task and wait until complete.
+     * @param params Generate lyrics parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed generate lyrics response.
+     */
     run(params: GenerateLyricsParams, options?: RequestOptions & PollingOptions): Promise<CompletedGenerateLyricsResponse>;
+    /**
+     * Create a generate lyrics task; returns immediately with a task id.
+     * @param params Generate lyrics parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: GenerateLyricsParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a generate lyrics task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current generate lyrics task status.
+     */
     get(id: string, options?: RequestOptions): Promise<GenerateLyricsResponse>;
 }
 
+/** Retrieves word-level timing alignment for a track. Synchronous (run only, no create/get polling). */
 declare class GetTimestampedLyrics {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Run get timestamped lyrics (synchronous).
+     * @param params Get timestamped lyrics parameters.
+     * @param options Per-request overrides.
+     * @returns The get timestamped lyrics response.
+     */
     run(params: GetTimestampedLyricsParams, options?: RequestOptions): Promise<GetTimestampedLyricsResponse>;
 }
 
+/** Re-generates a time range within an existing track with new lyrics and style. */
 declare class ReplaceSection {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a replace section task and wait until complete.
+     * @param params Replace section parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed replace section response.
+     */
     run(params: ReplaceSectionParams, options?: RequestOptions & PollingOptions): Promise<CompletedReplaceSectionResponse>;
+    /**
+     * Create a replace section task; returns immediately with a task id.
+     * @param params Replace section parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: ReplaceSectionParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a replace section task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current replace section task status.
+     */
     get(id: string, options?: RequestOptions): Promise<ReplaceSectionResponse>;
 }
 
+/** Blends two audio tracks into a single new composition. */
 declare class CreateMashup {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a create mashup task and wait until complete.
+     * @param params Create mashup parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed create mashup response.
+     */
     run(params: CreateMashupParams, options?: RequestOptions & PollingOptions): Promise<CompletedCreateMashupResponse>;
+    /**
+     * Create a create mashup task; returns immediately with a task id.
+     * @param params Create mashup parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: CreateMashupParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a create mashup task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current create mashup task status.
+     */
     get(id: string, options?: RequestOptions): Promise<CreateMashupResponse>;
 }
 
+/** Generates sound effects (not music) from a text description with optional looping and BPM control. */
 declare class TextToSound {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a text to sound task and wait until complete.
+     * @param params Text to sound parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed text to sound response.
+     */
     run(params: TextToSoundParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToSoundResponse>;
+    /**
+     * Create a text to sound task; returns immediately with a task id.
+     * @param params Text to sound parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: TextToSoundParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a text to sound task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current text to sound task status.
+     */
     get(id: string, options?: RequestOptions): Promise<TextToSoundResponse>;
 }
 
+/** Creates a reusable style or voice persona from an existing track's vocals. Synchronous (run only). */
 declare class GeneratePersona {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Run generate persona (synchronous).
+     * @param params Generate persona parameters.
+     * @param options Per-request overrides.
+     * @returns The generate persona response.
+     */
     run(params: GeneratePersonaParams, options?: RequestOptions): Promise<GeneratePersonaResponse>;
 }
 
+/** Generates style/genre tags from a text description for use in style fields. Synchronous (run only). */
 declare class BoostStyle {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Run boost style (synchronous).
+     * @param params Boost style parameters.
+     * @param options Per-request overrides.
+     * @returns The boost style response.
+     */
     run(params: BoostStyleParams, options?: RequestOptions): Promise<BoostStyleResponse>;
 }
 
+/** Step 1 of voice cloning: extracts a validation phrase from a voice recording for the user to re-record. */
 declare class VoiceToValidationPhrase {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a voice to validation phrase task and wait until complete.
+     * @param params Voice to validation phrase parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed voice to validation phrase response.
+     */
     run(params: VoiceToValidationPhraseParams, options?: RequestOptions & PollingOptions): Promise<CompletedValidationPhraseResponse>;
+    /**
+     * Create a voice to validation phrase task; returns immediately with a task id.
+     * @param params Voice to validation phrase parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: VoiceToValidationPhraseParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a voice to validation phrase task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current voice to validation phrase task status.
+     */
     get(id: string, options?: RequestOptions): Promise<ValidationPhraseResponse>;
 }
 
+/** Step 2 (optional) of voice cloning: requests a new, easier validation phrase. */
 declare class RegenerateValidationPhrase {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a regenerate validation phrase task and wait until complete.
+     * @param params Regenerate validation phrase parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed regenerate validation phrase response.
+     */
     run(params: RegenerateValidationPhraseParams, options?: RequestOptions & PollingOptions): Promise<CompletedValidationPhraseResponse>;
+    /**
+     * Create a regenerate validation phrase task; returns immediately with a task id.
+     * @param params Regenerate validation phrase parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: RegenerateValidationPhraseParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a regenerate validation phrase task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current regenerate validation phrase task status.
+     */
     get(id: string, options?: RequestOptions): Promise<ValidationPhraseResponse>;
 }
 
+/** Step 3 of voice cloning: trains a custom voice from the user's recording of the validation phrase. */
 declare class GenerateVoice {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Create a generate voice task and wait until complete.
+     * @param params Generate voice parameters.
+     * @param options Per-request and polling overrides.
+     * @returns The completed generate voice response.
+     */
     run(params: GenerateVoiceParams, options?: RequestOptions & PollingOptions): Promise<CompletedVoiceGenerationResponse>;
+    /**
+     * Create a generate voice task; returns immediately with a task id.
+     * @param params Generate voice parameters.
+     * @param options Per-request overrides.
+     * @returns The task creation result.
+     */
     create(params: GenerateVoiceParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    /**
+     * Fetch the current status of a generate voice task.
+     * @param id The task id.
+     * @param options Per-request overrides.
+     * @returns The current generate voice task status.
+     */
     get(id: string, options?: RequestOptions): Promise<VoiceGenerationResponse>;
 }
 
+/** Step 4 of voice cloning: checks whether a custom voice is ready for use. Synchronous (run only). */
 declare class CheckVoice {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Run check voice (synchronous).
+     * @param params Check voice parameters.
+     * @param options Per-request overrides.
+     * @returns The check voice response.
+     */
     run(params: CheckVoiceParams, options?: RequestOptions): Promise<CheckVoiceResponse>;
 }
 
 /**
- * Suno API client.
+ * Suno music platform client covering song generation, extension, covers, stems,
+ * MIDI, lyrics, mashups, sound effects, visualization, personas, and voice cloning.
  *
  * @example
  * ```typescript
@@ -640,27 +1164,48 @@ declare class CheckVoice {
  * });
  * ```
  */
-declare class SunoClient {
+declare class SunoClient extends BaseClient {
+    /** Generates songs from a text prompt with configurable vocal mode, style, and persona. */
     readonly textToMusic: TextToMusic;
+    /** Continues an existing track from a specified timestamp, inheriting or overriding its settings. */
     readonly extendMusic: ExtendMusic;
+    /** Creates cover artwork for an existing music task. */
     readonly generateArtwork: GenerateArtwork;
+    /** Re-records vocals over an uploaded audio file with a new style or voice. */
     readonly coverAudio: CoverAudio;
+    /** Generates and adds an instrumental backing track to uploaded audio. */
     readonly addInstrumental: AddInstrumental;
+    /** Generates and adds vocals to an uploaded instrumental track. */
     readonly addVocals: AddVocals;
+    /** Splits a track into individual instrument stems (vocals, drums, bass, guitar, etc.). */
     readonly separateAudioStems: SeparateAudioStems;
+    /** Extracts per-instrument MIDI note data from a generated track. */
     readonly generateMidi: GenerateMidi;
+    /** Converts a generated track to WAV format. */
     readonly convertAudio: ConvertAudio;
+    /** Generates a music visualization video from an existing track. */
     readonly visualizeMusic: VisualizeMusic;
+    /** Produces AI-generated lyrics from a text prompt. */
     readonly generateLyrics: GenerateLyrics;
+    /** Retrieves word-level timing alignment for a track. Synchronous (run only). */
     readonly getTimestampedLyrics: GetTimestampedLyrics;
+    /** Re-generates a time range within an existing track with new lyrics and style. */
     readonly replaceSection: ReplaceSection;
+    /** Blends two audio tracks into a single new composition. */
     readonly createMashup: CreateMashup;
+    /** Generates sound effects (not music) from a text description with optional looping and BPM control. */
     readonly textToSound: TextToSound;
+    /** Creates a reusable style or voice persona from a track's vocals. Synchronous (run only). */
     readonly generatePersona: GeneratePersona;
+    /** Generates style/genre tags from a text description for use in style fields. Synchronous (run only). */
     readonly boostStyle: BoostStyle;
+    /** Step 1 of voice cloning: extracts a validation phrase from a voice recording. */
     readonly voiceToValidationPhrase: VoiceToValidationPhrase;
+    /** Step 2 (optional) of voice cloning: requests a new, easier validation phrase. */
     readonly regenerateValidationPhrase: RegenerateValidationPhrase;
+    /** Step 3 of voice cloning: trains a custom voice from the user's recording of the validation phrase. */
     readonly generateVoice: GenerateVoice;
+    /** Step 4 of voice cloning: checks whether a custom voice is ready for use. Synchronous (run only). */
     readonly checkVoice: CheckVoice;
     constructor(options?: ClientOptions);
 }