Add Vocals to Music

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Document updated

If you have already completed the integration process previously, you can still access the old version document at: Old version address (https://ai.modelfold.online/docs/en/suno-api/add-vocals)

Generate music with vocals based on uploaded audio files. This interface allows you to upload audio files and add vocal singing to them.

Usage Guide

Use this interface to add vocal singing to existing audio
Supports custom lyric content and singing styles
Allows control of vocal gender, style weight, and other parameters
With source audio (upload_url), generation can proceed; title, negative_tags, and style are required, and all other fields are optional

Parameter Details

Always required: upload_url, title, negative_tags, style
upload_url specifies the source audio file URL to be processed
title specifies the title for the generated music
style and negative_tags are used to control music and vocal style
lyrics is optional. V6 maximum 5000 characters. If omitted, prompt is used as lyrics when provided
Optional fine-tuning: prompt, model, vocal_gender, style_weight, weirdness_constraint, audio_weight, variety

Developer Notes

Generated files will be retained for 14 days
Callbacks may be sent at the text, first and complete stages; only complete is guaranteed. Treat complete as the final result.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name to use for generation. Required field. 示例：`ai-music-api/add-vocals`。
`callBackUrl`	`string`	No	The URL to receive generation task completion updates. Optional but recommended for production use. - System will POST task status and results to this URL when generation completes - Callback includes generated content URLs and task information - Your callback endpoint should accept POST requests with JSON payload containing results - Alternatively, poll GET /api/v1/jobs/recordInfo?taskId=... (see Get Task Details). For Suno audio tasks the tracks are in data.response.data[] (audio_url, stream_audio_url, image_url, id, duration). - To ensure callback security, see Webhook Verification Guide for signature verification implementation
`input`	`object`	Yes	Input parameters for the generation task
`input.prompt`	`string`	No	Prompt for generating audio. Optional. - Used as lyrics only when `lyrics` is not provided. If `lyrics` is present, `prompt` is not used as lyrics. - V6, V6_MINI, and V6_WILD: Maximum 5000 characters. 示例：`A calm and relaxing piano track.`。
`input.model`	`string`	No	The AI model version to use for generation. - Available options: - `V6_WILD`: Pushes creative boundaries for bolder, more distinctive musical expression. - `V6_MINI`: Lightweight and fast, balancing quality and speed for effortless creation. - `V6`: Greater musical expression with more natural vocals and richer details. - `V5_5` (Discontinued): Custom Models Tailored to Your Unique Taste. - `V5` (Discontinued): Superior musical expression, faster generation. - `V4_5PLUS` (Discontinued): V4.5+ is richer sound, new ways to create. Default：`"V6"`。 Allowed values：`V4_5PLUS` / `V5` / `V5_5` / `V6` / `V6_MINI` / `V6_WILD`。示例：`V6`。
`input.title`	`string`	Yes	Music title. Required. Will be displayed in the player interface and file name. 示例：`Relaxing Piano`。
`input.negative_tags`	`string`	Yes	Excluded music styles. Required. Used to avoid including specific styles or elements in the generated music. 示例：`heavy metal, strong drum beats`。
`input.style`	`string`	Yes	Music style. Required. Such as jazz, electronic, classical and other music types. 示例：`Jazz`。
`input.vocal_gender`	`string`	No	Vocal gender preference. Optional. 'm' for male, 'f' for female. Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions. Allowed values：`m` / `f`。示例：`m`。
`input.style_weight`	`number`	No	Adherence strength to specified style. Optional. Range 0–1, up to 2 decimal places. 示例：`0.61`。
`input.weirdness_constraint`	`number`	No	Controls experimental/creative deviation level. Optional. Range 0–1, up to 2 decimal places. 示例：`0.72`。
`input.audio_weight`	`number`	No	Relative weight of audio elements. Optional. Range 0–1, up to 2 decimal places. 示例：`0.65`。
`input.upload_url`	`string`	Yes	URL of the uploaded audio file. Required. Source audio (`upload_url`) is enough to generate once `title`, `negative_tags`, and `style` are provided. 示例：`https://example.com/music.mp3`。
`input.lyrics`	`string`	No	Lyrics for the generated audio. Optional. - Takes priority over `prompt` as lyrics. If omitted, `prompt` is used as lyrics when provided. - V6, V6_MINI, and V6_WILD: Maximum 5000 characters. - Not required. Source audio (`upload_url`) is enough to generate once `title`, `negative_tags`, and `style` are provided. 示例：`[Verse]\nKeep the melody flowing\nInto a gentle bridge\n[Chorus]\nLet the piano rise and fall`。
`input.variety`	`integer`	No	Controls the diversity and stylistic variation of generated results. Optional. Integer range 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 Default：`1`。示例：`1`。

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ai-music-api/add-vocals",
  "callBackUrl": "https://example.com/callback",
  "input": {
    "prompt": "A calm and relaxing piano track.",
    "title": "Relaxing Piano",
    "negative_tags": "heavy metal, strong drum beats",
    "style": "Jazz",
    "upload_url": "https://example.com/music.mp3",
    "model": "V6",
    "vocal_gender": "m",
    "style_weight": 0.61,
    "weirdness_constraint": 0.72,
    "audio_weight": 0.65,
    "lyrics": "[Verse]\nKeep the melody flowing\nInto a gentle bridge\n[Chorus]\nLet the piano rise and fall",
    "variety": 1
  }
}'

json

{
  "model": "ai-music-api/add-vocals",
  "callBackUrl": "https://example.com/callback",
  "input": {
    "prompt": "A calm and relaxing piano track.",
    "title": "Relaxing Piano",
    "negative_tags": "heavy metal, strong drum beats",
    "style": "Jazz",
    "upload_url": "https://example.com/music.mp3",
    "model": "V6",
    "vocal_gender": "m",
    "style_weight": 0.61,
    "weirdness_constraint": 0.72,
    "audio_weight": 0.65,
    "lyrics": "[Verse]\nKeep the melody flowing\nInto a gentle bridge\n[Chorus]\nLet the piano rise and fall",
    "variety": 1
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `401` / `402` / `404` / `409` / `422` / `429` / `451` / `455` / `500`。示例：`200`。
`msg`	`string`	否	Error message when code != 200 示例：`success`。
`data`	`object`	否	—
`data.taskId`	`string`	否	Task ID for tracking task status. Poll GET /api/v1/jobs/recordInfo?taskId=... (see Get Task Details). For Suno audio tasks the tracks are in data.response.data[] (audio_url, stream_audio_url, image_url, id, duration). 示例：`5c79****be8e`。

json

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

Callback

audioGenerated

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

When vocal generation is completed, the system will call this callback to notify the results.

Callback Example

json

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v4-5",
        "title": "Iron Man",
        "tags": "electrifying, rock",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	否	Status code 示例：`200`。
`msg`	`string`	否	Return message 示例：`All generated successfully`。
`data`	`object`	否	—
`data.callbackType`	`string`	否	Callback type: text (text generation completed), first (first track completed), complete (all completed) Allowed values：`text` / `first` / `complete`。示例：`text`。
`data.task_id`	`string`	否	Task ID
`data.data`	`array<object>`	否	—
`data.data[].id`	`string`	否	Audio unique identifier (audioId)
`data.data[].audio_url`	`string`	否	Audio file URL
`data.data[].stream_audio_url`	`string`	否	Streaming audio URL
`data.data[].image_url`	`string`	否	Cover image URL
`data.data[].prompt`	`string`	否	Generation prompt/lyrics
`data.data[].model_name`	`string`	否	Model name used
`data.data[].title`	`string`	否	Music title
`data.data[].tags`	`string`	否	Music tags
`data.data[].createTime`	`string`	否	Creation time
`data.data[].duration`	`number`	否	Audio duration (seconds)

json

{
  "code": 200,
  "msg": "All generated successfully",
  "data": {
    "callbackType": "text",
    "task_id": "",
    "data": [
      {
        "id": "",
        "audio_url": "https://your-domain.com/input.png",
        "stream_audio_url": "https://your-domain.com/input.png",
        "image_url": "https://your-domain.com/input.png",
        "prompt": "A serene mountain landscape at sunrise",
        "model_name": "model-name",
        "title": "",
        "tags": "",
        "createTime": "",
        "duration": 0
      }
    ]
  }
}

Add Vocals to Music ​

Endpoint ​

Usage Guide ​

Parameter Details ​

Developer Notes ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

audioGenerated ​

Callback Example ​

Add Vocals to Music

Endpoint

Usage Guide

Parameter Details

Developer Notes

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

audioGenerated

Callback Example