Add Vocals
This endpoint layers AI-generated vocals on top of an existing instrumental. Given a prompt (e.g., lyrical concept or musical mood) and optional audio, it produces vocal output harmonized with the provided track.
Key Capabilities
- Accepts an existing instrumental via uploadUrl, with optional prompt-based stylistic input.
- Supports control parameters including:
- prompt, style, tags, model, negativeTags (define lyrical content and vocal style)
- vocalGender, styleWeight, weirdnessConstraint, audioWeight, callBackUrl .
- Returns a taskId, supports the same 14-day retention and three-stage callback model as the instrumental endpoint .
Typical Use Cases
- Music platforms or tools enabling topline creation and rapid prototyping of lyrical ideas.
- Collaborative songwriting or co-creation workflows, where lyrics or vocal styles are iteratively tested over instrumental drafts.
Parameter Details
uploadUrlspecifies the audio file URL to be processedpromptdefines lyric content and singing stylemodelspecifies the AI model version for generationstyleandnegativeTagsare used to control music and vocal stylenegativeTagsare used to exclude unwanted elements- 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-vocals
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-vocals:
post:
summary: Add Vocals to Music
description: >-
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
### Parameter Details
- `uploadUrl` specifies the audio file URL to be processed
- `prompt` defines lyric content and singing style
- `style` and `negativeTags` are used to control music and vocal 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-vocals
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uploadUrl
- callBackUrl
- prompt
- title
- negativeTags
- style
properties:
prompt:
type: string
description: >-
Prompt for generating audio. Usually text describing audio
content, used to guide vocal singing content and style.
example: A calm and relaxing piano track.
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: >-
Music title. Will be displayed in the player interface and
file name.
example: Relaxing Piano
negativeTags:
type: string
description: >-
Excluded music styles. Used to avoid including specific
styles or elements in the generated music.
example: heavy metal, strong drum beats
style:
type: string
description: >-
Music style. Such as jazz, electronic, classical and other
music types.
example: Jazz
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
uploadUrl:
type: string
format: uri
description: >-
URL of the uploaded audio file. Specifies the source audio
file location for adding vocals.
example: https://example.com/music.mp3
callBackUrl:
type: string
format: uri
description: >-
URL address for receiving vocal generation task completion
updates. This parameter is required for all vocal generation
requests.
- The system will send a POST request to this URL when vocal
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
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 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
}
]
}
}
```
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