Add Instrumental
This endpoint generates a musical accompaniment tailored to an uploaded audio file — typically a vocal stem or melody track. It helps users instantly flesh out their vocal ideas with high-quality backing music, all without needing a producer.
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
uploadUrlspecifies the audio file URL to be processedtitlespecifies the title for the generated musicmodelspecifies the AI model version for generationtagsandnegativeTagsare used to control music style- Supports various optional parameters for fine-tuning generation effects
Developer Notes
- Generated files will be retained for 14 days
- Callback process has three stages:
text(text generation),first(first track completed),complete(all completed)
Rate limits and quotas are enforced by Apikley and may differ from upstream providers.
OpenAPI
suno-api/suno-api.json post /api/v1/generate/add-instrumental
openapi: 3.0.0
info:
title: Suno API
description: Apikley Suno API Documentation
version: 1.0.0
contact:
name: Technical Support
email: support@apikley.ru
servers:
- url: https://api.apikley.ru
description: API Server
security:
- BearerAuth: []
paths:
/api/v1/generate/add-instrumental:
post:
summary: Add Instrumental to Music
description: >-
Generate instrumental accompaniment based on uploaded audio files. This
interface allows you to upload audio files and add instrumental tracks
to them.
### Usage Guide
- Use this interface to add instrumental tracks to existing audio
- Supports generation of various music style accompaniments
- Allows customization of style, exclusion of specific elements, etc.
### Parameter Details
- `uploadUrl` specifies the audio file URL to be processed
- `title` specifies the title for the generated music
- `tags` and `negativeTags` are used to control music style
- Supports various optional parameters for fine-tuning generation
effects
### Developer Notes
- Generated files will be retained for 14 days
- Callback process has three stages: `text` (text generation), `first`
(first track completed), `complete` (all completed)
operationId: add-instrumental
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- title
- negativeTags
- tags
- callBackUrl
properties:
uploadUrl:
type: string
format: uri
description: >-
URL of the uploaded audio file. Specifies the source audio
file location for adding accompaniment.
example: https://example.com/music.mp3
model:
type: string
description: |-
The AI model version to use for generation.
- Available options:
- **`V5`**: Superior musical expression, faster generation.
- **`V4_5PLUS`**: V4.5+ is richer sound, new ways to create.
enum:
- V4_5PLUS
- V5
default: V4_5PLUS
example: V4_5PLUS
title:
type: string
description: >-
Title of the generated music. Will be displayed in the
player interface and file name.
example: Relaxing Piano
negativeTags:
type: string
description: >-
Music styles or characteristics to exclude from the
generated audio. Used to avoid specific unwanted music
elements.
example: heavy metal, fast drums
tags:
type: string
description: >-
Music styles or tags to include in the generated music.
Defines the desired music style and characteristics.
example: relaxing, piano, soothing
callBackUrl:
type: string
format: uri
description: >-
URL address for receiving instrumental generation task
completion updates. This parameter is required for all
instrumental generation requests.
- The system will send a POST request to this URL when
instrumental generation is completed, including task status
and results
- Callback process has three stages: `text` (text
generation), `first` (first track completed), `complete`
(all completed)
- Your callback endpoint should be able to accept POST
requests containing JSON payloads with music generation
results
- Alternatively, you can use the get music details interface
to poll task status
example: https://example.com/callback
vocalGender:
type: string
description: >-
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.
enum:
- m
- f
example: m
styleWeight:
type: number
description: >-
Adherence strength to specified style. Optional. Range 0–1,
up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.61
weirdnessConstraint:
type: number
description: >-
Controls experimental/creative deviation level. Optional.
Range 0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.72
audioWeight:
type: number
description: >-
Relative weight of audio elements. Optional. Range 0–1, up
to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: >-
Response status code
- **200**: Success - Request processed successfully
- **401**: Unauthorized - Authentication credentials
missing or invalid
- **402**: Insufficient credits - Account does not
have enough credits to perform this operation
- **404**: Not found - Requested resource or endpoint
does not exist
- **409**: Conflict - WAV record already exists
- **422**: Validation error - Request parameters
failed validation checks
- **429**: Rate limit exceeded - Request limit for
this resource has been exceeded
- **451**: Unauthorized - Failed to retrieve image.
Please verify any access restrictions set by you or
your service provider.
- **455**: Service unavailable - System currently
undergoing maintenance
- **500**: Server error - Unexpected error occurred
while processing request
msg:
type: string
description: Error message when code != 200
example: success
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: >-
Task ID for tracking task status. You can use this
ID to query task details and results through the
"Get Music Details" interface.
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioGenerated:
'{request.body#/callBackUrl}':
post:
description: >-
When instrumental 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
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Status code
example: 200
msg:
type: string
description: Return message
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
Callback type: text (text generation completed),
first (first track completed), complete (all
completed)
enum:
- text
- first
- complete
task_id:
type: string
description: Task ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: Audio unique identifier (audioId)
audio_url:
type: string
description: Audio file URL
stream_audio_url:
type: string
description: Streaming audio URL
image_url:
type: string
description: Cover image URL
prompt:
type: string
description: Generation prompt/lyrics
model_name:
type: string
description: Model name used
title:
type: string
description: Music title
tags:
type: string
description: Music tags
createTime:
type: string
description: Creation time
format: date-time
duration:
type: number
description: Audio duration (seconds)
responses:
'200':
description: Callback received successfully
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: >-
Response status code
- **200**: Success - Request processed
successfully
- **400**: Validation error - Lyrics contain
copyrighted content.
- **408**: Rate limit exceeded - Timeout.
- **413**: Conflict - Uploaded audio matches
existing artwork.
- **500**: Server error - Unexpected error
occurred while processing request
- **501**: Audio generation failed.
- **531**: Server error - Sorry, generation
failed due to issues. Your credits have been
refunded. Please try again.
msg:
type: string
description: Error message when code != 200
example: success
example:
code: 200
msg: success
components:
responses:
Error:
description: Server Error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
All APIs require authentication via Bearer Token.
Get API Key:
1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
API Key
Usage:
Add to request header:
Authorization: Bearer APIKLEY_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
in the management page
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt