> ## 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.
# Sing Over Instrumental
> This endpoint allows users to sing over an instrumental audio track using a text prompt and lyrics. It supports either a file upload or a URL to the input audio and generates a vocal overlay based on the provided lyrics and style.
Generate a sung vocal performance over an instrumental audio track using a style prompt and lyrics.
***
## Endpoint
```http theme={null}
POST /sing_over_instrumental
```
This endpoint enables you to overlay vocals onto an instrumental audio using a textual description of the singing style and provided lyrics. Input can be either a file upload or a URL. You can optionally specify the vocal gender and a webhook URL for asynchronous processing.
***
## Request Parameters
| Parameter | Type | Required | Description |
| ------------- | ------------ | -------- | ---------------------------------------------------------------------------------------- |
| `audio_file` | `UploadFile` | Optional | Upload the instrumental audio file. Required if `audio_url` is not provided. |
| `audio_url` | `String` | Optional | URL or youtube link to the instrumental audio. Required if `audio_file` is not provided. |
| `prompt` | `String` | Required | Text describing the desired singing style. Example: "Sing in soft jazz style" |
| `lyrics` | `String` | Required | The lyrics to be sung over the instrumental. Max 2000 characters. |
| `gender` | `String` | Optional | Voice style. Options: `male`, `female`, `neutral`. |
| `webhook_url` | `String` | Optional | Callback URL to receive processing results. |
> 💡 **Note:** You must provide either `audio_file` or `audio_url` — at least one is required.
> **content-type:** multipart/form-data
***
## Sample Output
Listen to a real output:
Prompt: sing over instrumental in classical slow vibe - audio input : Moana How Far We will Go.
Download Audio
***
***
## Try it Yourself
Use the [Sing Over Insturmental Endpoint Explorer](/api-documentation/endpoint/sing_over_instrumental) to test this endpoint live with your own inputs.
***
## Sample Request
### cURL
```bash theme={null}
curl -X POST "https://api.musicgpt.com/api/public/v1/sing_over_instrumental" \
-H "accept: application/json" \
-H "Authorization: " \
-F "audio_url=https://youtube.com/audio.mp3" \
-F "prompt=Sing like Adele in a soulful tone" \
-F "lyrics=Never mind I'll find someone like you..." \
-F "gender=female" \
-F "webhook_url=https://yourdomain.com/webhook"
```
### Python
```python theme={null}
import requests
url = "https://api.musicgpt.com/api/public/v1/sing_over_instrumental"
headers = {"Authorization": ""}
data = {
"prompt": "Sing emotional vocals over a soft piano instrumental",
"lyrics": "Never mind I'll find someone like you...",
"gender": "female",
"webhook_url": "https://yourdomain.com/webhook"
}
# Option 1: Use audio_url
data["audio_url"] = "https://youtube.com/audio.mp3"
response = requests.post(url, headers=headers, data=data)
# Option 2: File upload
# with open("audio.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data, files=files)
# print(response.json())
```
> 🔐 Be sure to replace the placeholders like `` and file paths with real values.
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success": true,
"message": "Sing Over Instrumental request submitted successfully",
"task_id": "task-abcde12345",
"conversion_id_1": "over-instrumental-1",
"conversion_id_2": "over-instrumental-2",
"eta": 45,
"credit_estimate": 50
}
```
***
## Webhook Response
When the process completes, the provided `webhook_url` (if any) will receive a JSON POST with:
```json theme={null}
{
"success": true,
"conversion_type": "sing_over_instrumental",
"task_id": "task-abcde12345",
"conversion_id": "over-instrumental-1",
"conversion_path": "https://lalals.s3.amazonaws.com/conversions/over-instrumental-1.mp3",
"conversion_path_wav": "https://lalals.s3.amazonaws.com/conversions/over-instrumental-1.wav",
"conversion_duration": 175.34,
"is_flagged": false,
"lyrics": "Never mind I'll find someone like you...",
"title": "Emotional Overlay"
}
```
***
## Webhook Delivery
Once the generation is complete, **webhooks** will be triggered to deliver the following:
#### Standard Requests (non-instrumental):
* 2 (webhooks) x Sing Over conversion details (one per version)
* 2 (webhooks) x Lyrics with timestamp data
* 1 Album Cover Image
> Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc.
***
## Common Errors
* **422 Unprocessable Entity**: Missing required fields like `prompt` or `lyrics`, or no audio input provided.
* **500 Internal Server Error**: Unexpected error during processing.
***
Use this endpoint to effortlessly bring your lyrics to life with expressive vocals over any instrumental.
## OpenAPI
````yaml POST /v1/sing_over_instrumental
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/sing_over_instrumental:
post:
summary: Sing Over Instrumental Using Prompt and Lyrics
description: >-
This endpoint allows users to sing over an instrumental audio track
using a text prompt and lyrics. It supports either a file upload or a
URL to the input audio and generates a vocal overlay based on the
provided lyrics and style.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
audio_file:
type: string
format: binary
description: Uploaded instrumental audio file.
audio_url:
type: string
description: URL or S3 path to the input instrumental audio.
example: https://bucket.s3.amazonaws.com/audio.mp3
prompt:
type: string
description: Description of the singing style, tone, or genre.
example: Sing emotional vocals over a soft piano instrumental.
lyrics:
type: string
description: The lyrics to be sung over the instrumental.
example: Never mind I'll find someone like you...
maxLength: 2000
gender:
type: string
description: Voice gender to guide generation.
enum:
- male
- female
- neutral
example: female
webhook_url:
type: string
description: >-
Callback URL to receive status updates or final audio
result.
example: https://yourdomain.com/webhook
required:
- prompt
- lyrics
anyOf:
- required:
- audio_url
- required:
- audio_file
responses:
'200':
description: Successfully initiated sing over instrumental task
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
description: Estimated processing time in seconds
credit_estimate:
type: number
format: float
example:
success: true
message: Sing Over Instrumental request submitted successfully
task_id: task-abcde12345
conversion_id_1: over-instrumental-1
conversion_id_2: over-instrumental-2
eta: 45
credit_estimate: 50
'422':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: >-
Either audio_file or audio_url must be provided, along
with prompt and lyrics.
'500':
description: Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Internal Server Error
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: Python
source: >-
import requests
url =
"https://api.musicgpt.com/api/public/v1/sing_over_instrumental"
headers = {"Authorization": ""}
data = {
"prompt": "Sing emotional vocals over a soft piano instrumental.",
"lyrics": "Never mind I'll find someone like you...",
"gender": "female",
"webhook_url": "https://yourdomain.com/webhook"
}
# Option 1: Use audio_url
data["audio_url"] = "https://bucket.s3.amazonaws.com/audio.mp3"
response = requests.post(url, headers=headers, data=data)
# Option 2: Upload file
# with open("audio.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data,
files=files)
# print(response.json())
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````