> ## 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.
# Cover Song
> Convert an audio file or URL into a cover song using a different voice.
Convert an audio file or URL into a cover song using a different voice model.
The **Cover Song** endpoint recreates a vocal track using AI voice models, allowing for pitch manipulation and background audio transformation. Perfect for covers, remixes, or experimenting with different vocal styles.
***
## Endpoint
```http theme={null}
POST /v1/Cover
```
This is the primary endpoint for initiating cover song conversion tasks.
***
## Sample Output
Listen to a real sample output:
Output File:
Download Audio
***
## Try it Yourself
Visit the [Cover Endpoint Explorer](/api-documentation/endpoint/cover) to test it live. Upload your audio, select a voice model, and hear the transformation.
***
## Request Parameters
| Parameter | Type | Required | Description |
| ------------- | ------------ | -------- | -------------------------------------------------------------------------------------- |
| `audio_url` | `String` | Optional | URL of the audio file to convert. Either `audio_url` or `audio_file` must be provided. |
| `audio_file` | `UploadFile` | Optional | Upload the audio file directly. Either `audio_url` or `audio_file` must be provided. |
| `voice_id` | `String` | Yes | Voice model to convert the audio into. |
| `pitch` | `Integer` | Optional | Adjust pitch between -12 and 12 semitones. Default is `0`. |
| `webhook_url` | `String` | Optional | Callback URL for async response. |
> 💡**Note**: You must provide either `audio_url` or `audio_file` — not both as `None`.
> **content-type:** multipart/form-data
***
## Sample Request
### cURL
```bash theme={null}
curl -X POST "https://api.musicgpt.com/api/public/v1/Cover" \
-H "accept: multipart/form-data" \
-H "Authorization: " \
-F "audio_url=https://www.youtube.com/watch?v=jGflUbPQfW8" \
-F "voice_id=Drake" \
-F "pitch=0" \
-F "webhook_url=http://webhook.musicgpt.com"
```
### Python
```python theme={null}
import requests
url = "https://api.musicgpt.com/api/public/v1/Cover"
headers = {
"accept": "multipart/form-data",
"Authorization": ""
}
input_audio_file = open("{path_to_your_audio_file}", "rb")
payload = {
"audio_url": "",
"voice_id": "Drake",
"pitch": 0,
"webhook_url": "http://abc.requestcatcher.com/test",
}
response = requests.post(url, headers=headers, data=payload, files={"audio_file": input_audio_file})
print(response.json())
```
> Replace `{path_to_your_audio_file}`, `api_key`, and `webhook_url` before executing.
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success": true,
"task_id": "3d137437-4911-4669-b639-9e5701107c25",
"conversion_id": "b764b4f6-a842-42dd-a55b-818eb8251dc7",
"eta": 71,
"credit_estimate": 1.27,
"message": "Message published to queue",
"status": "IN_QUEUE"
}
```
***
## Common Errors
* **400 Bad Request**: The file could not be downloaded from the provided URL.
* **402 Payment Required**: Your credit balance is insufficient.
* **422 Unprocessable Entity**: No `audio_url` or `audio_file` provided.
* **500 Internal Server Error**: Something went wrong on our end.
***
## Webhook Response
When the cover conversion completes, the webhook receives:
```json theme={null}
{
"success": true,
"conversion_type": "Cover",
"task_id": "0ec93bdd-6132-40db-a873-676dc314919c",
"conversion_id": "acff300f-1c96-498d-99fe-929b985c5c55",
"audio_url": "https://lalals.s3.amazonaws.com/projects/acff300f-1c96-498d-99fe-929b985c5c55.mp3",
"audio_url_wav": "https://lalals.s3.amazonaws.com/projects/acff300f-1c96-498d-99fe-929b985c5c55.wav",
"conversion_cost": "0.88",
"conversion_duration": 272.44
}
```
You can download or stream the result directly from the `audio_url`.
***
## Payload and Request Formation
## OpenAPI
````yaml POST /v1/Cover
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/Cover:
post:
summary: Convert audio to cover song
description: Convert an audio file or URL into a cover song using a different voice.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
audio_url:
type: string
description: 'Input audio URL (supported format: YouTube URL).'
example: https://example.com/audio.wav
audio_file:
type: string
format: binary
description: >-
Audio file to upload and process. Either audio_file or
audio_url must be provided.
voice_id:
type: string
description: The ID of the voice model to use for voice transformation.
example: demo-voice-id
pitch:
type: integer
description: >-
Pitch adjustment for the voice. Range from -12 to 12.
Default: 0
default: 0
minimum: -12
maximum: 12
webhook_url:
type: string
description: >-
A URL where the result will be sent once processing is
completed.
example: https://example.com/callback
required:
- voice_id
anyOf:
- required:
- audio_url
- required:
- audio_file
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
task_id:
type: string
conversion_id:
type: string
eta:
type: integer
example:
success: true
task_id: b329c0df-b2eb-4914-b707-4d7dce53577e
conversion_id: 16708396-da86-4a9e-9b90-66f774cc2382
eta: 33
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: The file could not be downloaded from the provided URL
'402':
description: Payment Required
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Insufficient credit balance
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Both audio_url and audio_file cannot be None
'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/v1/Cover"
headers = {
"Authorization": ""
}
data = {
"voice_id": "e0bb585f-b798-4bac-ac4e-de7fff38f9d7",
"pitch": 0,
"webhook_url": "https://example.com/my-webhook"
}
# Option 1: audio_url
data["audio_url"] = ""
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.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
````