> ## 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 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 Usage Guide Required parameters for all requests: * `uploadUrl`: Valid audio file URL (MP3, WAV, or other supported formats) * `title`: Title for the generated instrumental track (max 100 characters) * `tags`: Desired style and characteristics for the instrumental * `negativeTags`: Styles or instruments to exclude * `callBackUrl`: URL to receive completion notifications Optional parameters for enhanced control: * `vocalGender`: Preferred vocal gender for any vocal elements ('m' or 'f') * `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: * File Format: MP3, WAV, or other supported audio formats * Quality: Higher quality input generally produces better instrumental results * Accessibility: Ensure uploaded audio URLs are publicly accessible and stable ### Developer Notes 1. Generated instrumental files are retained for 15 days before being deleted 2. Ensure you have proper rights to use the uploaded audio content 3. Be specific with tags to get the desired instrumental style (e.g., "acoustic guitar, soft piano, ambient") 4. Use negative tags effectively to avoid unwanted elements 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-instrumental 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-instrumental: post: tags: - Music Generation summary: Add Instrumental 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: >- 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: type: string description: >- The title of the music track. - Required. - This will be used as the title for the generated instrumental track. example: Relaxing Piano negativeTags: type: string description: >- 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: type: string description: >- 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: type: string format: uri description: >- 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](https://docs.sunoapi.org/suno-api/add-instrumental-callbacks) - Alternatively, you can use the Get Music Generation Details interface to poll task status example: https://api.example.com/callback vocalGender: type: string description: >- Preferred vocal gender for any vocal elements. 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 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: instrumentalAdded: '{request.body#/callBackUrl}': post: description: >- System will call this callback when instrumental 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": "[Instrumental] Relaxing piano melody", "model_name": "chirp-v3-5", "title": "Relaxing Piano Instrumental", "tags": "relaxing, piano, instrumental", "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 ````