suno-easy 0.1.0__py3-none-any.whl

suno_easy/__init__.py

@@ -0,0 +1,25 @@
+from .client import SunoClient
+from .models import (
+    Song,
+    Lyrics,
+    CoverImage,
+    SeparatedStems,
+    MIDIData,
+    MIDINote,
+    MIDIInstrument,
+)
+from .exceptions import SunoError, TaskFailed, SunoAPIError
+
+__all__ = [
+    "SunoClient",
+    "Song",
+    "Lyrics",
+    "CoverImage",
+    "SeparatedStems",
+    "MIDIData",
+    "MIDINote",
+    "MIDIInstrument",
+    "SunoError",
+    "TaskFailed",
+    "SunoAPIError",
+]

suno_easy/audio.py

@@ -0,0 +1,380 @@
+from .models import Song, CoverImage, SeparatedStems, MIDIData
+
+
+class AudioResource:
+    """Resource manager for audio processing (vocal separation, MIDI, covers, uploading)."""
+
+    def __init__(self, client):
+        """Initializes the AudioResource with a client reference.
+
+        Args:
+            client (SunoClient): The parent client instance.
+        """
+        self.client = client
+
+    def cover(
+        self,
+        upload_url: str,
+        style: str,
+        title: str,
+        prompt: str = "",
+        model: str = "V4_5ALL",
+        custom_mode: bool = True,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Uploads an audio track and transforms it into a new style (Cover).
+
+        Args:
+            upload_url (str): Public URL of the audio file to cover.
+            style (str): Musical style for the cover. Required if custom_mode is True. Defaults to "".
+            title (str): Title for the cover track. Required if custom_mode is True. Defaults to "".
+            prompt (str): Optional prompt describing changes/vocals. Defaults to "".
+            model (str): Model version. Defaults to "V4_5ALL".
+            custom_mode (bool): Use custom mode. Defaults to True.
+            callback_url (str, optional): Webhook URL for completion notification.
+            wait (bool): If True, poll and wait for task completion. Defaults to True.
+            timeout (int): Max time in seconds to wait for task completion. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of covered Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "uploadUrl": upload_url,
+            "style": style,
+            "title": title,
+            "prompt": prompt,
+            "model": model,
+            "customMode": custom_mode
+        }
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate/upload-cover", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)
+
+    def extend(
+        self,
+        upload_url: str,
+        continue_at: int,
+        prompt: str,
+        style: str = "",
+        title: str = "",
+        model: str = "V4_5ALL",
+        default_param_flag: bool = True,
+        persona_id: str | None = None,
+        persona_model: str | None = None,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Uploads an audio file and extends it.
+
+        Args:
+            upload_url (str): Public URL of the audio file to extend.
+            continue_at (int): Time in seconds in the original track where extension starts.
+            prompt (str): Text prompt describing the continuation.
+            style (str): Musical style for the continuation. Defaults to "".
+            title (str): Title for the extended track. Defaults to "".
+            model (str): Model version. Defaults to "V4_5ALL".
+            default_param_flag (bool): If True, uses custom parameters. Defaults to True.
+            persona_id (str, optional): Optional Persona ID.
+            persona_model (str, optional): Persona model type ("style_persona" or "voice_persona").
+            callback_url (str, optional): Webhook URL for callback notification.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of extended Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "uploadUrl": upload_url,
+            "continueAt": continue_at,
+            "prompt": prompt,
+            "style": style,
+            "title": title,
+            "model": model,
+            "defaultParamFlag": default_param_flag
+        }
+        if persona_id:
+            payload["personaId"] = persona_id
+        if persona_model:
+            payload["personaModel"] = persona_model
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate/upload-extend", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)
+
+    def generate_cover_image(
+        self,
+        task_id: str,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | CoverImage:
+        """Generates a personalized cover image for a music task.
+
+        Args:
+            task_id (str): Task ID of the original music generation.
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | CoverImage: A CoverImage object if wait is True, otherwise the taskId as a string.
+        """
+        payload = {"taskId": task_id}
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/suno/cover/generate", payload)
+        new_task_id = res["data"]["taskId"]
+
+        if not wait:
+            return new_task_id
+
+        task_data = self.client.wait_task(new_task_id, endpoint="/api/v1/suno/cover/record-info", timeout=timeout)
+        return CoverImage.from_task_data(task_data)
+
+    def get_cover_image(self, task_id: str) -> CoverImage:
+        """Retrieves the cover image details for a cover task.
+
+        Args:
+            task_id (str): The ID of the cover task.
+
+        Returns:
+            CoverImage: The CoverImage object containing generated image URLs.
+        """
+        task_data = self.client.get_task_info(task_id, endpoint="/api/v1/suno/cover/record-info")
+        return CoverImage.from_task_data(task_data)
+
+    def separate_vocals(
+        self,
+        task_id: str,
+        mode: str = "separate_vocal",
+        audio_id: str | None = None,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | SeparatedStems:
+        """Separates vocals from instruments.
+
+        Args:
+            task_id (str): Task ID of the original music generation.
+            mode (str): Separation mode: "separate_vocal" (2 stems) or "split_stem" (up to 12 stems).
+                Defaults to "separate_vocal".
+            audio_id (str, optional): Optional specific audio variation ID to process.
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | SeparatedStems: A SeparatedStems object if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "taskId": task_id,
+            "type": mode
+        }
+        if audio_id:
+            payload["audioId"] = audio_id
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/vocal-removal/generate", payload)
+        new_task_id = res["data"]["taskId"]
+
+        if not wait:
+            return new_task_id
+
+        task_data = self.client.wait_task(new_task_id, endpoint="/api/v1/vocal-removal/record-info", timeout=timeout)
+        return SeparatedStems.from_task_data(task_data)
+
+    def get_separated_stems(self, task_id: str) -> SeparatedStems:
+        """Retrieves stem separation results.
+
+        Args:
+            task_id (str): The ID of the vocal separation task.
+
+        Returns:
+            SeparatedStems: The SeparatedStems object containing urls of processed stems.
+        """
+        task_data = self.client.get_task_info(task_id, endpoint="/api/v1/vocal-removal/record-info")
+        return SeparatedStems.from_task_data(task_data)
+
+    def generate_midi(
+        self,
+        task_id: str,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | MIDIData:
+        """Converts separated audio tracks into MIDI format.
+
+        Args:
+            task_id (str): Task ID of the vocal removal task.
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | MIDIData: A MIDIData object if wait is True, otherwise the taskId as a string.
+        """
+        payload = {"taskId": task_id}
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/midi/generate", payload)
+        new_task_id = res["data"]["taskId"]
+
+        if not wait:
+            return new_task_id
+
+        task_data = self.client.wait_task(new_task_id, endpoint="/api/v1/midi/record-info", timeout=timeout)
+        return MIDIData.from_task_data(task_data)
+
+    def get_midi(self, task_id: str) -> MIDIData:
+        """Retrieves generated MIDI note/instrument data.
+
+        Args:
+            task_id (str): The ID of the MIDI generation task.
+
+        Returns:
+            MIDIData: The MIDIData object containing instrument and note details.
+        """
+        task_data = self.client.get_task_info(task_id, endpoint="/api/v1/midi/record-info")
+        return MIDIData.from_task_data(task_data)
+
+    def add_vocals(
+        self,
+        upload_url: str,
+        prompt: str,
+        style: str = "",
+        title: str = "",
+        negative_tags: str | None = None,
+        vocal_gender: str | None = None,
+        style_weight: float | None = None,
+        weirdness_constraint: float | None = None,
+        audio_weight: float | None = None,
+        model: str | None = None,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Adds vocals to an instrumental track.
+
+        Args:
+            upload_url (str): Public URL of the instrumental audio track.
+            prompt (str): Text prompt describing the vocal lyrics/style.
+            style (str): Musical style. Defaults to "".
+            title (str): Title for the track. Defaults to "".
+            negative_tags (str, optional): Characteristics to exclude.
+            vocal_gender (str, optional): Preferred vocal gender.
+            style_weight (float, optional): Weight parameter.
+            weirdness_constraint (float, optional): Tuning parameter.
+            audio_weight (float, optional): Tuning parameter.
+            model (str, optional): Model version.
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "uploadUrl": upload_url,
+            "prompt": prompt,
+            "style": style,
+            "title": title
+        }
+        if negative_tags is not None:
+            payload["negativeTags"] = negative_tags
+        if vocal_gender is not None:
+            payload["vocalGender"] = vocal_gender
+        if style_weight is not None:
+            payload["styleWeight"] = style_weight
+        if weirdness_constraint is not None:
+            payload["weirdnessConstraint"] = weirdness_constraint
+        if audio_weight is not None:
+            payload["audioWeight"] = audio_weight
+        if model is not None:
+            payload["model"] = model
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate/add-vocals", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)
+
+    def add_instrumental(
+        self,
+        upload_url: str,
+        title: str,
+        tags: str = "",
+        negative_tags: str | None = None,
+        weirdness_constraint: float | None = None,
+        audio_weight: float | None = None,
+        model: str | None = None,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Adds instrumental backing to an audio track (e.g. vocals).
+
+        Args:
+            upload_url (str): Public URL of the vocal/melody track.
+            title (str): Title for the track.
+            tags (str): Desired style and characteristics for the accompaniment. Defaults to "".
+            negative_tags (str, optional): Styles or instruments to exclude.
+            weirdness_constraint (float, optional): Tuning parameter.
+            audio_weight (float, optional): Tuning parameter.
+            model (str, optional): Model version.
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "uploadUrl": upload_url,
+            "title": title,
+            "tags": tags
+        }
+        if negative_tags is not None:
+            payload["negativeTags"] = negative_tags
+        if weirdness_constraint is not None:
+            payload["weirdnessConstraint"] = weirdness_constraint
+        if audio_weight is not None:
+            payload["audioWeight"] = audio_weight
+        if model is not None:
+            payload["model"] = model
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate/add-instrumental", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)

suno_easy/client.py

@@ -0,0 +1,147 @@
+import time
+import requests
+
+from .exceptions import TaskFailed, SunoAPIError
+from .music import MusicResource
+from .lyrics import LyricsResource
+from .persona import PersonaResource
+from .audio import AudioResource
+
+
+class SunoClient:
+    """Main client to interact with the Suno API.
+
+    This client acts as the central orchestrator and HTTP session manager,
+    exposing sub-resources to interact with different domain endpoints.
+
+    Attributes:
+        music (MusicResource): Endpoints related to music generation and extension.
+        lyrics (LyricsResource): Endpoints related to lyrics generation.
+        persona (PersonaResource): Endpoints related to persona creation.
+        audio (AudioResource): Endpoints related to audio processing (separations, MIDI, covers).
+    """
+
+    BASE_URL = "https://api.sunoapi.org"
+
+    def __init__(self, api_key: str):
+        """Initializes the SunoClient with a bearer token.
+
+        Args:
+            api_key (str): The API key for authorization.
+        """
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        })
+
+        # Composition: Initialize sub-resources
+        self.music = MusicResource(self)
+        self.lyrics = LyricsResource(self)
+        self.persona = PersonaResource(self)
+        self.audio = AudioResource(self)
+
+    def post(self, url: str, json: dict) -> dict:
+        """Sends a POST request to the API.
+
+        Args:
+            url (str): The endpoint path.
+            json (dict): The JSON payload.
+
+        Returns:
+            dict: The JSON response.
+
+        Raises:
+            SunoAPIError: If the API returns an HTTP error.
+        """
+        r = self.session.post(self.BASE_URL + url, json=json)
+        if not r.ok:
+            raise SunoAPIError(r.text, status_code=r.status_code, response_text=r.text)
+        return r.json()
+
+    def get(self, url: str, params: dict | None = None) -> dict:
+        """Sends a GET request to the API.
+
+        Args:
+            url (str): The endpoint path.
+            params (dict, optional): The query parameters.
+
+        Returns:
+            dict: The JSON response.
+
+        Raises:
+            SunoAPIError: If the API returns an HTTP error.
+        """
+        r = self.session.get(self.BASE_URL + url, params=params)
+        if not r.ok:
+            raise SunoAPIError(r.text, status_code=r.status_code, response_text=r.text)
+        return r.json()
+
+    def get_task_info(self, task_id: str, endpoint: str = "/api/v1/generate/record-info") -> dict:
+        """Fetches the raw response data of a task.
+
+        Args:
+            task_id (str): The ID of the task to retrieve.
+            endpoint (str): The API endpoint path. Defaults to "/api/v1/generate/record-info".
+
+        Returns:
+            dict: The raw data dictionary returned by the API.
+        """
+        return self.get(endpoint, params={"taskId": task_id})["data"]
+
+    def wait_task(
+        self,
+        task_id: str,
+        endpoint: str = "/api/v1/generate/record-info",
+        timeout: int = 300,
+        poll_interval: int = 3
+    ) -> dict:
+        """Polls the API and waits for a task to complete.
+
+        Args:
+            task_id (str): The ID of the task to poll.
+            endpoint (str): The API endpoint path. Defaults to "/api/v1/generate/record-info".
+            timeout (int): Maximum wait time in seconds. Defaults to 300.
+            poll_interval (int): Time in seconds between polling requests. Defaults to 3.
+
+        Returns:
+            dict: The completed task raw response.
+
+        Raises:
+            TimeoutError: If the task does not finish within the timeout period.
+            TaskFailed: If the task fails or encounters an error.
+        """
+        start = time.time()
+
+        while True:
+            if time.time() - start > timeout:
+                raise TimeoutError(f"Task {task_id} timed out after {timeout} seconds")
+
+            res = self.get_task_info(task_id, endpoint)
+            status = res.get("status")
+            success_flag = res.get("successFlag")
+            error_msg = res.get("errorMessage") or res.get("errorMsg")
+
+            if (
+                status == "FAILED"
+                or success_flag == "FAILED"
+                or (isinstance(success_flag, int) and success_flag < 0)
+                or (status is not None and "FAIL" in str(status).upper())
+                or (success_flag is not None and "FAIL" in str(success_flag).upper())
+                or error_msg
+            ):
+                if error_msg or status == "FAILED" or success_flag == "FAILED" or (isinstance(success_flag, int) and success_flag < 0):
+                    raise TaskFailed(res)
+
+            is_complete = False
+            if status == "SUCCESS" or success_flag == "SUCCESS":
+                is_complete = True
+            elif success_flag == 1 or success_flag == "1":
+                is_complete = True
+            elif "midiData" in res and isinstance(res["midiData"], dict) and res["midiData"].get("state") == "complete":
+                is_complete = True
+
+            if is_complete:
+                return res
+
+            time.sleep(poll_interval)

suno_easy/exceptions.py

@@ -0,0 +1,19 @@
+class SunoError(Exception):
+    """Base exception for all Suno Easy library errors."""
+    pass
+
+
+class TaskFailed(SunoError):
+    """Raised when a task status is FAILED or has error messages."""
+    def __init__(self, task_info: dict):
+        self.task_info = task_info
+        super().__init__(f"Task failed: {task_info.get('errorMessage') or task_info.get('errorMsg') or task_info}")
+
+
+class SunoAPIError(SunoError):
+    """Raised when the Suno API returns an HTTP error code."""
+    def __init__(self, message: str, status_code: int = None, response_text: str = None):
+        self.message = message
+        self.status_code = status_code
+        self.response_text = response_text
+        super().__init__(f"Suno API error ({status_code}): {message}")

suno_easy/lyrics.py

@@ -0,0 +1,56 @@
+from .models import Lyrics
+
+
+class LyricsResource:
+    """Resource manager for lyrics generation."""
+
+    def __init__(self, client):
+        """Initializes the LyricsResource with a client reference.
+
+        Args:
+            client (SunoClient): The parent client instance.
+        """
+        self.client = client
+
+    def generate(
+        self,
+        prompt: str,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 120
+    ) -> str | list[Lyrics]:
+        """Generates lyrics based on a text prompt.
+
+        Args:
+            prompt (str): Text prompt describing the desired lyrics.
+            callback_url (str, optional): Webhook URL for callback notification.
+            wait (bool): If True, poll and wait for task completion. Defaults to True.
+            timeout (int): Max time in seconds to wait for task completion. Defaults to 120.
+
+        Returns:
+            str | list[Lyrics]: A list of generated Lyrics objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {"prompt": prompt}
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/lyrics", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/lyrics/record-info", timeout=timeout)
+        return Lyrics.from_task_data(task_data)
+
+    def get(self, task_id: str) -> list[Lyrics]:
+        """Retrieves the lyrics generated by a task.
+
+        Args:
+            task_id (str): The ID of the lyrics task.
+
+        Returns:
+            list[Lyrics]: A list of generated Lyrics objects.
+        """
+        task_data = self.client.get_task_info(task_id, endpoint="/api/v1/lyrics/record-info")
+        return Lyrics.from_task_data(task_data)

suno_easy/models.py

@@ -0,0 +1,209 @@
+from dataclasses import dataclass
+import requests
+
+
+@dataclass
+class Song:
+    id: str
+    title: str
+    audio_url: str | None = None
+    stream_url: str | None = None
+    image_url: str | None = None
+    prompt: str | None = None
+    tags: str | None = None
+    duration: float | None = None
+    model_name: str | None = None
+    create_time: str | None = None
+
+    def download(self, path: str):
+        if not self.audio_url:
+            raise ValueError("No audio_url available")
+
+        r = requests.get(self.audio_url, stream=True)
+        r.raise_for_status()
+
+        with open(path, "wb") as f:
+            for chunk in r.iter_content(1024 * 1024):
+                f.write(chunk)
+
+    def download_image(self, path: str):
+        if not self.image_url:
+            raise ValueError("No image_url available")
+
+        r = requests.get(self.image_url)
+        r.raise_for_status()
+
+        with open(path, "wb") as f:
+            f.write(r.content)
+
+    @classmethod
+    def from_task_data(cls, task_data: dict) -> list["Song"]:
+        response_data = task_data.get("response", {})
+        songs_list = []
+        if isinstance(response_data, dict):
+            songs_list = response_data.get("sunoData") or response_data.get("songs") or []
+        if not songs_list:
+            songs_list = task_data.get("songs") or task_data.get("sunoData") or []
+        
+        return [
+            cls(
+                id=song["id"],
+                title=song.get("title", ""),
+                audio_url=song.get("audioUrl"),
+                stream_url=song.get("streamAudioUrl"),
+                image_url=song.get("imageUrl"),
+                prompt=song.get("prompt"),
+                tags=song.get("tags"),
+                duration=song.get("duration"),
+                model_name=song.get("modelName"),
+                create_time=song.get("createTime")
+            )
+            for song in songs_list
+        ]
+
+
+@dataclass
+class Lyrics:
+    text: str
+    title: str
+    status: str | None = None
+    error_message: str | None = None
+
+    @classmethod
+    def from_task_data(cls, task_data: dict) -> list["Lyrics"]:
+        response_data = task_data.get("response", {})
+        lyrics_list = []
+        if isinstance(response_data, dict):
+            lyrics_list = response_data.get("data") or []
+        if not lyrics_list:
+            lyrics_list = task_data.get("data") or []
+        
+        return [
+            cls(
+                text=lyric.get("text", ""),
+                title=lyric.get("title", ""),
+                status=lyric.get("status"),
+                error_message=lyric.get("errorMessage")
+            )
+            for lyric in lyrics_list
+        ]
+
+
+@dataclass
+class CoverImage:
+    images: list[str]
+
+    @classmethod
+    def from_task_data(cls, task_data: dict) -> "CoverImage":
+        response_data = task_data.get("response", {})
+        images = []
+        if isinstance(response_data, dict):
+            images = response_data.get("images") or []
+        if not images:
+            images = task_data.get("images") or []
+        return cls(images=images)
+
+
+@dataclass
+class SeparatedStems:
+    vocal_url: str | None = None
+    instrumental_url: str | None = None
+    backing_vocals_url: str | None = None
+    drums_url: str | None = None
+    bass_url: str | None = None
+    guitar_url: str | None = None
+    keyboard_url: str | None = None
+    percussion_url: str | None = None
+    strings_url: str | None = None
+    synth_url: str | None = None
+    fx_url: str | None = None
+    brass_url: str | None = None
+    woodwinds_url: str | None = None
+
+    def download_vocal(self, path: str):
+        if not self.vocal_url:
+            raise ValueError("No vocal_url available")
+        self._download_file(self.vocal_url, path)
+
+    def download_instrumental(self, path: str):
+        if not self.instrumental_url:
+            raise ValueError("No instrumental_url available")
+        self._download_file(self.instrumental_url, path)
+
+    def _download_file(self, url: str, path: str):
+        r = requests.get(url, stream=True)
+        r.raise_for_status()
+        with open(path, "wb") as f:
+            for chunk in r.iter_content(1024 * 1024):
+                f.write(chunk)
+
+    @classmethod
+    def from_task_data(cls, task_data: dict) -> "SeparatedStems":
+        response_data = task_data.get("response", {})
+        if not isinstance(response_data, dict):
+            response_data = {}
+        src = response_data if response_data else task_data
+        return cls(
+            vocal_url=src.get("vocalUrl"),
+            instrumental_url=src.get("instrumentalUrl"),
+            backing_vocals_url=src.get("backingVocalsUrl"),
+            drums_url=src.get("drumsUrl"),
+            bass_url=src.get("bassUrl"),
+            guitar_url=src.get("guitarUrl"),
+            keyboard_url=src.get("keyboardUrl"),
+            percussion_url=src.get("percussionUrl"),
+            strings_url=src.get("stringsUrl"),
+            synth_url=src.get("synthUrl"),
+            fx_url=src.get("fxUrl"),
+            brass_url=src.get("brassUrl"),
+            woodwinds_url=src.get("woodwindsUrl")
+        )
+
+
+@dataclass
+class MIDINote:
+    pitch: int
+    start: float
+    end: float
+    velocity: float
+
+
+@dataclass
+class MIDIInstrument:
+    name: str
+    notes: list[MIDINote]
+
+
+@dataclass
+class MIDIData:
+    state: str
+    instruments: list[MIDIInstrument]
+
+    @classmethod
+    def from_task_data(cls, task_data: dict) -> "MIDIData":
+        midi_data = task_data.get("midiData", {})
+        if not isinstance(midi_data, dict):
+            midi_data = {}
+        
+        instruments_list = []
+        for inst in midi_data.get("instruments", []):
+            notes = [
+                MIDINote(
+                    pitch=note.get("pitch", 0),
+                    start=note.get("start", 0.0),
+                    end=note.get("end", 0.0),
+                    velocity=note.get("velocity", 0.0)
+                )
+                for note in inst.get("notes", [])
+            ]
+            instruments_list.append(
+                MIDIInstrument(
+                    name=inst.get("name", ""),
+                    notes=notes
+                )
+            )
+        
+        return cls(
+            state=midi_data.get("state", ""),
+            instruments=instruments_list
+        )

suno_easy/music.py

@@ -0,0 +1,182 @@
+from .models import Song
+
+
+class MusicResource:
+    """Resource manager for music generation, extension, and remastering."""
+
+    def __init__(self, client):
+        """Initializes the MusicResource with a client reference.
+
+        Args:
+            client (SunoClient): The parent client instance.
+        """
+        self.client = client
+
+    def generate(
+        self,
+        prompt: str,
+        style: str = "",
+        title: str = "",
+        model: str = "V4_5ALL",
+        instrumental: bool = False,
+        custom_mode: bool = True,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Generates music based on a prompt.
+
+        Args:
+            prompt (str): Text prompt describing the music.
+            style (str): Musical style. Required if custom_mode is True. Defaults to "".
+            title (str): Title of the generated music. Required if custom_mode is True. Defaults to "".
+            model (str): Model version to use. Defaults to "V4_5ALL".
+            instrumental (bool): Generate instrumental music without vocals. Defaults to False.
+            custom_mode (bool): Use custom mode. Defaults to True.
+            callback_url (str, optional): Webhook URL for callback notification.
+            wait (bool): If True, poll and wait for task completion. Defaults to True.
+            timeout (int): Max time in seconds to wait for task completion. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of generated Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "customMode": custom_mode,
+            "prompt": prompt,
+            "style": style,
+            "title": title,
+            "instrumental": instrumental,
+            "model": model
+        }
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)
+
+    def extend(
+        self,
+        audio_id: str,
+        continue_at: int,
+        prompt: str,
+        style: str = "",
+        title: str = "",
+        model: str = "V4_5ALL",
+        default_param_flag: bool = True,
+        persona_id: str | None = None,
+        persona_model: str | None = None,
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Extends an existing audio track.
+
+        Args:
+            audio_id (str): The ID of the original music track to extend.
+            continue_at (int): Time in seconds in the original track where extension starts.
+            prompt (str): Text prompt describing the continuation of the music.
+            style (str): Musical style for the continuation. Defaults to "".
+            title (str): Title for the extended track. Defaults to "".
+            model (str): Model version (should match source track). Defaults to "V4_5ALL".
+            default_param_flag (bool): If True, uses custom parameters. Defaults to True.
+            persona_id (str, optional): Optional Persona ID.
+            persona_model (str, optional): Persona model type ("style_persona" or "voice_persona").
+            callback_url (str, optional): Webhook URL for callback notification.
+            wait (bool): If True, poll and wait for task completion. Defaults to True.
+            timeout (int): Max time in seconds to wait for task completion. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of extended Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "audioId": audio_id,
+            "continueAt": continue_at,
+            "prompt": prompt,
+            "style": style,
+            "title": title,
+            "model": model,
+            "defaultParamFlag": default_param_flag
+        }
+        if persona_id:
+            payload["personaId"] = persona_id
+        if persona_model:
+            payload["personaModel"] = persona_model
+        if callback_url:
+            payload["callBackUrl"] = callback_url
+
+        res = self.client.post("/api/v1/generate/extend", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)
+
+    def generate_instrumental(
+        self,
+        style: str,
+        title: str,
+        model: str = "V4_5ALL",
+        callback_url: str | None = None,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Helper to generate instrumental music.
+
+        Args:
+            style (str): Musical style.
+            title (str): Title of the music.
+            model (str): Model version. Defaults to "V4_5ALL".
+            callback_url (str, optional): Webhook URL.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of generated Song objects if wait is True, otherwise the taskId as a string.
+        """
+        return self.generate(
+            prompt="",
+            style=style,
+            title=title,
+            model=model,
+            instrumental=True,
+            callback_url=callback_url,
+            wait=wait,
+            timeout=timeout
+        )
+
+    def remaster(
+        self,
+        music_id: str,
+        wait: bool = True,
+        timeout: int = 300
+    ) -> str | list[Song]:
+        """Remasters an existing track to improve production quality/mix.
+
+        Args:
+            music_id (str): ID of the generated track to remaster.
+            wait (bool): If True, poll and wait for completion. Defaults to True.
+            timeout (int): Max wait time in seconds. Defaults to 300.
+
+        Returns:
+            str | list[Song]: A list of remastered Song objects if wait is True, otherwise the taskId as a string.
+        """
+        payload = {
+            "musicId": music_id
+        }
+
+        res = self.client.post("/api/v1/generate/remaster", payload)
+        task_id = res["data"]["taskId"]
+
+        if not wait:
+            return task_id
+
+        task_data = self.client.wait_task(task_id, endpoint="/api/v1/generate/record-info", timeout=timeout)
+        return Song.from_task_data(task_data)

suno_easy/persona.py

@@ -0,0 +1,30 @@
+class PersonaResource:
+    """Resource manager for persona creation."""
+
+    def __init__(self, client):
+        """Initializes the PersonaResource with a client reference.
+
+        Args:
+            client (SunoClient): The parent client instance.
+        """
+        self.client = client
+
+    def create(self, music_id: str, name: str) -> dict:
+        """Creates a personalized music persona based on a generated music ID.
+
+        Args:
+            music_id (str): The ID of the generated music track to create the persona from.
+            name (str): The name of the persona.
+
+        Returns:
+            dict: A dictionary containing the generated persona's details (such as personaId).
+        """
+        res = self.client.post(
+            "/api/v1/generate/persona",
+            {
+                "musicId": music_id,
+                "name": name
+            }
+        )
+
+        return res["data"]

suno_easy/utils.py

@@ -0,0 +1,5 @@
+import time
+
+
+def wait(seconds: float = 1):
+    time.sleep(seconds)

suno_easy-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: suno-easy
+Version: 0.1.0
+Summary: A lightweight, modern, and fully-typed Python SDK for the Suno AI API (sunoapi.org)
+Author-email: Fred <frederic.dymko@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Onnonoka/suno-easy
+Project-URL: Documentation, https://github.com/Onnonoka/suno-easy#readme
+Project-URL: Repository, https://github.com/Onnonoka/suno-easy.git
+Project-URL: Issues, https://github.com/Onnonoka/suno-easy/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# suno-easy 🎵
+
+> [!IMPORTANT]
+> **Disclaimer**: This is an unofficial, community-driven Python SDK wrapper for the Suno API (`sunoapi.org`). It is not affiliated with, endorsed, sponsored, or supported by Suno, Inc. or the official Suno AI platform.
+
+`suno-easy` is a lightweight, modern, and fully-typed Python SDK for the Suno AI API ([sunoapi.org](https://docs.sunoapi.org/)). 
+
+It provides an intuitive, object-oriented interface to generate music, write lyrics, create voice personas, separate audio stems, and generate MIDI notes from audio files.
+
+---
+
+## Features
+
+- **Clean Namespace Organization**: Resources are grouped logically (`client.music`, `client.lyrics`, `client.audio`, `client.persona`).
+- **Fully Typed**: Rich python dataclasses for responses (`Song`, `Lyrics`, `SeparatedStems`, `MIDIData`, `CoverImage`).
+- **Smart Polling**: Methods can either block and return the processed result (`wait=True`) or instantly return a `taskId` for asynchronous workflows (`wait=False`).
+- **Built-in Downloads**: Download audio tracks, cover images, and isolated stems with built-in streaming helpers.
+- **Robust Error Handling**: Distinct exceptions for HTTP failures (`SunoAPIError`) and generation failures (`TaskFailed`).
+
+---
+
+## Repository Structure
+
+```text
+suno-easy/
+├── suno_easy/          # Core SDK library source code
+│   ├── __init__.py     # Exposed client, models, and exceptions
+│   ├── client.py       # Main SunoClient orchestrator
+│   ├── models.py       # Strongly typed dataclasses representing API payloads
+│   ├── audio.py        # Audio processing sub-resource (stems, MIDI, covers)
+│   ├── music.py        # Music generation and extension sub-resource
+│   ├── lyrics.py       # Lyrics generation sub-resource
+│   ├── persona.py      # Voice/style persona sub-resource
+│   ├── exceptions.py   # SDK custom exception classes
+│   └── utils.py        # Internal utility and polling helpers
+├── tests/              # Test suite
+│   ├── __init__.py
+│   └── test_client.py  # Mocked HTTP interface unit tests
+├── examples/           # Basic usage examples
+│   └── quickstart.py   # Quickstart example script
+├── pyproject.toml      # PEP 621 compliant project packaging configuration
+├── requirements.txt    # Runtime dependencies
+├── requirements-dev.txt# Development and testing requirements
+├── LICENSE             # MIT License file
+└── README.md           # Project documentation
+```
+
+---
+
+## Installation
+
+This SDK requires `requests`. You can install the package directly from source:
+
+```bash
+pip install .
+```
+
+Or for development (editable mode):
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize the Client
+
+```python
+from suno_easy import SunoClient
+
+client = SunoClient(api_key="your_suno_api_key_here")
+```
+
+### 2. Generate Music
+
+Generate a track in custom mode (requires prompt, style, and title). By default, this blocks until the songs are generated (usually 2-3 minutes) and returns a list containing two song variations.
+
+```python
+songs = client.music.generate(
+    prompt="A peaceful acoustic guitar melody with soft strings",
+    style="Folk, Acoustic",
+    title="Morning Breeze",
+    instrumental=True
+)
+
+for song in songs:
+    print(f"Song generated: {song.title} (ID: {song.id})")
+    print(f"Audio URL: {song.audio_url}")
+    
+    # Download the track and its cover image
+    song.download(f"{song.title}.mp3")
+    song.download_image(f"{song.title}.jpg")
+```
+
+### 3. Generate Lyrics
+
+Create AI-generated lyrics structure markers like `[Verse]` or `[Chorus]`.
+
+```python
+lyrics_list = client.lyrics.generate(prompt="a song about embarking on a journey to Mars")
+
+for lyrics in lyrics_list:
+    print(f"Title Idea: {lyrics.title}")
+    print(lyrics.text)
+```
+
+### 4. Separate Vocals (Stem Separation)
+
+Separate an existing song task into vocals and instrumental tracks. Supports 2-stem (`separate_vocal`) and up to 12-stem (`split_stem`) separation.
+
+```python
+stems = client.audio.separate_vocals(
+    task_id="original_music_task_id",
+    mode="separate_vocal" # or "split_stem"
+)
+
+print(f"Vocal URL: {stems.vocal_url}")
+print(f"Instrumental URL: {stems.instrumental_url}")
+
+# Download isolated files
+stems.download_vocal("vocals.mp3")
+stems.download_instrumental("instrumental.mp3")
+```
+
+### 5. Convert Audio to MIDI
+
+Convert separated audio tracks into MIDI note structures.
+
+```python
+midi_data = client.audio.generate_midi(task_id="vocal_removal_task_id")
+
+print(f"MIDI Generation State: {midi_data.state}")
+for instrument in midi_data.instruments:
+    print(f"Instrument: {instrument.name}")
+    for note in instrument.notes[:5]: # Print first 5 notes
+        print(f"  Note pitch: {note.pitch}, start: {note.start}s, end: {note.end}s")
+```
+
+---
+
+## Asynchronous Workflows (Webhooks & Background Tasks)
+
+If you don't want the methods to block your program execution, set `wait=False`. The client will instantly return the `taskId` string. You can then poll later or receive webhook callbacks on your server.
+
+```python
+# Starts music generation and returns instantly
+task_id = client.music.generate(
+    prompt="Lo-fi hip hop beat for studying",
+    style="Lo-Fi",
+    title="Study Session",
+    wait=False,
+    callback_url="https://yourdomain.com/webhook"
+)
+
+print(f"Music generation started. Task ID: {task_id}")
+
+# Manually retrieve info later
+task_info = client.music.get_task_info(task_id)
+print(f"Status: {task_info.get('status')}")
+```
+
+---
+
+## API Reference
+
+### `client.music`
+*   `generate(...) -> list[Song] | str`: Generates songs from prompts.
+*   `extend(...) -> list[Song] | str`: Extends an existing song from a timestamp.
+*   `generate_instrumental(...) -> list[Song] | str`: Generates instrumentals.
+*   `remaster(music_id, ...) -> list[Song] | str`: Improves the quality of a song.
+
+### `client.lyrics`
+*   `generate(prompt, ...) -> list[Lyrics] | str`: Generates lyrics.
+*   `get(task_id) -> list[Lyrics]`: Retrieves lyrics from a completed task.
+
+### `client.audio`
+*   `cover(upload_url, style, title, ...) -> list[Song] | str`: Applies a style cover to an uploaded audio.
+*   `extend(upload_url, continue_at, prompt, ...) -> list[Song] | str`: Extends an uploaded audio track.
+*   `separate_vocals(task_id, mode, ...) -> SeparatedStems | str`: Split vocals and instrumentation.
+*   `get_separated_stems(task_id) -> SeparatedStems`: Retrieves separated stems.
+*   `generate_midi(task_id, ...) -> MIDIData | str`: Converts audio stems to MIDI notes.
+*   `get_midi(task_id) -> MIDIData`: Retrieves MIDI notes.
+*   `add_vocals(upload_url, prompt, ...) -> list[Song] | str`: Adds vocals to an instrumental track.
+*   `add_instrumental(upload_url, title, tags, ...) -> list[Song] | str`: Adds backing instruments to vocals.
+
+### `client.persona`
+*   `create(music_id, name) -> dict`: Creates a voice/style persona from a track.
+
+---
+
+## License
+
+This project is licensed under the MIT License.

suno_easy-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+suno_easy/__init__.py,sha256=Oq20glb9dN1WmOI8gdJCOuxMCRDo1ElU9hcs4D_gjs4,428
+suno_easy/audio.py,sha256=q5XzqdKlBAau1HiP9V1ZePWLpDAIX2PpYOWNv6vYoZQ,14600
+suno_easy/client.py,sha256=gbGWLxmdfseEK5aAOydY1SvbdAxQtaaacuxRJ2CCZn8,5252
+suno_easy/exceptions.py,sha256=1CJ_f7Xqu8_iFoUEKQGza6xPlauXhE7FHgKLgDg9QW4,757
+suno_easy/lyrics.py,sha256=MxhdEIvW837YSChfnW6Xmg3i7jxdbGBjUCNPIc1ICLM,1862
+suno_easy/models.py,sha256=heV06GYOPXbWfjE78NiPSbUigrrnPGuUQw6cHLQKAE8,6313
+suno_easy/music.py,sha256=f1SKHMNdAKpNaJ_vLh1FGhx8IHdtIDUBJwsSdeoeYEY,6685
+suno_easy/persona.py,sha256=_mOzAAEgfk3MbTLSnen6uyJ72PkhMWU9vHbc-M-m93g,910
+suno_easy/utils.py,sha256=Hd_teNSLHyfDbuPXq8lMn8kV4ZcdQA9e_nNW5oVHYII,67
+suno_easy-0.1.0.dist-info/licenses/LICENSE,sha256=NQOBbjLLnmdABdu7wu3NSyDpTBIhsPDmrf8KROa8GS0,1061
+suno_easy-0.1.0.dist-info/METADATA,sha256=HXI18kUdZd6kH8ttLTaaRrZ0JSC9D8PE5FUYyG1g1UM,7915
+suno_easy-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+suno_easy-0.1.0.dist-info/top_level.txt,sha256=DkNsMy-TPRtD96oVhlhTqWdRGa_4-WUG_-_nKPFgFgE,10
+suno_easy-0.1.0.dist-info/RECORD,,

suno_easy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

suno_easy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

suno_easy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+suno_easy