tunova 0.1.0__tar.gz

tunova-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tunova
+
+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.

tunova-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: tunova
+Version: 0.1.0
+Summary: Tiny zero-dependency Python client for the Tunova Suno music API (v5.5) — async, billed only on success.
+Author: Tunova
+License: MIT License
+        
+        Copyright (c) 2026 Tunova
+        
+        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.
+        
+Project-URL: Homepage, https://tunova.ai
+Project-URL: Documentation, https://api.tunova.ai/docs
+Project-URL: Source, https://github.com/erliona/tunova-sdk
+Keywords: suno,suno-api,music,ai,mcp,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Tunova SDK
+
+Tiny, **zero-dependency** clients + MCP manifest for the [Tunova](https://tunova.ai) music API —
+generate music with Suno (v5.5) over a simple REST or MCP interface.
+Generation is async and **billed only on success**: a failed render refunds itself.
+
+- **Python** → [`python/tunova.py`](python/tunova.py) — stdlib only, Python 3.8+.
+- **Node / TypeScript** → [`node/tunova.ts`](node/tunova.ts) — Node 18+ (`fetch` built in).
+- **MCP** → [`server.json`](server.json) — hosted Streamable-HTTP server at `https://api.tunova.ai/mcp`.
+
+Get a key (50 free tokens, no card) at **<https://tunova.ai>**. Full reference:
+<https://api.tunova.ai/docs> · live status: <https://tunova.ai/status>.
+
+> Tunova is an independent service, not affiliated with or endorsed by Suno. Tracks come from paid
+> Suno plans; review Suno's terms for your use case.
+
+## Python
+
+```bash
+pip install tunova
+```
+
+```python
+from tunova import Tunova
+
+t = Tunova("sk_live_…")
+job = t.generate("warm lo-fi piano to study to", model="v5.5")
+print(job["clips"][0]["audio_url"] if job["status"] == "complete" else job["error"])
+```
+
+Prefer no install? `python/tunova.py` is stdlib-only — vendor the single file and `import` it.
+
+## Node / TypeScript
+
+```bash
+npm i tunova
+```
+
+```ts
+import { Tunova } from "tunova";
+
+const t = new Tunova(process.env.TUNOVA_API_KEY!);
+const job = await t.generate("warm lo-fi piano to study to", { model: "v5.5" });
+console.log(job.status === "complete" ? job.clips[0]?.audio_url : job.error);
+```
+
+Both `generate()` calls submit a job and poll until the track is delivered. Prefer fire-and-forget?
+Use `submit()` with a `callback_url` and take an HMAC-signed webhook instead.
+
+## MCP — give an AI agent the power to make music
+
+```bash
+claude mcp add --transport http tunova https://api.tunova.ai/mcp \
+  --header "X-API-Key: sk_live_…"
+```
+
+Tools: `generate_song` · `wait_for_song` · `check_song`. Same API key, same billed-on-success rule.
+
+## Verifying webhooks
+
+If you pass `callback_url`, Tunova POSTs the terminal job with
+`X-Webhook-Signature: sha256=<hmac>` over `<X-Webhook-Timestamp>.<rawBody>`, keyed with your
+`whsec_…` secret (view/rotate it on the dashboard's API-keys page). Verify against the **raw** body
+before parsing — both SDKs ship a verifier (`Tunova.verify_webhook` / `verifyWebhook`).
+
+## License
+
+MIT — see [LICENSE](LICENSE). The SDK code is yours to use freely; your use of the Tunova API is
+governed by the [terms](https://tunova.ai/terms).

tunova-0.1.0/README.md

@@ -0,0 +1,69 @@
+# Tunova SDK
+
+Tiny, **zero-dependency** clients + MCP manifest for the [Tunova](https://tunova.ai) music API —
+generate music with Suno (v5.5) over a simple REST or MCP interface.
+Generation is async and **billed only on success**: a failed render refunds itself.
+
+- **Python** → [`python/tunova.py`](python/tunova.py) — stdlib only, Python 3.8+.
+- **Node / TypeScript** → [`node/tunova.ts`](node/tunova.ts) — Node 18+ (`fetch` built in).
+- **MCP** → [`server.json`](server.json) — hosted Streamable-HTTP server at `https://api.tunova.ai/mcp`.
+
+Get a key (50 free tokens, no card) at **<https://tunova.ai>**. Full reference:
+<https://api.tunova.ai/docs> · live status: <https://tunova.ai/status>.
+
+> Tunova is an independent service, not affiliated with or endorsed by Suno. Tracks come from paid
+> Suno plans; review Suno's terms for your use case.
+
+## Python
+
+```bash
+pip install tunova
+```
+
+```python
+from tunova import Tunova
+
+t = Tunova("sk_live_…")
+job = t.generate("warm lo-fi piano to study to", model="v5.5")
+print(job["clips"][0]["audio_url"] if job["status"] == "complete" else job["error"])
+```
+
+Prefer no install? `python/tunova.py` is stdlib-only — vendor the single file and `import` it.
+
+## Node / TypeScript
+
+```bash
+npm i tunova
+```
+
+```ts
+import { Tunova } from "tunova";
+
+const t = new Tunova(process.env.TUNOVA_API_KEY!);
+const job = await t.generate("warm lo-fi piano to study to", { model: "v5.5" });
+console.log(job.status === "complete" ? job.clips[0]?.audio_url : job.error);
+```
+
+Both `generate()` calls submit a job and poll until the track is delivered. Prefer fire-and-forget?
+Use `submit()` with a `callback_url` and take an HMAC-signed webhook instead.
+
+## MCP — give an AI agent the power to make music
+
+```bash
+claude mcp add --transport http tunova https://api.tunova.ai/mcp \
+  --header "X-API-Key: sk_live_…"
+```
+
+Tools: `generate_song` · `wait_for_song` · `check_song`. Same API key, same billed-on-success rule.
+
+## Verifying webhooks
+
+If you pass `callback_url`, Tunova POSTs the terminal job with
+`X-Webhook-Signature: sha256=<hmac>` over `<X-Webhook-Timestamp>.<rawBody>`, keyed with your
+`whsec_…` secret (view/rotate it on the dashboard's API-keys page). Verify against the **raw** body
+before parsing — both SDKs ship a verifier (`Tunova.verify_webhook` / `verifyWebhook`).
+
+## License
+
+MIT — see [LICENSE](LICENSE). The SDK code is yours to use freely; your use of the Tunova API is
+governed by the [terms](https://tunova.ai/terms).

tunova-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tunova"
+version = "0.1.0"
+description = "Tiny zero-dependency Python client for the Tunova Suno music API (v5.5) — async, billed only on success."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "Tunova" }]
+keywords = ["suno", "suno-api", "music", "ai", "mcp", "api-client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://tunova.ai"
+Documentation = "https://api.tunova.ai/docs"
+Source = "https://github.com/erliona/tunova-sdk"
+
+# The client is a single stdlib-only module living in python/tunova.py.
+[tool.setuptools]
+py-modules = ["tunova"]
+
+[tool.setuptools.package-dir]
+"" = "python"

tunova-0.1.0/python/tunova.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: tunova
+Version: 0.1.0
+Summary: Tiny zero-dependency Python client for the Tunova Suno music API (v5.5) — async, billed only on success.
+Author: Tunova
+License: MIT License
+        
+        Copyright (c) 2026 Tunova
+        
+        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.
+        
+Project-URL: Homepage, https://tunova.ai
+Project-URL: Documentation, https://api.tunova.ai/docs
+Project-URL: Source, https://github.com/erliona/tunova-sdk
+Keywords: suno,suno-api,music,ai,mcp,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Tunova SDK
+
+Tiny, **zero-dependency** clients + MCP manifest for the [Tunova](https://tunova.ai) music API —
+generate music with Suno (v5.5) over a simple REST or MCP interface.
+Generation is async and **billed only on success**: a failed render refunds itself.
+
+- **Python** → [`python/tunova.py`](python/tunova.py) — stdlib only, Python 3.8+.
+- **Node / TypeScript** → [`node/tunova.ts`](node/tunova.ts) — Node 18+ (`fetch` built in).
+- **MCP** → [`server.json`](server.json) — hosted Streamable-HTTP server at `https://api.tunova.ai/mcp`.
+
+Get a key (50 free tokens, no card) at **<https://tunova.ai>**. Full reference:
+<https://api.tunova.ai/docs> · live status: <https://tunova.ai/status>.
+
+> Tunova is an independent service, not affiliated with or endorsed by Suno. Tracks come from paid
+> Suno plans; review Suno's terms for your use case.
+
+## Python
+
+```bash
+pip install tunova
+```
+
+```python
+from tunova import Tunova
+
+t = Tunova("sk_live_…")
+job = t.generate("warm lo-fi piano to study to", model="v5.5")
+print(job["clips"][0]["audio_url"] if job["status"] == "complete" else job["error"])
+```
+
+Prefer no install? `python/tunova.py` is stdlib-only — vendor the single file and `import` it.
+
+## Node / TypeScript
+
+```bash
+npm i tunova
+```
+
+```ts
+import { Tunova } from "tunova";
+
+const t = new Tunova(process.env.TUNOVA_API_KEY!);
+const job = await t.generate("warm lo-fi piano to study to", { model: "v5.5" });
+console.log(job.status === "complete" ? job.clips[0]?.audio_url : job.error);
+```
+
+Both `generate()` calls submit a job and poll until the track is delivered. Prefer fire-and-forget?
+Use `submit()` with a `callback_url` and take an HMAC-signed webhook instead.
+
+## MCP — give an AI agent the power to make music
+
+```bash
+claude mcp add --transport http tunova https://api.tunova.ai/mcp \
+  --header "X-API-Key: sk_live_…"
+```
+
+Tools: `generate_song` · `wait_for_song` · `check_song`. Same API key, same billed-on-success rule.
+
+## Verifying webhooks
+
+If you pass `callback_url`, Tunova POSTs the terminal job with
+`X-Webhook-Signature: sha256=<hmac>` over `<X-Webhook-Timestamp>.<rawBody>`, keyed with your
+`whsec_…` secret (view/rotate it on the dashboard's API-keys page). Verify against the **raw** body
+before parsing — both SDKs ship a verifier (`Tunova.verify_webhook` / `verifyWebhook`).
+
+## License
+
+MIT — see [LICENSE](LICENSE). The SDK code is yours to use freely; your use of the Tunova API is
+governed by the [terms](https://tunova.ai/terms).

tunova-0.1.0/python/tunova.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+python/tunova.py
+python/tunova.egg-info/PKG-INFO
+python/tunova.egg-info/SOURCES.txt
+python/tunova.egg-info/dependency_links.txt
+python/tunova.egg-info/top_level.txt

tunova-0.1.0/python/tunova.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tunova-0.1.0/python/tunova.egg-info/top_level.txt

@@ -0,0 +1 @@
+tunova

tunova-0.1.0/python/tunova.py

@@ -0,0 +1,159 @@
+"""Tunova — tiny zero-dependency Python client for the Suno music API (https://api.tunova.ai).
+
+Generation is asynchronous: ``submit()`` returns a ``job_id``; ``generate()`` submits and
+polls until the track is delivered. You're billed only when a song actually delivers —
+failed renders are auto-refunded.
+
+    from tunova import Tunova
+
+    t = Tunova("sk_live_…")
+    job = t.generate("lofi hip hop to code to", model="v5.5")
+    if job["status"] == "complete":
+        print(job["clips"][0]["audio_url"])
+    else:
+        print("failed (auto-refunded):", job["error"])
+
+Stdlib only — no pip install needed. Python 3.8+.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+
+DEFAULT_BASE = "https://api.tunova.ai"
+_TERMINAL = ("complete", "failed")
+
+
+class TunovaError(Exception):
+    """An API error. ``code``/``detail`` mirror the JSON error envelope; ``request_id`` is the
+    X-Request-Id you can quote to support."""
+
+    def __init__(self, status: int, code: str, detail: str, request_id: Optional[str] = None):
+        super().__init__(f"[{status}] {code}: {detail}")
+        self.status = status
+        self.code = code
+        self.detail = detail
+        self.request_id = request_id
+
+
+class Tunova:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE, timeout: float = 30.0):
+        if not api_key:
+            raise ValueError("api_key is required (your sk_live_… key)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- transport ----
+    def _request(self, method: str, path: str, headers: Dict[str, str], data: Optional[bytes]) -> Any:
+        req = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            try:
+                body = json.loads(raw)
+            except Exception:
+                body = {}
+            raise TunovaError(
+                e.code,
+                body.get("code", "HTTP_ERROR"),
+                body.get("detail", raw.decode("utf-8", "replace")[:300]),
+                body.get("request_id"),
+            ) from None
+
+    def _post(self, path: str, body: Dict[str, Any], idempotency_key: Optional[str] = None) -> Any:
+        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._request("POST", path, headers, json.dumps(body).encode())
+
+    def _get(self, path: str) -> Any:
+        return self._request("GET", path, {"X-API-Key": self.api_key}, None)
+
+    # ---- API ----
+    def submit(
+        self,
+        prompt: str,
+        *,
+        custom: bool = False,
+        tags: Optional[str] = None,
+        title: Optional[str] = None,
+        make_instrumental: bool = False,
+        model: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Submit a generation job (returns immediately). Response: ``{job_id, status, status_url}``.
+
+        ``custom=True`` switches to lyrics mode (``prompt`` = your lyrics; add ``tags``/``title``).
+        ``model`` is e.g. "v5.5". Pass ``callback_url`` for an HMAC-signed webhook on
+        completion, or poll ``get_job``. ``idempotency_key`` makes a retried submit return the same
+        job (never double-charged)."""
+        body: Dict[str, Any] = {"prompt": prompt}
+        if custom:
+            if tags is not None:
+                body["tags"] = tags
+            if title is not None:
+                body["title"] = title
+        if make_instrumental:
+            body["make_instrumental"] = True
+        if model:
+            body["model"] = model
+        if callback_url:
+            body["callback_url"] = callback_url
+        path = "/api/custom_generate" if custom else "/api/generate"
+        return self._post(path, body, idempotency_key)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Fetch a job's current state. Once ``status == "complete"``, ``clips[].audio_url`` is set."""
+        return self._get(f"/api/jobs/{job_id}")
+
+    def wait_for(self, job_id: str, *, poll_interval: float = 3.0, timeout: float = 300.0) -> Dict[str, Any]:
+        """Poll until the job is terminal ("complete"/"failed") or ``timeout`` seconds elapse."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.get("status") in _TERMINAL:
+                return job
+            if time.monotonic() >= deadline:
+                raise TunovaError(0, "TIMEOUT", f"job {job_id} not terminal after {timeout}s")
+            time.sleep(poll_interval)
+
+    def generate(self, prompt: str, *, poll_interval: float = 3.0, timeout: float = 300.0, **kwargs: Any) -> Dict[str, Any]:
+        """``submit`` + ``wait_for``. Returns the terminal job — check ``job["status"]``
+        ("complete" or "failed"). All ``submit`` keyword args are forwarded."""
+        accepted = self.submit(prompt, **kwargs)
+        return self.wait_for(accepted["job_id"], poll_interval=poll_interval, timeout=timeout)
+
+    # ---- webhooks ----
+    @staticmethod
+    def verify_webhook(
+        secret: str,
+        timestamp: str,
+        body: str,
+        signature: str,
+        *,
+        tolerance: int = 300,
+    ) -> bool:
+        """Verify a webhook delivery. ``signature`` = the ``X-Webhook-Signature`` header
+        ("sha256=<hex>"), ``timestamp`` = ``X-Webhook-Timestamp``, ``body`` = the RAW request body
+        string (verify before parsing), ``secret`` = your ``whsec_…`` key. Returns True iff the
+        signature matches AND the timestamp is within ``tolerance`` seconds (anti-replay; pass
+        ``tolerance=0`` to skip the freshness check)."""
+        if tolerance:
+            try:
+                if abs(time.time() - int(timestamp)) > tolerance:
+                    return False
+            except (TypeError, ValueError):
+                return False
+        expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
+        provided = signature[7:] if signature.startswith("sha256=") else signature
+        return hmac.compare_digest(expected, provided)

tunova-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+