> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunoapi.org/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 Usage Guide Required parameters for all requests: * `uploadUrl`: Valid instrumental audio file URL * `prompt`: Description of the desired vocal content and style * `title`: Title for the generated vocal track (max 100 characters) * `style`: Music and vocal style (e.g., "Jazz", "Pop", "Classical") * `negativeTags`: Vocal styles or characteristics to exclude * `callBackUrl`: URL to receive completion notifications Optional parameters for enhanced control: * `vocalGender`: Preferred vocal gender ('m' for male, 'f' for female) * `styleWeight`: Style adherence weight (0.00-1.00) * `weirdnessConstraint`: Creativity/novelty constraint (0.00-1.00) * `audioWeight`: Audio consistency weight (0.00-1.00) * `model`: Model version used for generation. Allowed values: `V4_5PLUS` (default), `V5`, `V5_5` Audio requirements: * Input Type: Instrumental or backing track audio files * File Format: MP3, WAV, or other supported audio formats * Quality: Clear instrumental tracks work best for vocal addition * Accessibility: Ensure uploaded audio URLs are publicly accessible ### Developer Notes 1. Generated vocal tracks are retained for 15 days before being deleted 2. Ensure you have proper rights to use the uploaded audio content 3. Use clear, well-mixed instrumental tracks for best results 4. Be specific about vocal style in your prompt (e.g., "smooth jazz vocals", "energetic pop vocals") 5. Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete) 6. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks ## 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@sunoapi.org servers: - url: https://api.sunoapi.org 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.sunoapi.org/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://sunoapi.org/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 ````