> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.box/llms.txt > Use this file to discover all available pages before exploring further. # 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, 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 * **Required fields**: `uploadUrl`, `callBackUrl`, `prompt`, `title`, `negativeTags`, `style` * **Upload URL**: Must be a valid, publicly accessible audio file URL * **Style**: Describes the overall genre and vocal approach (Jazz, Classical, Electronic, Pop) * **Negative Tags**: Music styles or vocal traits to exclude from generation * **Title**: Used as the title for the generated vocal track ### Optional parameters The following fields are optional controls available for this endpoint: * vocalGender (string): Preferred vocal gender. 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`, `V5_5` ### 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 Vocals Callbacks](./add-vocals-callbacks) for detailed callback format * Monitor task progress using [Get Music Generation Details](./get-music-generation-details) ## OpenAPI ````yaml suno-api/suno-api.json POST /api/v1/generate/add-vocals openapi: 3.0.0 info: title: intro description: API documentation for audio generation services version: 1.0.0 contact: name: Technical Support email: support@api.box servers: - url: https://apibox.erweima.ai description: API Server security: - BearerAuth: [] tags: - name: Music Generation description: Endpoints for creating and managing music generation tasks - name: Lyrics Generation description: Endpoints for lyrics generation and management - name: WAV Conversion description: Endpoints for converting music to WAV format - name: Vocal Removal description: Endpoints for vocal removal from music tracks - name: Music Video Generation description: Endpoints for generating MP4 videos from music tracks - name: Account Management description: Endpoints for account and credits management paths: /api/v1/generate/add-vocals: post: tags: - Music Generation summary: Add Vocals operationId: add-vocals requestBody: required: true content: application/json: schema: type: object required: - uploadUrl - callBackUrl - prompt - title - negativeTags - style properties: prompt: type: string description: >- Description of the audio content to generate vocals for. - Required. - Provides context about the desired vocal style and content. - The more detailed your prompt, the better the vocal generation will match your vision. example: A calm and relaxing piano track with soothing vocals title: type: string description: >- The title of the music track. - Required. - This will be used as the title for the generated vocal track. example: Relaxing Piano with Vocals negativeTags: type: string description: >- Music styles or vocal traits to exclude from the generated track. - Required. - Use to avoid specific vocal styles or characteristics. Example: "Heavy Metal, Aggressive Vocals" example: Heavy Metal, Aggressive Vocals style: type: string description: |- The music and vocal style. - Required. - Examples: "Jazz", "Classical", "Electronic", "Pop". - Describes the overall genre and vocal approach. example: Jazz vocalGender: type: string description: >- Preferred vocal gender. Optional. Allowed values: 'm' (male), 'f' (female). enum: - m - f example: m styleWeight: type: number description: >- Style adherence weight. Optional. Range: 0-1. Two decimal places recommended. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.61 weirdnessConstraint: type: number description: >- Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.72 audioWeight: type: number description: >- Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 uploadUrl: type: string format: uri description: >- The URL of the uploaded audio file to add vocals 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/instrumental.mp3 callBackUrl: type: string format: uri description: >- The URL to receive task completion notifications when vocal 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 Vocals Callbacks](https://docs.api.box/suno-api/add-vocals-callbacks) - Alternatively, you can use the Get Music Generation Details interface to poll task status example: https://api.example.com/callback model: type: string description: >- Model version to use for generation. Optional. Default: V4_5PLUS. enum: - V4_5PLUS - V5 - V5_5 default: V4_5PLUS example: V4_5PLUS responses: '200': description: Request successful content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: type: object properties: taskId: type: string description: Task ID for tracking task status example: 5c79****be8e '500': $ref: '#/components/responses/Error' callbacks: vocalsAdded: '{request.body#/callBackUrl}': post: description: >- System will call this callback when vocal generation is complete. ### Callback Example ```json { "code": 200, "msg": "All generated successfully.", "data": { "callbackType": "complete", "task_id": "2fac****9f72", "data": [ { "id": "8551****662c", "audio_url": "https://example.cn/****.mp3", "source_audio_url": "https://example.cn/****.mp3", "stream_audio_url": "https://example.cn/****", "source_stream_audio_url": "https://example.cn/****", "image_url": "https://example.cn/****.jpeg", "source_image_url": "https://example.cn/****.jpeg", "prompt": "[Verse] Calm and relaxing melodies with soothing vocals", "model_name": "chirp-v3-5", "title": "Relaxing Piano with Vocals", "tags": "relaxing, piano, vocals, jazz", "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: Response message example: All generated successfully data: type: object properties: callbackType: type: string description: >- Callback type: text (text generation complete), first (first track complete), complete (all tracks complete) 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 source_audio_url: type: string description: Original audio file URL stream_audio_url: type: string description: Streaming audio URL source_stream_audio_url: type: string description: Original streaming audio URL image_url: type: string description: Cover image URL source_image_url: type: string description: Original 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 method: post type: path path: '{request.body#/callBackUrl}' components: schemas: ApiResponse: type: object properties: code: type: integer description: |- # 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 example: 200 enum: - 200 - 400 - 401 - 404 - 405 - 413 - 429 - 430 - 455 - 500 msg: type: string description: Error message when code != 200 example: success responses: Error: description: Server error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- # 🔑 API Authentication All endpoints require authentication using Bearer Token. ## Get API Key 1. Visit the [API Key Management Page](https://api.box/api-key) 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 ````