POST
/
api
/
v1
/
generate
/
add-vocals
{
  "uploadUrl": "https://example.com/instrumental.mp3",
  "callBackUrl": "https://api.example.com/callback",
  "prompt": "A calm and relaxing piano track with soothing vocals",
  "title": "Relaxing Piano with Vocals",
  "negativeTags": "Heavy Metal, Aggressive Vocals",
  "style": "Jazz",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
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, prompt, 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:
  • 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)
{
  "uploadUrl": "https://example.com/instrumental.mp3",
  "callBackUrl": "https://api.example.com/callback",
  "prompt": "A calm and relaxing piano track with soothing vocals",
  "title": "Relaxing Piano with Vocals",
  "negativeTags": "Heavy Metal, Aggressive Vocals",
  "style": "Jazz",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

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

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

application/json

Response

200
application/json

Request successful

The response is of type object.