curl --request POST \
--url https://apibox.erweima.ai/api/v1/generate/add-vocals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Relaxing Piano with Vocals",
"negativeTags": "Heavy Metal, Aggressive Vocals",
"style": "Jazz",
"uploadUrl": "https://example.com/instrumental.mp3",
"callBackUrl": "https://api.example.com/callback",
"prompt": "A calm and relaxing piano track with soothing vocals",
"lyrics": "[Chorus] Brighter lights, we keep going on",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"model": "V6",
"variety": 1
}
'import requests
url = "https://apibox.erweima.ai/api/v1/generate/add-vocals"
payload = {
"title": "Relaxing Piano with Vocals",
"negativeTags": "Heavy Metal, Aggressive Vocals",
"style": "Jazz",
"uploadUrl": "https://example.com/instrumental.mp3",
"callBackUrl": "https://api.example.com/callback",
"prompt": "A calm and relaxing piano track with soothing vocals",
"lyrics": "[Chorus] Brighter lights, we keep going on",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"model": "V6",
"variety": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: 'Relaxing Piano with Vocals',
negativeTags: 'Heavy Metal, Aggressive Vocals',
style: 'Jazz',
uploadUrl: 'https://example.com/instrumental.mp3',
callBackUrl: 'https://api.example.com/callback',
prompt: 'A calm and relaxing piano track with soothing vocals',
lyrics: '[Chorus] Brighter lights, we keep going on',
vocalGender: 'm',
styleWeight: 0.61,
weirdnessConstraint: 0.72,
audioWeight: 0.65,
model: 'V6',
variety: 1
})
};
fetch('https://apibox.erweima.ai/api/v1/generate/add-vocals', 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://apibox.erweima.ai/api/v1/generate/add-vocals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Relaxing Piano with Vocals',
'negativeTags' => 'Heavy Metal, Aggressive Vocals',
'style' => 'Jazz',
'uploadUrl' => 'https://example.com/instrumental.mp3',
'callBackUrl' => 'https://api.example.com/callback',
'prompt' => 'A calm and relaxing piano track with soothing vocals',
'lyrics' => '[Chorus] Brighter lights, we keep going on',
'vocalGender' => 'm',
'styleWeight' => 0.61,
'weirdnessConstraint' => 0.72,
'audioWeight' => 0.65,
'model' => 'V6',
'variety' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://apibox.erweima.ai/api/v1/generate/add-vocals"
payload := strings.NewReader("{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apibox.erweima.ai/api/v1/generate/add-vocals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apibox.erweima.ai/api/v1/generate/add-vocals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}Add Vocals
This endpoint layers AI-generated vocals on top of an existing instrumental. Given a prompt (e.g., lyrical concept or musical mood) and optional audio, it produces vocal output harmonized with the provided track.
curl --request POST \
--url https://apibox.erweima.ai/api/v1/generate/add-vocals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Relaxing Piano with Vocals",
"negativeTags": "Heavy Metal, Aggressive Vocals",
"style": "Jazz",
"uploadUrl": "https://example.com/instrumental.mp3",
"callBackUrl": "https://api.example.com/callback",
"prompt": "A calm and relaxing piano track with soothing vocals",
"lyrics": "[Chorus] Brighter lights, we keep going on",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"model": "V6",
"variety": 1
}
'import requests
url = "https://apibox.erweima.ai/api/v1/generate/add-vocals"
payload = {
"title": "Relaxing Piano with Vocals",
"negativeTags": "Heavy Metal, Aggressive Vocals",
"style": "Jazz",
"uploadUrl": "https://example.com/instrumental.mp3",
"callBackUrl": "https://api.example.com/callback",
"prompt": "A calm and relaxing piano track with soothing vocals",
"lyrics": "[Chorus] Brighter lights, we keep going on",
"vocalGender": "m",
"styleWeight": 0.61,
"weirdnessConstraint": 0.72,
"audioWeight": 0.65,
"model": "V6",
"variety": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: 'Relaxing Piano with Vocals',
negativeTags: 'Heavy Metal, Aggressive Vocals',
style: 'Jazz',
uploadUrl: 'https://example.com/instrumental.mp3',
callBackUrl: 'https://api.example.com/callback',
prompt: 'A calm and relaxing piano track with soothing vocals',
lyrics: '[Chorus] Brighter lights, we keep going on',
vocalGender: 'm',
styleWeight: 0.61,
weirdnessConstraint: 0.72,
audioWeight: 0.65,
model: 'V6',
variety: 1
})
};
fetch('https://apibox.erweima.ai/api/v1/generate/add-vocals', 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://apibox.erweima.ai/api/v1/generate/add-vocals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Relaxing Piano with Vocals',
'negativeTags' => 'Heavy Metal, Aggressive Vocals',
'style' => 'Jazz',
'uploadUrl' => 'https://example.com/instrumental.mp3',
'callBackUrl' => 'https://api.example.com/callback',
'prompt' => 'A calm and relaxing piano track with soothing vocals',
'lyrics' => '[Chorus] Brighter lights, we keep going on',
'vocalGender' => 'm',
'styleWeight' => 0.61,
'weirdnessConstraint' => 0.72,
'audioWeight' => 0.65,
'model' => 'V6',
'variety' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://apibox.erweima.ai/api/v1/generate/add-vocals"
payload := strings.NewReader("{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apibox.erweima.ai/api/v1/generate/add-vocals")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apibox.erweima.ai/api/v1/generate/add-vocals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"Relaxing Piano with Vocals\",\n \"negativeTags\": \"Heavy Metal, Aggressive Vocals\",\n \"style\": \"Jazz\",\n \"uploadUrl\": \"https://example.com/instrumental.mp3\",\n \"callBackUrl\": \"https://api.example.com/callback\",\n \"prompt\": \"A calm and relaxing piano track with soothing vocals\",\n \"lyrics\": \"[Chorus] Brighter lights, we keep going on\",\n \"vocalGender\": \"m\",\n \"styleWeight\": 0.61,\n \"weirdnessConstraint\": 0.72,\n \"audioWeight\": 0.65,\n \"model\": \"V6\",\n \"variety\": 1\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}Model Versions
- Current models:
V6(default),V6_WILD,V6_MINI - Deprecated models:
V5_5,V5,V4_5PLUS,V4_5ALL,V4_5,V4 - Deprecated values remain available only for backward compatibility. New integrations should use a V6-series model.
Key Capabilities
- Accepts an existing instrumental via uploadUrl, with optional prompt-based stylistic input.
- Supports control parameters including:
- prompt, style, tags, negativeTags (define lyrical content and vocal style)
- vocalGender, styleWeight, weirdnessConstraint, audioWeight, callBackUrl .
- Returns a taskId, supports the same 14-day retention and three-stage callback model as the instrumental endpoint .
Typical Use Cases
- Music platforms or tools enabling topline creation and rapid prototyping of lyrical ideas.
- Collaborative songwriting or co-creation workflows, where lyrics or vocal styles are iteratively tested over instrumental drafts.
Parameter Details
- Required fields:
uploadUrl,callBackUrl,title,negativeTags,style. All other fields are optional. - Upload URL: Must be a valid, publicly accessible audio file URL. Source audio is enough to generate.
- Style: Describes the overall genre and vocal approach (Jazz, Classical, Electronic, Pop)
- Negative Tags: Music styles or vocal traits to exclude from generation
- Title: Used as the title for the generated vocal track
- Lyrics: Optional. Lyrics for the generated vocals. For V6, V6_WILD, and V6_MINI: maximum 5000 characters
- Prompt: Optional. Describes the desired vocal style and content
Optional parameters
- lyrics (string): Lyrics for the generated vocals. Optional. For V6, V6_WILD, and V6_MINI: maximum 5000 characters.
- prompt (string): Description of the audio content to generate vocals for. Optional.
- vocalGender (string): Preferred vocal gender. Allowed values:
m(male),f(female) - styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
- weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
- audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
- variety (integer): Diversity of generated results. Integer from 0–4, default 1.
0off,1normal (default),2high,3extra,4max. - model (string): Model version used for generation. Current values:
V6(default),V6_WILD,V6_MINI. Deprecated:V5_5,V5,V4_5PLUS,V4_5ALL,V4_5,V4.
Developer Notes
- Callback process has three stages:
text(text generation),first(first track complete),complete(all tracks complete) - In some cases,
textandfirststages may be skipped, directly returningcomplete - See Add Vocals Callbacks for detailed callback format
- Monitor task progress using Get Music Generation Details
Authorizations
🔑 API Authentication
All endpoints require authentication using Bearer Token.
Get API Key
- Visit the API Key Management Page to obtain your API Key
Usage
Add to request headers:
Authorization: Bearer YOUR_API_KEY
⚠️ Note:
- Keep your API Key secure and do not share it with others
- If you suspect your API Key has been compromised, reset it immediately from the management page
Body
The title of the music track.
- Required.
- This will be used as the title for the generated vocal track.
"Relaxing Piano with Vocals"
Music styles or vocal traits to exclude from the generated track.
- Required.
- Use to avoid specific vocal styles or characteristics.
Example: "Heavy Metal, Aggressive Vocals"
"Heavy Metal, Aggressive Vocals"
The music and vocal style.
- Required.
- Examples: "Jazz", "Classical", "Electronic", "Pop".
- Describes the overall genre and vocal approach.
"Jazz"
The URL of the uploaded audio file to add vocals to.
- Required.
- Must be a valid audio file URL accessible by the system.
- The uploaded audio should be in a supported format (MP3, WAV, etc.).
"https://example.com/instrumental.mp3"
The URL to receive task completion notifications when vocal generation is complete. The callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete). Note: In some cases, text and first stages may be skipped, directly returning complete.
- For detailed callback format and implementation guide, see Add Vocals Callbacks
- Alternatively, you can use the Get Music Generation Details interface to poll task status
"https://api.example.com/callback"
Description of the audio content to generate vocals for.
- Optional.
- Provides context about the desired vocal style and content.
- The more detailed your prompt, the better the vocal generation will match your vision.
"A calm and relaxing piano track with soothing vocals"
Lyrics for the generated vocals. Optional. Source audio (uploadUrl) alone is enough to generate.
- V6, V6_WILD & V6_MINI: Maximum 5000 characters
"[Chorus] Brighter lights, we keep going on"
Preferred vocal gender. Optional. Allowed values: 'm' (male), 'f' (female).
m, f "m"
Style adherence weight. Optional. Range: 0-1. Two decimal places recommended.
0 <= x <= 1Must be a multiple of 0.010.61
Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.
0 <= x <= 1Must be a multiple of 0.010.72
Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.
0 <= x <= 1Must be a multiple of 0.010.65
AI model version. Default: V6.
V6: Current standard model and recommended default.V6_WILD: Current model for more experimental and creative results.V6_MINI: Current lightweight model.- Deprecated:
V5_5,V5,V4_5PLUS,V4_5ALL,V4_5, andV4. These values remain listed only for backward compatibility; use a V6-series model for new integrations.
V6, V6_WILD, V6_MINI, V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4 "V6"
Diversity of generated results. Optional. Integer from 0 to 4. Default: 1.
0: off — variety off, strictly the same style1: normal — default, balances stability and diversity2: high — results with clearly different styles3: extra — higher variation, bolder exploration4: max — maximum variation
0 <= x <= 4Must be a multiple of 11
Callbacks
Response
Request successful
Status Codes
- ✅ 200 - Request successful
- ⚠️ 400 - Invalid parameters
- ⚠️ 401 - Unauthorized access
- ⚠️ 404 - Invalid request method or path
- ⚠️ 405 - Rate limit exceeded
- ⚠️ 413 - Theme or prompt too long
- ⚠️ 429 - Insufficient credits
- ⚠️ 430 - Your call frequency is too high. Please try again later.
- ⚠️ 455 - System maintenance
- ❌ 500 - Server error
200, 400, 401, 404, 405, 413, 429, 430, 455, 500 200
Error message when code != 200
"success"
Show child attributes
Show child attributes
