langchain-tunova 0.1.0

LangChain integration for the Tunova music generation API (Suno-powered songs for AI agents)

langchain-tunova

LangChain integration for Tunova — an API that turns a text prompt into a complete, ready-to-listen song. This package gives your LangChain agents a music generation tool.

Agent-friendly billing: songs are billed only on successful renders — failed generations auto-refund, so autonomous retries are safe. 10 tokens per song, and every account starts with 50 free tokens (no card required).

Installation

pip install langchain-tunova

Setup

Get an API key at tunova.ai and export it:

export TUNOVA_API_KEY="your-api-key"

(Or pass api_key="..." to the tool constructor.)

Usage

Direct invocation:

from langchain_tunova import TunovaMusicGenerationTool

tool = TunovaMusicGenerationTool()
print(tool.invoke({"prompt": "an upbeat synthwave track about road trips"}))
# Generated "Neon Highway" (192s): https://cdn.tunova.ai/...mp3

With an agent:

from langchain.agents import create_agent
from langchain_tunova import TunovaMusicGenerationTool

agent = create_agent(
    model="claude-sonnet-4-5",
    tools=[TunovaMusicGenerationTool()],
)

result = agent.invoke(
    {"messages": [("user", "Make me a chill instrumental lofi track for studying.")]}
)
print(result["messages"][-1].content)

Generation takes a few minutes; the tool polls the job and returns the song title, duration, and audio URL. If a render fails, the tool tells the agent that the tokens were auto-refunded — so the agent can simply retry, at no cost.

Tool reference

Tool name	tunova_generate_song
Arguments	prompt: str, make_instrumental: bool = False
Returns	Generated "<title>" (<duration>s): <audio_url> or an error string
Auth	TUNOVA_API_KEY env var or api_key= constructor arg
Async	Supported (await tool.ainvoke(...))

License

MIT © 2026 Tunova