Text-to-Music

Generate AI-powered music from text prompts, style tags, and lyrics. Create original songs, instrumentals, and background music.

Endpoint

POST /api/v1/text-to-music

Request

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`application/json`

Body:

{
  "prompt": "An upbeat electronic dance track with a catchy melody",
  "tags": ["electronic", "dance", "upbeat", "energetic"],
  "lyrics": "Feel the rhythm, feel the beat\nMoving to the sound beneath our feet",
  "num_songs": 1,
  "output_format": "mp3",
  "store_audio": true,
  "name": "Dance Track"
}

Parameters

Field	Required	Type	Default	Description
`prompt`	Conditional	string	—	Description of the track.
`tags`	Conditional	string[]	—	Style tags (e.g., "pop", "electronic").
`lyrics`	Conditional	string	—	Lyrics for the song. Empty string for instrumentals.
`seed`	No	number	Random	Seed for reproducibility.
`prompt_strength`	No	number	2	CFG strength. Higher = follows prompt more closely.
`balance_strength`	No	number	0.7	Vocal naturalness balance.
`num_songs`	No	number	1	Number of songs (1 or 2).
`output_format`	No	string	`wav`	`flac`, `mp3`, `wav`, `ogg`, or `m4a`.
`output_bit_rate`	No	string	—	For mp3/m4a: `128`, `192`, `256`, or `320`.
`bpm`	No	number/`"auto"`	`auto`	Beats per minute.
`store_audio`	No	boolean	`false`	Store audio and return a persistent URL.
`name`	No	string	—	Name for the generated track.

Input Combination Rules

You must provide at least one of prompt, tags, or lyrics:

Combination	Allowed?
`prompt` only	✅
`prompt` + `tags`	✅
`prompt` + `lyrics`	✅
`tags` + `lyrics`	✅
`lyrics` only	❌ Must pair with `prompt` or `tags`.
`tags` only	❌ Must pair with `prompt` or `lyrics`.
`prompt` + `tags` + `lyrics`	❌ Do not provide all three.

Response

{
  "success": true,
  "tracks": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Dance Track",
      "audio_url": "https://storage.verbatik.com/music/track-abc123.mp3",
      "seed": 42,
      "tags": ["electronic", "dance", "upbeat", "energetic"],
      "lyrics": "Feel the rhythm, feel the beat..."
    }
  ],
  "cost_cents": 60,
  "balance_cents": 1340
}

Pricing

$0.20 per minute of audio generated.
A typical track (~3 minutes) costs approximately $0.60.
Generating 2 songs (num_songs: 2) doubles the cost.

Track Statuses

Status	Description
`pending`	Being generated (typically 30–90 seconds).
`ready`	Ready to play and download.
`failed`	Generation failed. Check the error message.

Examples

Instrumental Track

curl -X POST https://api.verbatik.com/api/v1/text-to-music \
  -H "Authorization: Bearer vbt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A calm lo-fi hip hop beat perfect for studying",
    "tags": ["lo-fi", "hip-hop", "chill", "instrumental"],
    "lyrics": "",
    "output_format": "mp3",
    "store_audio": true,
    "name": "Study Beats"
  }'

Song with Lyrics

curl -X POST https://api.verbatik.com/api/v1/text-to-music \
  -H "Authorization: Bearer vbt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An acoustic folk song with warm guitar and soft vocals",
    "lyrics": "Walking down the old dirt road\nSunlight dancing through the trees",
    "output_format": "flac",
    "store_audio": true,
    "name": "Morning Walk"
  }'

Reproducible Generation

curl -X POST https://api.verbatik.com/api/v1/text-to-music \
  -H "Authorization: Bearer vbt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Epic orchestral trailer music",
    "tags": ["orchestral", "epic", "cinematic"],
    "seed": 12345,
    "output_format": "wav",
    "store_audio": true
  }'

Error Responses

Status	Error	Description
400	`Invalid input combination`	See input combination rules above.
401	`Invalid or missing API token`	API key is missing or invalid.
402	`Insufficient balance`	Not enough funds.
429	`Rate limit exceeded`	Too many requests.
500	`Internal server error`	Try again or contact support.

Text-to-Music

On this page