Skip to main content
POST
/
api
/
v1
/
generate
/
add-instrumental
Add Instrumental
curl --request POST \
  --url https://api.api.box/api/v1/generate/add-instrumental \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrl": "https://example.com/music.mp3",
  "title": "Relaxing Piano",
  "negativeTags": "Heavy Metal, Aggressive Drums",
  "tags": "Relaxing Piano, Ambient, Peaceful",
  "callBackUrl": "https://api.example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "model": "V4_5PLUS"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Key Capabilities

  • Accepts uploadUrl of an existing audio file (usually vocals or stems).
  • Supports fine-grained customization via parameters such as:
    • tags and negativeTags (musical style controls)
    • styleWeight, audioWeight, weirdnessConstraint (stylistic & creative blending)
    • vocalGender, title, callBackUrl for metadata & workflow control  .
  • Returns a taskId for tracking, and results are retained for 14 days. Callback workflow includes three stages: text, first, and complete  .

​
Typical Use Cases

  • Singers or melody writers who want instant fuller arrangements around their vocal inputs.
  • Applications like karaoke platforms, demo-generation tools, or co-creation interfaces that allow users to experiment with accompaniment styles easily.

​
Parameter Details

  • Required fields: uploadUrl, title, negativeTags, tags, callBackUrl
  • Upload URL: Must be a valid, publicly accessible audio file URL
  • Title: Used as the title for the generated instrumental track
  • Tags: Describe the desired style, mood, and instruments for the instrumental track
  • Negative Tags: Music styles or traits to exclude from the generated instrumental

​
Optional parameters

The following fields are optional controls available for this endpoint:
  • vocalGender (string): Preferred vocal gender for any vocal elements. 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)
  • model (string): Model version used for generation. Allowed values: V4_5PLUS (default), V5

​
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 Instrumental 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
​
uploadUrl
string<uri>
required

The URL of the uploaded music file to add instrumental 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/music.mp3"

​
title
string
required

The title of the music track.

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

"Relaxing Piano"

​
negativeTags
string
required

Music styles or traits to exclude from the generated instrumental.

  • Required.
  • Use to avoid specific styles or instruments in the instrumental version.
    Example: "Heavy Metal, Aggressive Drums"
Example:

"Heavy Metal, Aggressive Drums"

​
tags
string
required

Music style and characteristics for the instrumental.

  • Required.
  • Describe the desired style, mood, and instruments for the instrumental track.
    Example: "Relaxing Piano, Ambient, Peaceful"
Example:

"Relaxing Piano, Ambient, Peaceful"

​
callBackUrl
string<uri>
required

The URL to receive task completion notifications when instrumental 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 Instrumental Callbacks

  • Alternatively, you can use the Get Music Generation Details interface to poll task status
Example:

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

​
vocalGender
enum<string>

Preferred vocal gender for any vocal elements. 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

​
model
enum<string>
default:V4_5PLUS

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

Available options:
V4_5PLUS,
V5
Example:

"V4_5PLUS"

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