> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelslab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Song Generator
> Generate full songs in 50+ languages by providing lyrics and a reference audio style using the ACE-Step v1.5 model.
## Overview
The Song Generator API lets you create complete, production-quality songs by combining your lyrics with a reference audio file that defines the style, mood, and instrumentation. You can also skip writing lyrics entirely and let the model generate them automatically from a prompt.
Provide your lyrics directly or enable auto-generation with a `prompt`. Supply a `caption` describing the musical style : genre, instruments, vocal type, and mood.
Optionally attach a reference audio via `init_audio` to influence the style further. Set the `duration` between 30 and 480 seconds.
The API returns a hosted audio URL once generation is complete, or fires a webhook to your endpoint if provided.
***
## Request
Make a `POST` request to the endpoint below and pass the required parameters as a JSON body.
```curl curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
--request POST 'https://modelslab.com/api/v6/voice/song_generator' \
```
***
## Body Parameters
Your API key.
Set to `true` to auto-generate lyrics from `prompt`. When `false`, provide `lyrics` directly.
Song lyrics with section tags like `[Verse 1]`, `[Chorus]`, `[Bridge]`. Required if `lyrics_generation` is `false`.
Topic or description for auto lyrics generation. Required if `lyrics_generation` is `true`.
Musical style descriptor : genre, instruments, vocal type, tempo, mood. E.g. `"female vocal, pop, piano, slow, emotional"`.
URL to a reference audio file (MP3/WAV) to influence the song's style.
Song length in seconds. Range: **30–480** (0.5–8 minutes).
Language code for lyrics and vocals. Defaults to auto-detection. See table below.
Set to `true` to generate a vocals-free instrumental track.
URL to receive a POST callback when generation completes.
Custom ID sent with the webhook payload for request correlation.
***
## Example Requests
* Song duration must be between **30 and 480 seconds** (0.5–8 minutes)
* If you don't have lyrics, set `lyrics_generation: true` and provide a `prompt` and `caption` instead
* Set `instrumental: true` to generate a vocals-free track
* 50+ languages are supported : see the table below
With manual lyrics (`lyrics_generation: false`)
```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"key": "your_api_key",
"lyrics_generation": false,
"lyrics": "[Verse 1]\nYour eyes hypnotize me, make me sigh\nYour lips call to me, I can't escape\n\n[Chorus]\nTonight I'll give you everything\nIn your arms I'll stay",
"caption": "female vocal, reggaeton, deep bass, drum machine, reverb",
"duration": 120,
"webhook": null,
"track_id": null
}
```
With auto lyrics generation (`lyrics_generation: true`)
```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"key": "your_api_key",
"lyrics_generation": true,
"prompt": "A Cantopop track with layered female vocals and synth keys",
"caption": "female vocal, Cantopop, synth keys, mid-tempo, ethereal",
"duration": 180,
"webhook": null,
"track_id": null
}
```
***
## Supported Languages
| Language | Code |
| - | - |
| Arabic | ar |
| Azerbaijani | az |
| Bulgarian | bg |
| Bengali | bn |
| Catalan | ca |
| Czech | cs |
| Danish | da |
| German | de |
| Greek | el |
| English | en |
| Spanish | es |
| Persian | fa |
| Finnish | fi |
| French | fr |
| Hebrew | he |
| Hindi | hi |
| Croatian | hr |
| Haitian Creole | ht |
| Hungarian | hu |
| Indonesian | id |
| Icelandic | is |
| Italian | it |
| Japanese | ja |
| Korean | ko |
| Latin | la |
| Lithuanian | lt |
| Malay | ms |
| Nepali | ne |
| Dutch | nl |
| Norwegian | no |
| Punjabi | pa |
| Polish | pl |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Sanskrit | sa |
| Slovak | sk |
| Serbian | sr |
| Swedish | sv |
| Swahili | sw |
| Tamil | ta |
| Telugu | te |
| Thai | th |
| Tagalog | tl |
| Turkish | tr |
| Ukrainian | uk |
| Urdu | ur |
| Vietnamese | vi |
| Cantonese | yue |
| Chinese | zh |
## OpenAPI
````yaml POST /voice/song_generator
openapi: 3.1.0
info:
title: ModelsLab Voice API
description: >-
A comprehensive API for AI-driven voice and audio generation including
text-to-speech, voice cloning, music generation, and audio processing
capabilities
license:
name: MIT
version: 6.0.0
servers:
- url: https://modelslab.com/api/v6
security: []
paths:
/voice/song_generator:
post:
summary: Generate song from lyrics and reference audio
description: Creates a song from lyrics and reference audio URL
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SongGeneratorRequest'
responses:
'200':
description: Song generation response
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
SongGeneratorRequest:
type: object
required:
- key
properties:
key:
type: string
description: API key for authentication
lyrics_generation:
type: boolean
description: Pass true to generate lyrics automatically
lyrics:
type: string
description: >-
Lyrics in LRC format (timestamp + lyrics). Required if
lyrics_generation is false
prompt:
type: string
description: Topic for lyrics generation. Required if lyrics_generation is true
init_audio:
type: string
format: uri
description: URL to reference audio file to influence style
duration:
type:
- integer
- 'null'
description: >-
Duration of the generated song in seconds (30-480 seconds / 0.5-8
minutes)
language:
type:
- string
- 'null'
enum:
- ar
- az
- bg
- bn
- ca
- cs
- da
- de
- el
- en
- es
- fa
- fi
- fr
- he
- hi
- hr
- ht
- hu
- id
- is
- it
- ja
- ko
- la
- lt
- ms
- ne
- nl
- 'no'
- pa
- pl
- pt
- ro
- ru
- sa
- sk
- sr
- sv
- sw
- ta
- te
- th
- tl
- tr
- uk
- ur
- vi
- yue
- zh
- null
description: Language for the generated song
instrumental:
type:
- boolean
- 'null'
description: Whether to generate an instrumental version without vocals
caption:
type:
- string
- 'null'
description: >-
Caption for the song describe styles, female or male voice or loops
and more.
webhook:
type: string
format: uri
description: URL to receive POST notification upon completion
track_id:
type: integer
description: ID for webhook identification
oneOf:
- title: Auto-generate lyrics
required:
- lyrics_generation
- prompt
- caption
properties:
lyrics_generation:
enum:
- true
- title: Manual lyrics
properties:
lyrics_generation:
enum:
- false
VoiceResponse:
type: object
properties:
status:
type: string
enum:
- success
- processing
- error
description: Status of the voice generation
generationTime:
type: number
description: Time taken to generate the audio in seconds
id:
type: integer
description: Unique identifier for the voice generation
output:
type: array
items:
type: string
format: uri
description: Array of generated audio URLs
proxy_links:
type: array
items:
type: string
format: uri
description: Array of proxy audio URLs
future_links:
type: array
items:
type: string
format: uri
description: Array of future audio URLs for queued requests
links:
type: array
items:
type: string
format: uri
description: Array of audio URLs (voice cover response)
meta:
type: object
description: Metadata about the audio generation including all parameters used
eta:
type: integer
description: Estimated time for completion in seconds (processing status)
message:
type: string
description: Status message or additional information
tip:
type: string
description: Additional information or tips for the user
fetch_result:
type: string
format: uri
description: URL to fetch the result when processing
audio_time:
type: number
description: Duration of the generated audio in seconds
Error:
type: object
required:
- status
- message
properties:
status:
type: string
enum:
- error
message:
type: string
description: Error message description
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.