Music GenerationtaskType: add_instrumental30 Credits / Task

Add Instrumental to Music

Generate rich musical instrumentation, rhythm sections, and harmonic accompaniment beneath an existing acapella vocal recording. The model intelligently synchronizes tempo, chord progressions, and dynamics to elevate the vocal performance.

POST/api/v1/createTask

Test in Playground

Usage Guide & Overview

Four Required Parameters: You must provide upload_url, title, tags, and negative_tags.
Source Audio Input: upload_url must be a direct, publicly accessible audio file (MP3 or WAV) containing vocal or singing tracks.
Arrangement Tags: Use tags (or style) to dictate the specific instruments, genre style, and tempo vibes you desire.
Negative Constraints: Use negative_tags to prevent unwanted sonic artifacts, excessive distortion, or clashing genre traits.
File Retention: Output audio files remain accessible for 14 days on the high-speed CDN.

Supported AI Models

High Fidelity

V6DEFAULT

Deep instrumental harmonization, authentic acoustic resonance, and intelligent cadence matching.

V6_MINI

Optimized lightweight accompaniment generator for high-velocity creation.

V6_WILD

Bold, boundary-pushing arrangements and unique sonic textures.

Validation Rules & Constraints

Required Input Parameters

upload_url: Must be a direct URL to a valid audio file (HTTP/HTTPS).
title: Required, up to 100 characters.
tags: Required instrumentation style tags (up to 1,000 characters).
negative_tags: Required exclusion keywords.

Harmonic Synchronicity & Phrasing

Providing lyrics helps the AI align chord changes with semantic emotional beats.
Maximum 5,000 characters for lyrics on V6, V6_MINI, and V6_WILD.
If lyrics is omitted, the AI derives timing purely from spectral audio analysis.

Fine-Tuning & Balance Controls

audio_weight: Regulates how tightly the backing music follows the vocal tempo (0.0 ~ 1.0).
style_weight: Controls the dominance of requested instruments in the mix (0.0 ~ 1.0).
variety: Integer range 0 to 4 (0: tight adherence to style, 1: balanced default, 4: wide creative freedom).

Authentication & Headers

Header	Requirement	Description
Authorization	required	Bearer YOUR_API_KEY Secret Key generated from dashboard
Content-Type	required	application/json Request payload format

Header

Requirement

Description

Authorization

required

Bearer YOUR_API_KEY

Secret Key generated from dashboard

Content-Type

required

application/json

Request payload format

Request Body Schema

14 fields

upload_urlstringrequired

Publicly accessible direct URL of the source vocal or acapella audio file (MP3, WAV) to generate backing instrumentation for.

titlestringrequired

Title for the generated music track (max 100 characters). Displayed in player interfaces and filenames.

tagsstringrequired

Musical styles, genres, or instrumentation keywords to generate under the vocals (e.g. "Acoustic Guitar, Soft Strings, Ambient Piano"). Also accepts "style".

negative_tagsstringrequired

Instruments, genres, or audio traits to exclude (e.g. "heavy metal, electronic synths, loud drums, brass").

taskTypestringoptional

default:add_instrumental

Task routing identifier. Explicitly set to "add_instrumental" (or "add-instrumental").

modelstringoptional

default:V6

AI generation model. Supported: "V6" (Default, highest fidelity musical arrangement), "V6_MINI" (Fast & lightweight), "V6_WILD" (Experimental), "V4_5PLUS".

lyricsstringoptional

Optional lyrics corresponding to the vocal track, helping the engine better synchronize instrumental phrasing. Max 5,000 characters on V6.

promptstringoptional

Additional stylistic guidance, mood description, or arrangement suggestions. Max 5,000 characters.

callBackUrlstringoptional

Public Webhook URL to receive asynchronous completion notifications when instrumental generation completes.

vocal_genderstringoptional

Vocal gender of source audio: "m" (male) or "f" (female). Informs EQ separation and frequency headroom.

Allowed options:

"m""f"

style_weightnumberoptional

default:0.65

Strength of adherence to specified tags/style (range 0.0 to 1.0, up to 2 decimal places).

weirdness_constraintnumberoptional

default:0.65

Creative/experimental deviation control (range 0.0 to 1.0, up to 2 decimal places).

audio_weightnumberoptional

default:0.65

Relative adherence to original vocal melody and tempo dynamics vs new musical motifs (range 0.0 to 1.0).

varietynumberoptional

default:1

Diversity and stylistic variation: 0 (exact style match), 1 (normal / balanced, default), 2 (high), 3 (extra), 4 (max variation).

Request Sample

curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "add_instrumental",
    "upload_url": "https://example.com/audio/acapella_voice.mp3",
    "title": "Autumn Serenade",
    "tags": "Acoustic Folk, Fingerstyle Guitar, Warm Cello, Subdued Percussion",
    "negative_tags": "heavy metal, electronic synths, autotune, loud brass",
    "model": "V6",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79be8e9f72"
  }
}

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

Instrumental composition structure parsed (callbackType: "text")
First accompanied mix variation completed (callbackType: "first")
All full accompaniment variations completed (callbackType: "complete")
Instrumental synthesis task failed or timed out (code: 400, 408, 500, 501)

Webhook Payload Format

Response Body(200 status)

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "8a92de44c102",
    "data": [
      {
        "id": "c345def0-789a-6123-cdef-0123456789ab",
        "audio_url": "https://cdn.example.com/audio/accompanied_track_1.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/accompanied_stream_1.m3u8",
        "image_url": "https://cdn.example.com/cover/accompanied_cover_1.jpeg",
        "prompt": "Acoustic Folk, Fingerstyle Guitar...",
        "model_name": "chirp-v4-5",
        "title": "Autumn Serenade",
        "createTime": 1786343609818,
        "duration": 194.5,
        "tags": "acoustic folk, fingerstyle guitar, warm cello",
        "source_audio_url": "https://example.com/audio/acapella_voice.mp3",
        "source_image_url": "https://cdn.example.com/cover/source_voice.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/source_voice_stream"
      },
      {
        "id": "d456ef01-89ab-7234-def0-123456789abc",
        "audio_url": "https://cdn.example.com/audio/accompanied_track_2.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/accompanied_stream_2.m3u8",
        "image_url": "https://cdn.example.com/cover/accompanied_cover_2.jpeg",
        "prompt": "Acoustic Folk, Fingerstyle Guitar...",
        "model_name": "chirp-v4-5",
        "title": "Autumn Serenade",
        "createTime": 1786343609818,
        "duration": 194.5,
        "tags": "acoustic folk, fingerstyle guitar, warm cello",
        "source_audio_url": "https://example.com/audio/acapella_voice.mp3",
        "source_image_url": "https://cdn.example.com/cover/source_voice.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/source_voice_stream"
      }
    ]
  }
}

Callback Payload Fields

Field	Type	Description
`code`	integer	Callback status code (200: Success, 400: Invalid params, 408: Timeout, 500: Server error, 501: Task failed)
`msg`	string	Execution status message or error cause details
`data.task_id`	string	Task ID matching the taskId returned from the initial createTask submission
`data.callbackType`	string	Event stage: "text" (arrangement planned), "first" (first mix ready), or "complete" (all variations generated)
`data.data[]`	array	Array of completed audio tracks with newly composed instrumental accompaniment underneath the source vocals
`data.data[].source_audio_url`	string	Original acapella vocal audio URL uploaded by the user

Receiver Implementation Example

Webhook Receiver

// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data) {
    const { callbackType, task_id, data: tracks } = data;
    console.log(`Received ${callbackType} callback for add-instrumental task ${task_id}`);

    if (callbackType === 'complete' && Array.isArray(tracks)) {
      tracks.forEach((track) => {
        console.log(`Complete Accompanied Audio URL: ${track.audio_url}`);
        console.log(`Duration: ${track.duration}s, Original Acapella: ${track.source_audio_url}`);
        // Save full mix track to database...
      });
    }
  } else {
    console.error(`Instrumental generation failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Previous EndpointAdd Vocals to Music Next EndpointBoost Music Style

Ready to integrate Add Instrumental to Music?

Create your free account, obtain your Secret Key, and get 100 free generation credits.

Generate Secret Key