> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicgpt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Music AI
> Create music powered by AI using just a prompt, lyrics, or a defined music style.
**Music AI** generates original music compositions from a prompt, lyrics, or musical style. Whether you're a developer, content creator, or musician, this tool provides an easy and flexible way to create music powered by AI.
Key features:
* Compose custom songs using your own lyrics and chosen music style
* Generate complete tracks from a single prompt, including lyrics, instrumentation, and melody
* Apply voice conversion using a custom voice model
* Output options: full tracks, instrumental-only, or vocal-only
* Asynchronous webhook support for seamless integration
Each request generates **two versions** of the song with variation, giving you more creative options.
***
## Endpoint
```http theme={null}
POST /MusicAI
```
This is the primary endpoint for initiating music generation.
***
## Sample Output
Listen to a real sample output:
Prompt: a song about greenery, nature and forest.
Download Audio
***
## Try It Yourself
Use the [MusicAI Endpoint Explorer](/api-documentation/endpoint/MusicAI) to test your own requests using prompts, lyrics, and more.
> Each request returns **two distinct versions** of the track.
***
## Request Parameters
| Parameter | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ------------------------------------------------ |
| `prompt` | String | Optional | — | A natural language prompt for music generation |
| `music_style` | String | Optional | — | Musical style or genre (e.g., Rock, Pop, Lo-fi) |
| `lyrics` | String | Optional | "" | Custom lyrics to use in the song |
| `make_instrumental` | Boolean | Optional | false | If true, generate instrumental-only audio |
| `vocal_only` | Boolean | Optional | false | If true, generate vocals without instruments |
| `voice_id` | String | Optional | "" | Apply voice model for vocal rendering |
| `output_length` | float | Optional | "" | The requested output audio length of the request |
| `webhook_url` | String | Optional | "" | URL to receive generated results via webhook |
| `gender` | String | Optional | "" | Allowed values: male, female, neutral. |
> **content-type:** application/json
***
## Generation Modes
### Custom Mode
Provide both `lyrics` and `music_style` to craft a fully personalized song.
### Prompt Mode
Supply only a `prompt` and let the system generate everything: lyrics, style, vocals, and more.
> `make_instrumental`, `vocal_only`, and Music AI generation with custom `voice_id` are supported in both modes.
***
## Webhook Delivery
Once the generation is complete, **webhooks** will be triggered to deliver the following:
#### Standard Requests (non-instrumental):
* 2 (webhooks) x Music conversion details (one per version)
* 2 (webhooks) x Lyrics with timestamp data
* 1 (webhook ) x Album cover image
#### Instrumental-only Requests:
* 2 (webhook) x Music conversion details (one per version)
* 1 (webhook) x Album cover image
> Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc.
***
## Sample Request (Python)
```python theme={null}
import requests
url = "https://api.musicgpt.com/api/public/v1/MusicAI"
headers = {
"Authorization": "",
"Content-Type": "application/json"
}
payload = {
"prompt": "song about a football match between Man City and Arsenal",
"music_style": "Pop",
"webhook_url": "https://abcd.requestcatcher.com/",
"lyrics": "",
"voice_id": "Drake"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
***
## Sample Response
```json theme={null}
{
"success": true,
"message": "Message published to queue",
"task_id": "8e058b85-6c22-41cc-a6ed-1e91ed73e34b",
"conversion_id_1": "2872d9a6-4abe-4a8f-a04f-5540c4ef0a1a",
"conversion_id_2": "dda98922-d5e9-4fc9-accd-4fc1f0729234",
"eta": 76,
"credit_estimate": 0.99
}
```
***
## Webhook Sample Payload
```json theme={null}
{
"success": true,
"conversion_type": "Music AI",
"task_id": "8e058b85-6c22-41cc-a6ed-1e91ed73e34b",
"conversion_id": "2872d9a6-4abe-4a8f-a04f-5540c4ef0a1a",
"conversion_path": "https://lalals.s3.amazonaws.com/conversions/2872d9a6-4abe-4a8f-a04f-5540c4ef0a1a.mp3",
"conversion_path_wav": "https://lalals.s3.amazonaws.com/conversions/2872d9a6-4abe-4a8f-a04f-5540c4ef0a1a.wav",
"conversion_duration": 213.99,
"is_flagged": false,
"reason": "",
"lyrics": "...",
"lyrics_timestamped": "[ ... ]",
"title": "Contradiction"
}
```
> Note: Each `conversion_id` corresponds to a different variation of the track.
***
## Payload and Request Formation
## OpenAPI
````yaml POST /v1/MusicAI
openapi: 3.1.0
info:
title: Musicgpt API
version: 1.0.0
description: API for retrieving conversion details by ID.
servers:
- url: https://api.musicgpt.com/api/public
description: Production server
security: []
paths:
/v1/MusicAI:
post:
summary: Generate Custom Music
description: >-
Create music powered by AI using just a prompt, lyrics, or a defined
music style.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
description: >-
A natural language prompt for music generation. Keep it
under 280 characters for guaranteed results, but
detailed—the clearer and more descriptive it is, the better
the outcome.
music_style:
type: string
description: Style of music to generate (e.g., Rock, Pop)
lyrics:
type: string
description: Custom lyrics for the generated music
make_instrumental:
type: boolean
description: Whether to make the music instrumental
default: false
vocal_only:
type: boolean
description: Whether to generate only vocals of output audio
default: false
gender:
type: string
description: Gender of the voice model
voice_id:
type: string
description: Voice model to convert generated audio
output_length:
type: number
format: float
description: >-
The requested output audio length of the request in seconds.
This feature is purely experimental.
webhook_url:
type: string
description: URL for callback upon completion
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
task_id:
type: string
conversion_id_1:
type: string
conversion_id_2:
type: string
eta:
type: integer
example:
success: true
message: Message published to queue
task_id: 4fc2cdba-005d-4d14-a208-5fb02a2809da
conversion_id_1: 05092d5c-f8b1-4c96-a4a3-45bc00de6268
conversion_id_2: 52fcd3b6-3925-41ed-b4c6-aee17a29e40b
eta: 154
'402':
description: Payment Required
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Insufficient credit balance
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Internal Server Error
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````