runapi-suno 0.1.0__tar.gz

runapi_suno-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

runapi_suno-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: runapi-suno
+Version: 0.1.0
+Summary: Suno music, sound, lyrics, and voice client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/suno
+Project-URL: Documentation, https://runapi.ai/docs#sdk-suno
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,audio,lyrics,music,runapi,sdk,suno,voice
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Suno Python SDK for RunAPI
+
+The Suno Python SDK is the language-specific package for Suno on RunAPI. Use it
+for music, sound effect, lyrics, stem, MIDI, and custom voice flows when your
+application needs JSON request bodies, task status lookup, and consistent RunAPI
+errors in Python.
+
+For model details, use https://runapi.ai/models/suno; for API reference, use
+https://runapi.ai/docs#suno; for SDK docs, use https://runapi.ai/docs#sdk-suno.
+
+## Install
+
+```bash
+pip install runapi-suno
+```
+
+## Quick start
+
+```python
+from runapi.suno import SunoClient
+
+client = SunoClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+# Generate music and poll until completion.
+result = client.text_to_music.run(
+    model="suno-v4.5-plus",
+    vocal_mode="auto_lyrics",
+    prompt="A chill lo-fi beat with soft vocals",
+)
+print(result.audios[0].audio_url)
+
+# Generate lyrics from a prompt.
+lyrics = client.generate_lyrics.run(prompt="a song about the ocean at night")
+print(lyrics.lyrics[0].text)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+task = client.text_to_music.create(
+    model="suno-v4.5-plus",
+    vocal_mode="instrumental",
+    style="ambient piano",
+    title="Quiet Morning",
+)
+status = client.text_to_music.get(task.id)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a
+worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated audio,
+images, and videos in your own durable storage within 7 days; do not treat
+returned URLs as long-term assets.
+
+## Resources
+
+The client exposes one accessor per resource:
+
+- Music: `text_to_music`, `extend_music`, `cover_audio`, `add_instrumental`,
+  `add_vocals`, `replace_section`, `create_mashup`
+- Sound and lyrics: `text_to_sound`, `generate_lyrics`, `get_timestamped_lyrics`
+- Audio tooling: `separate_audio_stems`, `generate_midi`, `convert_audio`,
+  `visualize_music`, `generate_artwork`
+- Voice and style: `voice_to_validation_phrase`, `regenerate_validation_phrase`,
+  `generate_voice`, `check_voice`, `generate_persona`, `boost_style`
+
+Music, sound, stem, MIDI, conversion, visualization, artwork, replace-section,
+mashup, validation-phrase, and voice resources are asynchronous: call `run` to
+create and poll, or `create` plus `get`. Lyrics lookup, persona, voice check,
+and style boost return their result directly from `run`.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.suno` error classes
+when building audio jobs or scripts. Keep `RUNAPI_API_KEY` in the environment or
+your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/suno
+- SDK docs: https://runapi.ai/docs#sdk-suno
+- Product docs: https://runapi.ai/docs#suno
+- Pricing and rate limits: https://runapi.ai/models/suno
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_suno-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Suno Python SDK for RunAPI
+
+The Suno Python SDK is the language-specific package for Suno on RunAPI. Use it
+for music, sound effect, lyrics, stem, MIDI, and custom voice flows when your
+application needs JSON request bodies, task status lookup, and consistent RunAPI
+errors in Python.
+
+For model details, use https://runapi.ai/models/suno; for API reference, use
+https://runapi.ai/docs#suno; for SDK docs, use https://runapi.ai/docs#sdk-suno.
+
+## Install
+
+```bash
+pip install runapi-suno
+```
+
+## Quick start
+
+```python
+from runapi.suno import SunoClient
+
+client = SunoClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+# Generate music and poll until completion.
+result = client.text_to_music.run(
+    model="suno-v4.5-plus",
+    vocal_mode="auto_lyrics",
+    prompt="A chill lo-fi beat with soft vocals",
+)
+print(result.audios[0].audio_url)
+
+# Generate lyrics from a prompt.
+lyrics = client.generate_lyrics.run(prompt="a song about the ocean at night")
+print(lyrics.lyrics[0].text)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+task = client.text_to_music.create(
+    model="suno-v4.5-plus",
+    vocal_mode="instrumental",
+    style="ambient piano",
+    title="Quiet Morning",
+)
+status = client.text_to_music.get(task.id)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a
+worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated audio,
+images, and videos in your own durable storage within 7 days; do not treat
+returned URLs as long-term assets.
+
+## Resources
+
+The client exposes one accessor per resource:
+
+- Music: `text_to_music`, `extend_music`, `cover_audio`, `add_instrumental`,
+  `add_vocals`, `replace_section`, `create_mashup`
+- Sound and lyrics: `text_to_sound`, `generate_lyrics`, `get_timestamped_lyrics`
+- Audio tooling: `separate_audio_stems`, `generate_midi`, `convert_audio`,
+  `visualize_music`, `generate_artwork`
+- Voice and style: `voice_to_validation_phrase`, `regenerate_validation_phrase`,
+  `generate_voice`, `check_voice`, `generate_persona`, `boost_style`
+
+Music, sound, stem, MIDI, conversion, visualization, artwork, replace-section,
+mashup, validation-phrase, and voice resources are asynchronous: call `run` to
+create and poll, or `create` plus `get`. Lyrics lookup, persona, voice check,
+and style boost return their result directly from `run`.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.suno` error classes
+when building audio jobs or scripts. Keep `RUNAPI_API_KEY` in the environment or
+your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/suno
+- SDK docs: https://runapi.ai/docs#sdk-suno
+- Product docs: https://runapi.ai/docs#suno
+- Pricing and rate limits: https://runapi.ai/models/suno
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_suno-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-suno"
+version = "0.1.0"
+description = "Suno music, sound, lyrics, and voice client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "suno", "music", "audio", "lyrics", "voice", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/suno"
+Documentation = "https://runapi.ai/docs#sdk-suno"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+runapi-core = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.runapi]
+slug = "suno"

runapi_suno-0.1.0/src/runapi/suno/__init__.py

@@ -0,0 +1,24 @@
+"""Suno client for RunAPI."""
+
+from runapi.core import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    TaskFailedError,
+    TaskTimeoutError,
+    ValidationError,
+)
+
+from .client import SunoClient
+
+__all__ = [
+    "SunoClient",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ValidationError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

runapi_suno-0.1.0/src/runapi/suno/_validators.py

@@ -0,0 +1,208 @@
+"""Shared Suno request validators.
+
+Ported from the Ruby ``RunApi::Suno::Validators`` module. Each ``validate_*``
+function mirrors its Ruby counterpart, including the exact ``ValidationError``
+message strings. Resources call these from their ``_validate_params`` hook.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Sequence
+
+from runapi.core import ValidationError
+
+from . import types
+
+_TRUTHY_VALUES = [True, 1, "1", "true", "TRUE", "True"]
+
+
+def _param(params: Dict[str, Any], key: str) -> Any:
+    return params.get(key)
+
+
+def _truthy(value: Any) -> bool:
+    return value in _TRUTHY_VALUES
+
+
+def _truthy_presence(value: Any) -> bool:
+    if hasattr(value, "__len__"):
+        return len(value) > 0
+    return value is not None
+
+
+def _to_i(value: Any) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        if isinstance(value, str):
+            digits = ""
+            for ch in value.strip():
+                if ch in "+-" and not digits:
+                    digits += ch
+                elif ch.isdigit():
+                    digits += ch
+                else:
+                    break
+            try:
+                return int(digits)
+            except ValueError:
+                return 0
+        return 0
+
+
+def _to_f(value: Any) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def require_param(params: Dict[str, Any], key: str) -> None:
+    if _param(params, key) is None:
+        raise ValidationError(f"{key} is required")
+
+
+def require_all(params: Dict[str, Any], *keys: str) -> None:
+    for key in keys:
+        require_param(params, key)
+
+
+def validate_optional(params: Dict[str, Any], key: str, allowed: Sequence[Any]) -> None:
+    value = params.get(key)
+    if value is None:
+        return
+    if value not in allowed:
+        joined = ", ".join(str(option) for option in allowed)
+        raise ValidationError(f"Invalid {key}: {value}. Must be one of: {joined}")
+
+
+def validate_extend_music_prompt_shape(params: Dict[str, Any]) -> None:
+    if not _truthy_presence(_param(params, "lyrics")):
+        return
+
+    if _truthy_presence(_param(params, "prompt")):
+        raise ValidationError("prompt cannot be combined with lyrics")
+
+    if _truthy(_param(params, "instrumental")):
+        raise ValidationError("lyrics cannot be used when instrumental is true")
+
+    upload_mode = any(_truthy_presence(_param(params, key)) for key in ("audio_url", "upload_url"))
+    if _param(params, "parameter_mode") == "custom" and upload_mode:
+        return
+
+    raise ValidationError("lyrics can only be used when extending uploaded audio with custom parameters")
+
+
+def validate_extend_music(params: Dict[str, Any]) -> None:
+    if not any(_param(params, key) for key in ("task_id", "audio_id", "audio_url", "upload_url")):
+        raise ValidationError("task_id, audio_id, audio_url, or upload_url is required")
+    require_param(params, "parameter_mode")
+    require_param(params, "model")
+
+    validate_optional(params, "parameter_mode", types.PARAMETER_MODES)
+    if _param(params, "parameter_mode") == "custom":
+        require_param(params, "style")
+        require_param(params, "title")
+        require_param(params, "continue_at")
+    validate_extend_music_prompt_shape(params)
+    validate_optional(params, "model", types.MODELS)
+    validate_optional(params, "vocal_gender", types.VOCAL_GENDERS)
+    validate_optional(params, "persona_type", types.PERSONA_TYPES)
+
+
+def validate_generate_artwork(params: Dict[str, Any]) -> None:
+    require_param(params, "task_id")
+
+
+def validate_add_instrumental(params: Dict[str, Any]) -> None:
+    require_all(params, "upload_url", "title", "negative_tags", "tags", "model")
+    validate_optional(params, "model", types.MODELS)
+    validate_optional(params, "vocal_gender", types.VOCAL_GENDERS)
+
+
+def validate_add_vocals(params: Dict[str, Any]) -> None:
+    require_all(params, "upload_url", "lyrics", "title", "negative_tags", "style", "model")
+    validate_optional(params, "model", types.MODELS)
+    validate_optional(params, "vocal_gender", types.VOCAL_GENDERS)
+
+
+def validate_separate_audio_stems(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "audio_id")
+    validate_optional(params, "type", types.SEPARATE_AUDIO_STEMS_TYPES)
+
+
+def validate_generate_midi(params: Dict[str, Any]) -> None:
+    require_param(params, "task_id")
+
+
+def validate_convert_audio(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "audio_id")
+
+
+def validate_visualize_music(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "audio_id")
+
+
+def validate_generate_lyrics(params: Dict[str, Any]) -> None:
+    require_param(params, "prompt")
+
+
+def validate_get_timestamped_lyrics(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "audio_id")
+
+
+def validate_replace_section(params: Dict[str, Any]) -> None:
+    require_all(
+        params,
+        "task_id",
+        "audio_id",
+        "lyrics",
+        "tags",
+        "title",
+        "infill_start_time",
+        "infill_end_time",
+    )
+    if _to_f(_param(params, "infill_end_time")) <= _to_f(_param(params, "infill_start_time")):
+        raise ValidationError("infill_end_time must be greater than infill_start_time")
+
+
+def validate_text_to_sound(params: Dict[str, Any]) -> None:
+    require_all(params, "prompt", "model")
+    validate_optional(params, "model", types.SOUND_MODELS)
+    validate_optional(params, "sound_key", types.SOUND_KEYS)
+    tempo = _param(params, "sound_tempo")
+    if tempo is not None and not (1 <= _to_i(tempo) <= 300):
+        raise ValidationError("sound_tempo must be between 1 and 300")
+
+
+def validate_voice_to_validation_phrase(params: Dict[str, Any]) -> None:
+    require_all(params, "voice_url", "vocal_start_seconds", "vocal_end_seconds")
+    validate_optional(params, "language", types.VALIDATION_PHRASE_LANGUAGES)
+
+    start_seconds = _to_i(_param(params, "vocal_start_seconds"))
+    end_seconds = _to_i(_param(params, "vocal_end_seconds"))
+    if end_seconds > start_seconds:
+        return
+
+    raise ValidationError("vocal_end_seconds must be greater than vocal_start_seconds")
+
+
+def validate_regenerate_validation_phrase(params: Dict[str, Any]) -> None:
+    require_param(params, "task_id")
+
+
+def validate_generate_voice(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "verify_url")
+    validate_optional(params, "singer_skill_level", types.SINGER_SKILL_LEVELS)
+
+
+def validate_check_voice(params: Dict[str, Any]) -> None:
+    require_param(params, "task_id")
+
+
+def validate_generate_persona(params: Dict[str, Any]) -> None:
+    require_all(params, "task_id", "audio_id", "name", "description")
+
+
+def validate_boost_style(params: Dict[str, Any]) -> None:
+    require_param(params, "description")

runapi_suno-0.1.0/src/runapi/suno/client.py

@@ -0,0 +1,70 @@
+"""Suno client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.add_instrumental import AddInstrumental
+from .resources.add_vocals import AddVocals
+from .resources.boost_style import BoostStyle
+from .resources.check_voice import CheckVoice
+from .resources.convert_audio import ConvertAudio
+from .resources.cover_audio import CoverAudio
+from .resources.create_mashup import CreateMashup
+from .resources.extend_music import ExtendMusic
+from .resources.generate_artwork import GenerateArtwork
+from .resources.generate_lyrics import GenerateLyrics
+from .resources.generate_midi import GenerateMidi
+from .resources.generate_persona import GeneratePersona
+from .resources.generate_voice import GenerateVoice
+from .resources.get_timestamped_lyrics import GetTimestampedLyrics
+from .resources.regenerate_validation_phrase import RegenerateValidationPhrase
+from .resources.replace_section import ReplaceSection
+from .resources.separate_audio_stems import SeparateAudioStems
+from .resources.text_to_music import TextToMusic
+from .resources.text_to_sound import TextToSound
+from .resources.visualize_music import VisualizeMusic
+from .resources.voice_to_validation_phrase import VoiceToValidationPhrase
+
+
+class SunoClient:
+    """Suno music, sound, lyrics, and voice client.
+
+    Example::
+
+        client = SunoClient(api_key="sk-...")
+        result = client.text_to_music.run(
+            prompt="A chill lo-fi beat with soft vocals",
+            model="suno-v4.5-plus",
+            vocal_mode="auto_lyrics",
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        resolved_api_key = resolve_api_key(api_key)
+        client_options = ClientOptions(api_key=resolved_api_key, **options)
+        http = client_options.http_client or HttpClient(client_options)
+
+        self.text_to_music = TextToMusic(http)
+        self.extend_music = ExtendMusic(http)
+        self.generate_artwork = GenerateArtwork(http)
+        self.cover_audio = CoverAudio(http)
+        self.add_instrumental = AddInstrumental(http)
+        self.add_vocals = AddVocals(http)
+        self.separate_audio_stems = SeparateAudioStems(http)
+        self.generate_midi = GenerateMidi(http)
+        self.convert_audio = ConvertAudio(http)
+        self.visualize_music = VisualizeMusic(http)
+        self.generate_lyrics = GenerateLyrics(http)
+        self.get_timestamped_lyrics = GetTimestampedLyrics(http)
+        self.replace_section = ReplaceSection(http)
+        self.create_mashup = CreateMashup(http)
+        self.text_to_sound = TextToSound(http)
+        self.voice_to_validation_phrase = VoiceToValidationPhrase(http)
+        self.regenerate_validation_phrase = RegenerateValidationPhrase(http)
+        self.generate_voice = GenerateVoice(http)
+        self.check_voice = CheckVoice(http)
+        self.generate_persona = GeneratePersona(http)
+        self.boost_style = BoostStyle(http)