> ## 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 V2
> Create music powered by AI using just a prompt, lyrics, or a defined music style.
**Music AI v2** is our most advanced music generation model yet, faster generation, higher-quality audio, sharper prompt understanding, and more creative control than any version before it.
## Choose your model
Studio-quality tracks in seconds, reliable, fast, and built for everyday creation.
Everything in v6, now with real-time streaming so listeners hear the track as it's composed.
Our best-sounding model yet, richer detail, more texture, state-of-the-art quality.
The full power of v7 with real-time streaming and advanced creative controls. Our flagship.
New here? Reach for **v7-pro** for the best quality, or drop to **v6** for the fastest, most economical generations.
### Model comparison
| Model | Audio quality | Streaming | Best for |
| -------- | ------------- | --------- | ------------------------------------ |
| `v6` | Very good | - | Fast, dependable everyday tracks |
| `v6-pro` | Very good | Real-time | Live, as-it-generates playback |
| `v7` | Best-in-class | - | Highest-quality final renders |
| `v7-pro` | Best-in-class | Real-time | Production apps that want everything |
Pass your choice with the `model` parameter (`v6`, `v6-pro`, `v7`, or `v7-pro`). Streaming is available on the `pro` models for paid users. Per-model rates are listed on the [Pricing page](/api-documentation/index/pricing).
### 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 full tracks, instrumental-only, or vocal-only versions
* View the live streaming of the song as it generates (`pro` models)
* Asynchronous webhook support for clean integration
Every request returns **two distinct versions** of the track, so you always have a creative option to choose from.
***
## Endpoint
```http theme={null}
POST /v2/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/MusicAiv2) 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 |
| `title` | String | Optional | - | Title of the generated music |
| `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 |
| `generate_album_cover` | Boolean | Optional | false | If `true`, generate an album cover for the generated audio |
| `model` | String | Optional | "v6" | Allowed values: `v6`, `v6-pro`, `v7`, `v7-pro` |
| `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
* 2 (webhook ) x Streaming URL
* 1 (webhook ) x Album cover image
#### Instrumental-only Requests:
* 2 (webhook) x Music conversion details (one per version)
* 2 (webhook ) x Streaming URL
* 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/v2/MusicAI"
headers = {
"Authorization": "",
"Content-Type": "application/json"
}
payload = {
"prompt": "song about a football match between Man City and Arsenal",
"music_style": "Pop",
"model": "v7-pro",
"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 /v2/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:
/v2/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
title:
type: string
description: Title of the generated music track
gender:
type: string
description: Gender of the voice model
voice_id:
type: string
description: Voice model to convert generated audio
generate_album_cover:
type: boolean
description: Whether to generate an album cover for the generated audio
default: false
model:
type: string
description: Model version to use for generation
enum:
- v6
- v6-pro
- v7
- v7-pro
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: []
x-codeSamples:
- lang: Python
source: |-
import requests
url = "https://api.musicgpt.com/api/public/v2/MusicAI"
headers = {
"Authorization": "",
"Content-Type": "application/json"
}
payload = {
"prompt": "Create a relaxing lo-fi song for studying",
"music_style": "Lo-fi",
"lyrics": "It's a brand new day",
"make_instrumental": False,
"vocal_only": False,
"voice_id": "e1cb7380-e3db-433a-b186-a996d7545986",
"title": "My Generated Track",
"gender": "female",
"generate_album_cover": False,
"model": "v7-pro",
"webhook_url": "https://example.com/my-webhook"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````