Sing Over Instrumental

Python

import requests

url = "https://api.wav.com/api/public/v1/sing_over_instrumental"
headers = {"Authorization": "<API_KEY>"}
data = {
  "prompt": "Sing emotional vocals over a soft piano instrumental.",
  "lyrics": "Never mind I'll find someone like you...",
  "gender": "female",
  "title": "My Generated Track",
  "webhook_url": "https://yourdomain.com/webhook"
}

# Option 1: Use audio_url
data["audio_url"] = "<YOUR_AUDIO_URL>"
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())

curl --request POST \
  --url https://api.wav.com/api/public/v1/sing_over_instrumental \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form audio_url=https://bucket.s3.amazonaws.com/audio.mp3 \
  --form 'prompt=Sing emotional vocals over a soft piano instrumental.' \
  --form 'lyrics=Never mind I'\''ll find someone like you...' \
  --form 'audio_file=<string>' \
  --form gender=female \
  --form 'title=<string>' \
  --form generate_album_cover=false \
  --form lyrics_timestamps=false \
  --form webhook_url=https://yourdomain.com/webhook \
  --form 0.audio_file='@example-file' \
  --form 1.audio_file='@example-file'

const form = new FormData();
form.append('audio_url', 'https://bucket.s3.amazonaws.com/audio.mp3');
form.append('prompt', 'Sing emotional vocals over a soft piano instrumental.');
form.append('lyrics', 'Never mind I'll find someone like you...');
form.append('audio_file', '<string>');
form.append('gender', 'female');
form.append('title', '<string>');
form.append('generate_album_cover', 'false');
form.append('lyrics_timestamps', 'false');
form.append('webhook_url', 'https://yourdomain.com/webhook');
form.append('0.audio_file', '{
  "fileName": "example-file"
}');
form.append('1.audio_file', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.wav.com/api/public/v1/sing_over_instrumental', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wav.com/api/public/v1/sing_over_instrumental",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wav.com/api/public/v1/sing_over_instrumental"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wav.com/api/public/v1/sing_over_instrumental")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wav.com/api/public/v1/sing_over_instrumental")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Sing Over Instrumental request submitted successfully",
  "task_id": "653c5108-c827-4568-9671-9259fd6b44cc",
  "conversion_id_1": "1d712957-00d9-493a-a6aa-8497ccaea9bc",
  "conversion_id_2": "7d6fa7a2-292c-4a95-8bda-df8ccce44bef",
  "is_flagged": false,
  "reason": "",
  "eta": 258,
  "status": "IN_QUEUE",
  "credit_estimate": 0.1,
  "error_message": "",
  "error_message_detail": "",
  "missing_input_fields": "",
  "predicted_user_intent": ""
}

{
  "success": false,
  "message": "Either audio_file or audio_url must be provided, along with prompt and lyrics."
}

{
  "success": false,
  "message": "Internal Server Error"
}

POST

sing_over_instrumental

Python

import requests

url = "https://api.wav.com/api/public/v1/sing_over_instrumental"
headers = {"Authorization": "<API_KEY>"}
data = {
  "prompt": "Sing emotional vocals over a soft piano instrumental.",
  "lyrics": "Never mind I'll find someone like you...",
  "gender": "female",
  "title": "My Generated Track",
  "webhook_url": "https://yourdomain.com/webhook"
}

# Option 1: Use audio_url
data["audio_url"] = "<YOUR_AUDIO_URL>"
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())

curl --request POST \
  --url https://api.wav.com/api/public/v1/sing_over_instrumental \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form audio_url=https://bucket.s3.amazonaws.com/audio.mp3 \
  --form 'prompt=Sing emotional vocals over a soft piano instrumental.' \
  --form 'lyrics=Never mind I'\''ll find someone like you...' \
  --form 'audio_file=<string>' \
  --form gender=female \
  --form 'title=<string>' \
  --form generate_album_cover=false \
  --form lyrics_timestamps=false \
  --form webhook_url=https://yourdomain.com/webhook \
  --form 0.audio_file='@example-file' \
  --form 1.audio_file='@example-file'

const form = new FormData();
form.append('audio_url', 'https://bucket.s3.amazonaws.com/audio.mp3');
form.append('prompt', 'Sing emotional vocals over a soft piano instrumental.');
form.append('lyrics', 'Never mind I'll find someone like you...');
form.append('audio_file', '<string>');
form.append('gender', 'female');
form.append('title', '<string>');
form.append('generate_album_cover', 'false');
form.append('lyrics_timestamps', 'false');
form.append('webhook_url', 'https://yourdomain.com/webhook');
form.append('0.audio_file', '{
  "fileName": "example-file"
}');
form.append('1.audio_file', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

options.body = form;

fetch('https://api.wav.com/api/public/v1/sing_over_instrumental', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wav.com/api/public/v1/sing_over_instrumental",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: multipart/form-data; boundary=---011000010111000001101001"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wav.com/api/public/v1/sing_over_instrumental"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wav.com/api/public/v1/sing_over_instrumental")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wav.com/api/public/v1/sing_over_instrumental")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_url\"\r\n\r\nhttps://bucket.s3.amazonaws.com/audio.mp3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nSing emotional vocals over a soft piano instrumental.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics\"\r\n\r\nNever mind I'll find someone like you...\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio_file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"gender\"\r\n\r\nfemale\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"generate_album_cover\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"lyrics_timestamps\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://yourdomain.com/webhook\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.audio_file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Sing Over Instrumental request submitted successfully",
  "task_id": "653c5108-c827-4568-9671-9259fd6b44cc",
  "conversion_id_1": "1d712957-00d9-493a-a6aa-8497ccaea9bc",
  "conversion_id_2": "7d6fa7a2-292c-4a95-8bda-df8ccce44bef",
  "is_flagged": false,
  "reason": "",
  "eta": 258,
  "status": "IN_QUEUE",
  "credit_estimate": 0.1,
  "error_message": "",
  "error_message_detail": "",
  "missing_input_fields": "",
  "predicted_user_intent": ""
}

{
  "success": false,
  "message": "Either audio_file or audio_url must be provided, along with prompt and lyrics."
}

{
  "success": false,
  "message": "Internal Server Error"
}

Generate a sung vocal performance over an instrumental audio track using a style prompt and lyrics.

Endpoint

POST /v1/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.

Request Parameters

Parameter	Type	Required	Description
`title`	`String`	Optional	Title of the generated music
`audio_file`	`UploadFile`	Optional	Upload the instrumental audio file. Required if `audio_url` is not provided.
`audio_url`	`String`	Optional	URL to the audio file.
`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`.
`generate_album_cover`	Boolean	Optional	false	If `true`, generate an album cover for the generated audio
`lyrics_timestamps`	Boolean	Optional	false	If true, generates lyric timestamps for the output track
`webhook_url`	`String`	Optional	Callback URL to receive processing results.

Note: Either audio_file or audio_url must be provided.

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 to test this endpoint live with your own inputs.

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.

Sample Request

cURL

curl -X POST "https://api.wav.com/api/public/v1/sing_over_instrumental" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-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

import requests

url = "https://api.wav.com/api/public/v1/sing_over_instrumental"
headers = {"Authorization": "<API_KEY>"}
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())

Sample Response

Success (200 OK)

{
  "success": true,
  "message": "Sing Over Instrumental request submitted successfully",
  "task_id": "653c5108-c827-4568-9671-9259fd6b44cc",
  "conversion_id_1": "1d712957-00d9-493a-a6aa-8497ccaea9bc",
  "conversion_id_2": "7d6fa7a2-292c-4a95-8bda-df8ccce44bef",
  "is_flagged": false,
  "reason": "",
  "eta": 258,
  "status": "IN_QUEUE",
  "credit_estimate": 0.1,
  "error_message": "",
  "error_message_detail": "",
  "missing_input_fields": "",
  "predicted_user_intent": ""
}

Webhook Sample Payload

Sing Over Instrumental Webhook

{
  "success": true,
  "conversion_type": "Sing Over Instrumental",
  "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c",
  "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2",
  "conversion_path": "https://cdn1.wav.com/conversions/api/standard/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.mp3",
  "conversion_path_wav": "https://cdn1.wav.com/conversions/api/hq/8725079f-bf68-5098-a6c8-6dcba44dcaa2/8725079f-bf68-5098-a6c8-6dcba44dcaa2.wav",
  "conversion_duration": 155.95,
  "is_flagged": false,
  "reason": "",
  "lyrics": "[Verse]\nTurn up the sound\nLet the rhythm take control\nFeel every beat\nMoving through my soul\nLights are shining bright\nAnd we lose track of time\n\n[Chorus]\nMusic in the air\nDancing through the night\nEvery beat we share\nMakes everything feel right\nTurn it up again\nLet the whole world sing",
  "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]",
  "title": "Rhythm Take Control",
  "subtype": "remix"
}

Album Cover Webhook

{
  "success": true,
  "conversion_type": "Sing Over Instrumental",
  "task_id": "5254c422-0fab-53f0-b5e3-36abb69dd111",
  "image_paths": [
    "https://cdn1.wav.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg"
  ],
  "thumbnail_paths": [
    "https://cdn1.wav.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg"
  ],
  "image_path": "https://cdn1.wav.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111.jpg",
  "thumbnail_path": "https://cdn1.wav.com/img-gen-pipeline/api/5254c422-0fab-53f0-b5e3-36abb69dd111_thumb.jpg",
  "conversion_id_1": "eba76eae-9c77-5b09-9f2b-96a8bdef0f36",
  "conversion_id_2": "1cf119ce-a78c-500b-ad43-4b1f598507cb",
  "album_cover_generator_output": true,
  "subtype": "album_cover_generation",
}

Lyrics Timestamp Webhook

{
  "success": true,
  "conversion_type": "Sing Over Instrumental",
  "task_id": "c287cca4-c03a-5074-b16a-b8da9d6a124c",
  "conversion_id": "8725079f-bf68-5098-a6c8-6dcba44dcaa2",
  "subtype": "lyrics_timestamped",
  "lyrics_timestamped": "[{\"start\": 9880, \"end\": 35120, \"text\": \"[Verse]\", \"index\": 0}, {\"start\": 9880, \"end\": 10720, \"text\": \"Turn up the sound\", \"index\": 1}, {\"start\": 13720, \"end\": 15600, \"text\": \"Let the rhythm take control\", \"index\": 2}, {\"start\": 19200, \"end\": 20400, \"text\": \"Feel every beat\", \"index\": 3}, {\"start\": 23480, \"end\": 25400, \"text\": \"Moving through my soul\", \"index\": 4}, {\"start\": 29520, \"end\": 31440, \"text\": \"Lights are shining bright\", \"index\": 5}, {\"start\": 33320, \"end\": 35120, \"text\": \"And we lose track of time\", \"index\": 6}, {\"start\": 39640, \"end\": 54320, \"text\": \"[Chorus]\", \"index\": 7}, {\"start\": 39640, \"end\": 40120, \"text\": \"Music in the air\", \"index\": 8}, {\"start\": 41800, \"end\": 42560, \"text\": \"Dancing through the night\", \"index\": 9}, {\"start\": 44320, \"end\": 45280, \"text\": \"Every beat we share\", \"index\": 10}, {\"start\": 45600, \"end\": 47440, \"text\": \"Makes everything feel right\", \"index\": 11}, {\"start\": 49240, \"end\": 49920, \"text\": \"Turn it up again\", \"index\": 12}, {\"start\": 51720, \"end\": 54320, \"text\": \"Let the whole world sing\", \"index\": 13}]"
}

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.

Authorizations

Authorization

string

header

required

Body

multipart/form-data

Option 1
Option 2

audio_url

string

required

Input audio URL (supported format: YouTube URL).

Example:

"https://bucket.s3.amazonaws.com/audio.mp3"

prompt

string

required

Description of the singing style, tone, or genre.

Example:

"Sing emotional vocals over a soft piano instrumental."

lyrics

string

required

The lyrics to be sung over the instrumental.

Maximum string length: 2000

Example:

"Never mind I'll find someone like you..."

audio_file

file

Uploaded instrumental audio file.

gender

enum<string>

Voice gender to guide generation.

Available options:

male,

female,

neutral

Example:

"female"

title

string

Title of the generated music track

generate_album_cover

boolean

default:false

Whether to generate an album cover for the generated audio

lyrics_timestamps

boolean

default:false

Whether to generate timestamps for the lyrics

webhook_url

string

Callback URL to receive status updates or final audio result.

Example:

"https://yourdomain.com/webhook"

Response

Successfully initiated Sing Over Instrumental task

success

boolean

message

string

task_id

string

conversion_id_1

string

conversion_id_2

string

is_flagged

boolean

reason

string

eta

integer

Estimated processing time in seconds

status

string

credit_estimate

number<float>

error_message

string

error_message_detail

string

missing_input_fields

string

predicted_user_intent

string

⌘I

API Documentation

Utilities

Resources

Keep in mind

Features

Sample Request Endpoints

Helper Endpoints

Conversion Endpoints

Endpoint

Request Parameters

Sample Output

Try it Yourself

Webhook Delivery

Standard Requests (non-instrumental):

Sample Request

cURL

Python

Sample Response

Success (200 OK)

Webhook Sample Payload

Common Errors

Authorizations

Body

Response

​Endpoint

​Request Parameters

​Sample Output

​Try it Yourself

​Webhook Delivery

​Standard Requests (non-instrumental):

​Sample Request

​cURL

​Python

​Sample Response

​Success (200 OK)

​Webhook Sample Payload

​Common Errors

Authorizations

Body

Response

Endpoint

Request Parameters

Sample Output

Try it Yourself

Webhook Delivery

Standard Requests (non-instrumental):

Sample Request

cURL

Python

Sample Response

Success (200 OK)

Webhook Sample Payload

Common Errors