Music tools

Generate full music tracks. All music jobs are asynchronous: call generate_music, then poll get_status until status is completed (or failed).

For sound effects, an instrumental bed of an exact length, or a soundtrack written against a video you already have, use generate_sound below.

#How to choose: simple vs advanced

The generate_music tool supports two mutually exclusive modes. The agent should pick one based on what the user needs.

Default to SIMPLE mode. Use ADVANCED only when the user explicitly provides or asks for lyrics, a title, style tags, or vocal gender.

Rules:

• If the user only describes a song idea (vibe, mood, genre, instruments) with no mention of lyrics/title/style → use simple mode.
• If both title and style are non-empty → advanced mode (custom). prompt is ignored for content; use song_description / lyrics instead.
• If either title or style is set alone → invalid; supply both or neither.
• If neither title nor style is set → simple mode; prompt is required.

Advanced mode — description vs lyrics (non-instrumental):

• Choose one: set song_description or lyrics, never both. Sending both is rejected (they are not appended or merged).
• Description path: theme/mood/instructions for the model to write the song; leave lyrics empty.
• Lyrics path: user-supplied full lyrics; leave song_description empty.

Advanced mode — instrumental: set instrumental: true and provide song_description only; do not pass lyrics.

Use get_models with model_type=music for current model IDs and credit costs.

#Models

Music generation is powered by Suno. Supported model values (simple and advanced): V6, V6_WILD, V6_MINI (displayed in the app as V6, V6 Wild and V6 Mini). All three cost the same, so the choice is character, not price: V6 has the richest detail and the most natural vocals, V6_WILD pushes further for a bolder result, V6_MINI is the fast, light lane.

If model is omitted, the platform default V6 applies. Every earlier version (V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5) was discontinued by the provider. A request naming one is served by V6 at the same price rather than rejected, so an existing integration keeps working, but those ids are no longer part of the supported set.

#generate_music

#Simple mode parameters

Do not pass title, style, or vocal_gender for simple mode (leave empty).

Example — simple, with vocals:

{
  "prompt": "Upbeat pop song about summer",
  "instrumental": false,
  "model": "V6"
}

Example — simple, instrumental:

{
  "prompt": "Epic orchestral background music",
  "instrumental": true
}

#Advanced mode parameters

Content requirement (advanced, not instrumental): exactly one of song_description or lyrics must be non-empty (the other omitted or empty).

Example — advanced with description only:

{
  "title": "Neon Midnight",
  "style": "synthwave, 80s, driving bass, nostalgic",
  "vocal_gender": "random",
  "song_description": "A song about driving through the city at night with neon reflections",
  "model": "V6"
}

Example — advanced with lyrics only:

{
  "title": "Morning Light",
  "style": "acoustic folk, gentle guitar, warm",
  "vocal_gender": "f",
  "lyrics": "[Verse 1] ... [Chorus] ..."
}

Response: Includes generation_id, status (e.g. pending), and often estimated_time_seconds. Poll with get_status.

<a id="generate_sound"></a>

#generate_sound

Sound effects and music, either from a sentence or written against a clip you already have. Not for songs with vocals: that is generate_music. Every model here bills per second and generations cannot be refunded, so quote with estimate before you run it.

Pick the model by what you have:

Prefer a -video-to-video-* id when the user wants a finished clip back, and the bare audio ids when they will mix the sound themselves in an editor.

Parameters:

A video run with no prompt at all is valid, and often better: the model writes to what it sees.

Billing: per second of the clip for video models (not of the output), and per second of output for the text models. Each product has a minimum billable length: 10 seconds on anything that writes music (both *-sound ids included) and 3 seconds on the effects-only ids, so a 6-second score bills 10 seconds. estimate(model=..., reference_video_seconds=<clip seconds>) applies the minimum for you.

Response: {generation_id, status: "pending"}. Poll get_status until completed or failed. There is no provider callback, so the poll is also what settles the run; stop early and the credits stay reserved.

#get_status

Check the status of a music generation and get song URLs when done.

Parameters:

Response: Includes status, progress, and when completed a songs array. Each song typically has id, title, audio_url, stream_url, cover_image_url, duration, lyrics, and style.

See Limitations for rate limits and credits.