Pricing Sign In

Music tools

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

#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.

Mode	When to use it	How the API decides
Simple	Quick idea in one text: genre, mood, vibe, instruments. No fixed title, style tags, lyrics, or vocal gender.	Do not set `title` or `style` (leave them empty). Provide a non-empty `prompt` (max 400 characters).
Advanced (custom)	User explicitly provides or asks for lyrics, a specific title, style tags, or vocal gender (or random). Needs either a song description or lyrics (not both), optional negative_tags (what to avoid).	Set both `title` and `style` to non-empty strings. `vocal_gender` is required (`m`, `f`, or `random`). Supply exactly one of `song_description` or `lyrics` when not instrumental (see below).

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

Supported model values (simple and advanced): V4, V4_5, V4_5PLUS, V5, V5_5. If omitted, the platform default applies (typically V5_5). Do not use variants like V4_5ALL.

#generate_music

#Simple mode parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	Single description of the music; max 400 characters.
`instrumental`	boolean	No	If `true`, instrumental only (no vocals). Default: `false`.
`model`	string	No	`V4`, `V4_5`, `V4_5PLUS`, `V5`, or `V5_5`.

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": "V5_5"
}

Example — simple, instrumental:

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

#Advanced mode parameters

Parameter	Type	Required	Description
`title`	string	Yes	Song title; max 80 characters.
`style`	string	Yes	Style / genre / tags; max 1000 characters.
`vocal_gender`	string	Yes	`m`, `f`, or `random` (aliases: `male`/`female`; `random` lets the provider choose). For instrumental, still required by the API but vocal gender is not applied to vocals.
`song_description`	string	XOR with `lyrics`	What the song is about (theme, mood, instructions). Max 5000 chars. Omit if using `lyrics`.
`lyrics`	string	XOR with `song_description`	Full lyrics if the user supplied them. Max 5000 chars. Omit if using `song_description`.
`instrumental`	boolean	No	Default `false`. If `true`, require `song_description` only.
`negative_tags`	string	No	Styles or elements to avoid; max 200 characters.
`style_weight`	number	No	Default 0.65 (same as web app).
`weirdness_constraint`	number	No	Default 0.65.
`audio_weight`	number	No	Default 0.65.
`model`	string	No	Same set as simple mode.

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": "V5_5"
}

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_music_status.

#get_music_status

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

Parameters:

Parameter	Type	Required	Description
`generation_id`	string	Yes	ID returned from generate_music.

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.