CCAPI

Generate a song

generate_music

Generate a song with vocals or instrumental. Two modes: simple (custom=false) where you describe the song and the model writes the lyrics, or custom (custom=true) where you supply lyrics, title and style tags. Asynchronous — returns a task_id you poll with get_task; generation usually takes 30-120 seconds and normally yields two variations.

Input Schema

TableJSON Schema

Name	Required	Description
`tags`	No	Comma-separated style tags, e.g. 'pop, upbeat, guitar'. Max 200 characters.
`model`	No	Suno model version, e.g. chirp-v5 or chirp-v4-5-plus. Omit for the platform default.
`title`	No	Song title. Used in custom mode.
`custom`	No	false (default) lets the model write the lyrics from your description; true means prompt contains lyrics you wrote and you should also set title and tags.
`prompt`	Yes	In simple mode (custom=false) a description of the song, e.g. 'a dreamy lo-fi track about late-night trains'. In custom mode (custom=true) the actual lyrics, with section markers like [Verse] and [Chorus].
`provider`	No	Music backend: 'suno' (default) or 'producer'.
`instrumental`	No	Generate without vocals.
`wait_seconds`	No	Poll server-side for up to this many seconds (max 240) and return finished audio if it completes in time. Omit to return a task_id immediately.
`negative_tags`	No	Styles to avoid, e.g. 'heavy metal, rap'.

Output Schema

TableJSON Schema

Name	Required	Description
`raw`	No	Full result payload when completed — clip IDs, lyrics text and per-clip metadata. Clip IDs from here are what extend_music takes.
`note`	Yes	What to do next.
`status`	Yes	One of: queued, in_progress, completed, failed.
`task_id`	Yes	Pass this to get_task together with platform to check progress.
`platform`	Yes	'suno' or 'producer'. Pass to get_task.
`audio_urls`	No	Finished audio URLs, when the task completed within wait_seconds.

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description clearly discloses that the operation is asynchronous, returns a task_id to poll, typically takes 30–120 seconds, and normally produces two variations. These are valuable behavioral details beyond the generic annotations, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences deliver the core operation, mode distinction, and asynchronous behavior without filler. The most decision-relevant information is front-loaded, making the description easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential workflow, modes, polling mechanism, and timing expectations, which is enough for an agent to invoke the tool correctly. It does not mention failure semantics or explicitly rule out sibling tools, but the detailed input schema and presence of an output schema cover most remaining context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already well documented. The description adds a useful high-level synthesis of the custom vs simple modes, but it does not provide substantial new parameter-level meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Generate a song'), and immediately distinguishes two modes (simple vs custom) plus an instrumental option. It is clearly differentiated from sibling tools like extend_music and generate_lyrics by describing the generation workflow and output behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use each mode: simple for model-written lyrics and custom for user-supplied lyrics. It also instructs the agent to poll with get_task after receiving the task_id, but it does not explicitly contrast this tool with alternatives such as extend_music or generate_lyrics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All CCAPI tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool maps to a distinct media type or lifecycle step: text, image, music, video, task status, balance, and model discovery. The adjacent tools like edit_image vs generate_image and generate_lyrics vs generate_music are explicitly cross-referenced in their descriptions, so an agent can reliably pick the right one.

Naming Consistency4/5

All but one tool follows a clear imperative verb_noun pattern: edit_image, generate_music, get_task, list_models, etc. chat_completion is the lone structural outlier, using a noun phrase instead of a verb-led action name, which is a minor but noticeable inconsistency.

Tool Count5/5

11 tools is well-scoped for a multimodal API: one generation tool per media type, plus task polling, model listing, and balance checking. There is no redundancy or bloat, and each tool earns its place in the set.

Completeness4/5

The surface covers the full asynchronous workflow—submit generation, poll status, retrieve results—plus model discovery and quota awareness, so there are no dead ends. It lacks conveniences like cancelling a queued task or listing historical tasks, but those are minor gaps rather than blockers for the stated purpose.

Resources

Need Help?