Sign in

v1

latestOpenAPI 3.0.02026-07-26355125.0 KB
Music Generation

Add Vocals

post/api/v1/generate/add-vocals

Request body

promptstring required

Description of the audio content to generate vocals for.

  • Required.
  • Provides context about the desired vocal style and content.
  • The more detailed your prompt, the better the vocal generation will match your vision.
titlestring required

The title of the music track.

  • Required.
  • This will be used as the title for the generated vocal track.
negativeTagsstring 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"
stylestring required

The music and vocal style.

  • Required.
  • Examples: "Jazz", "Classical", "Electronic", "Pop".
  • Describes the overall genre and vocal approach.
vocalGender'm' | 'f'

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

styleWeightnumber

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

weirdnessConstraintnumber

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

audioWeightnumber

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

uploadUrlstring 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.).
callBackUrlstring 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
model'V4_5PLUS' | 'V5' | 'V5_5'

Model version to use for generation. Optional. Default: V4_5PLUS.

Example request

{
  "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,
  "uploadUrl": "https://example.com/instrumental.mp3",
  "callBackUrl": "https://api.example.com/callback",
  "model": "V4_5PLUS"
}

Response

Request successful

code200 | 400 | 401 | 404 | 405 | 413 | 429 | 430 | 455 | 500

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
msgstring

Error message when code != 200

Example response

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