Skip to main content
POST
Add Vocals

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:
    • lyrics, prompt, style, tags, negativeTags (define lyrical content and vocal style)
    • vocalGender, styleWeight, weirdnessConstraint, audioWeight, variety, 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

  • A source audio (uploadUrl) is enough to start generation together with the required fields below. Remaining fields are optional.
  • Required fields: uploadUrl, callBackUrl, title, negativeTags, style
  • Upload URL: Must be a valid, publicly accessible audio file URL
  • 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

Optional parameters

The following fields are optional controls available for this endpoint:
  • lyrics (string): Lyrics content. Optional. V6 series maximum 5000 characters. Takes priority over prompt as lyrics.
  • prompt (string): Lyrics content. Optional. Used as lyrics when lyrics is not provided. V6 series maximum 5000 characters.
  • 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 (number): Diversity of generated results. Integer from 0–4, default 1. 0 off, 1 normal (default), 2 high, 3 extra, 4 max.
  • 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, text and first stages may be skipped, directly returning complete
  • See Add Vocals Callbacks for detailed callback format
  • Monitor task progress using Get Music Generation Details

Authorizations

Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

⚠️ 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

application/json
title
string
required

The title of the music track.

  • Required.
  • This will be used as the title for the generated vocal track.
Example:

"Relaxing Piano with Vocals"

negativeTags
string
required

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"
Example:

"Heavy Metal, Aggressive Vocals"

style
string
required

The music and vocal style.

  • Required.
  • Examples: "Jazz", "Classical", "Electronic", "Pop".
  • Describes the overall genre and vocal approach.
Example:

"Jazz"

uploadUrl
string<uri>
required

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.).
Example:

"https://example.com/instrumental.mp3"

callBackUrl
string<uri>
required

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
Example:

"https://api.example.com/callback"

prompt
string

Lyrics content. Optional. Used as lyrics when lyrics is not provided. If lyrics is also provided, lyrics takes priority. For V6, V6_MINI, and V6_WILD: maximum 5000 characters.

Example:

"A calm and relaxing piano track with soothing vocals"

lyrics
string

Lyrics for the generated audio. Optional. For V6, V6_MINI, and V6_WILD: maximum 5000 characters. Takes priority over prompt as lyrics. If omitted, prompt is used as lyrics.

Example:

"[Verse] Night city lights shining bright"

vocalGender
enum<string>

Preferred vocal gender. Optional. Allowed values: 'm' (male), 'f' (female).

Available options:
m,
f
Example:

"m"

styleWeight
number

Style adherence weight. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.61

weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.72

audioWeight
number

Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

variety
number
default:1

Controls the diversity and stylistic variation of generated results. Optional. Integer from 0–4, default 1.

  • 0: off (exact style) — fully off, strictly the same style
  • 1: normal (balanced variety) — default, balances stability and diversity
  • 2: high (distinct styles) — produces results with clearly different styles
  • 3: extra (bold exploration) — higher variation, encourages bold exploration of different styles
  • 4: max (unreasonably varied) — maximum diversity; results may differ in style very significantly
Required range: 0 <= x <= 4Must be a multiple of 1
Example:

1

model
enum<string>
default:V6

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, and V4. These values remain listed only for backward compatibility; use a V6-series model for new integrations.
Available options:
V6,
V6_WILD,
V6_MINI,
V5_5,
V5,
V4_5PLUS,
V4_5ALL,
V4_5,
V4
Example:

"V6"

Callbacks

POST
{request.body#/callBackUrl}vocalsAdded

Body

application/json
code
integer

Status code

Example:

200

msg
string

Response message

Example:

"All generated successfully"

data
object

Response

200

Callback received successfully

Response

Request successful

code
enum<integer>

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
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

msg
string

Error message when code != 200

Example:

"success"

data
object