tunova

Tunova SDK

Tunova の音楽 API 向けの、依存関係ゼロの小さなクライアントと MCP マニフェストです — シンプルな REST または MCP インターフェースを使って、Suno（v5.5）で音楽を生成できます。 生成は非同期で、成功した場合にのみ課金されます。レンダリングに失敗した場合は、料金が自動的に返金されます。

• Python → python/tunova.py — 標準ライブラリのみを使用。Python 3.8 以降に対応。
• Node / TypeScript → node/tunova.ts — Node 18 以降に対応（fetch は組み込み）。
• MCP → server.json — https://api.tunova.ai/mcp でホストされる Streamable-HTTP サーバー。

https://tunova.ai で API キーを取得できます（無料トークン 50 個、カード不要）。詳しいリファレンス： https://api.tunova.ai/docs · ライブステータス：https://tunova.ai/status。

Tunova は独立したサービスであり、Suno とは提携も推奨関係もありません。楽曲は有料の Suno プランから生成されます。ご利用の際は、用途に応じて Suno の利用規約をご確認ください。

Python

pip install tunova

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"])

インストールせずに使いたい場合は、python/tunova.py は標準ライブラリのみを使用するため、このファイルだけを同梱して import できます。

Node / TypeScript

npm i tunova

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);

どちらの generate() 呼び出しもジョブを送信し、楽曲が配信されるまでポーリングします。処理を待たずに済ませたい場合は、 submit() に callback_url を指定して、HMAC 署名付きの Webhook を受け取ってください。

MCP — AI エージェントに音楽を作る力を与える

claude mcp add --transport http tunova https://api.tunova.ai/mcp \
  --header "X-API-Key: sk_live_…"

ツール：generate_song · wait_for_song · check_song。同じ API キーを使用し、成功した場合にのみ課金されるルールも同じです。

Webhook の検証

callback_url を指定すると、Tunova は最終状態のジョブを X-Webhook-Signature: sha256=<hmac> ヘッダーとともに POST します。署名は <X-Webhook-Timestamp>.<rawBody> に対して計算され、whsec_… シークレット（ダッシュボードの API キーページで確認・ローテーションできます）を使用します。解析する前に、生のボディに対して検証してください — どちらの SDK にも検証関数（Tunova.verify_webhook / verifyWebhook）が含まれています。

ライセンス

MIT — LICENSE をご覧ください。SDK コードは自由にご利用いただけます。Tunova API のご利用には 利用規約が適用されます。