> ## Documentation Index > Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add Vocals > Layer AI-generated vocals on top of an existing instrumental 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`. 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint. ## Usage Guide * This endpoint adds AI-generated vocals to an existing instrumental track * Upload an instrumental file and provide lyrics or a description for the vocals * Perfect for transforming instrumental tracks into complete songs ## Parameter Details * Required parameters: * `upload_url`: URL of the instrumental audio file * `prompt`: Lyrics or description for the vocals * `title`: Name for the generated track * `style`: Music style to guide vocal delivery * `negative_tags`: Styles to exclude from generation * Model selection: * **V5**: Superior musical expressiveness with faster generation * **V4\_5PLUS**: Enhanced tonal richness (default) ## Developer Notes * The `prompt` parameter serves as both lyrics and creative direction for the vocals * Use `style` to specify the vocal delivery style (e.g., "Pop Ballad", "Rock", "R\&B") * Combine with `vocal_gender` for more control over the vocal output ## Optional parameters * `model` (string): AI model version. Options: `V4_5PLUS` (default), `V5`. * `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter can only increase the probability but cannot guarantee the specified gender. * `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals. * `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals. * `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals. ## OpenAPI ````yaml /api-manual/music-series/add-vocals.json POST /api/generate/submit openapi: 3.0.0 info: title: Vidgo API - Add Vocals API description: Layer AI-generated vocals on top of an existing instrumental version: 1.0.0 servers: - url: https://api.vidgo.ai description: Production server security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Music Generation summary: Submit Add Vocals Task description: Layer AI-generated vocals on top of an existing instrumental track operationId: submitAddVocalsTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: basic: summary: Basic Vocal Generation value: model: add-vocals callback_url: https://your-domain.com/callback input: upload_url: https://storage.example.com/instrumental.mp3 prompt: A heartfelt ballad about love and memories title: Memories of You style: Pop Ballad negative_tags: rap, heavy metal advanced: summary: Advanced with Style Controls value: model: add-vocals callback_url: https://your-domain.com/callback input: upload_url: https://storage.example.com/instrumental.mp3 mv: V5 prompt: Upbeat lyrics about summer adventures and freedom title: Summer Freedom style: Pop, Upbeat, Energetic negative_tags: sad, slow, melancholic vocal_gender: f style_weight: 0.7 weirdness_constraint: 0.2 audio_weight: 0.6 responses: '200': description: Task submitted successfully content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' components: schemas: SubmitRequest: type: object required: - model - input properties: model: type: string description: |- API model identifier. Must be `add-vocals` for this endpoint. enum: - add-vocals example: add-vocals callback_url: type: string format: uri description: Webhook callback URL for result notifications example: https://your-domain.com/callback input: type: object required: - upload_url - prompt - title - style - negative_tags description: Input parameters for vocal generation properties: upload_url: type: string format: uri description: URL of the instrumental audio file to add vocals to. example: https://storage.example.com/instrumental.mp3 prompt: type: string description: |- Lyrics or description for the generated vocals. This will be used as the content for the AI-generated vocals. example: A heartfelt ballad about love and memories title: type: string description: |- Name for the generated music. Maximum 100 characters. maxLength: 100 example: Memories of You style: type: string description: >- Music style specification defining genre, mood, or artistic direction. Guides the vocal style and delivery. example: Pop Ballad negative_tags: type: string description: >- Music styles or characteristics to exclude from generation. Specify unwanted genres, moods, or vocal styles to avoid in the output. example: rap, heavy metal mv: type: string description: >- AI model version for vocal generation. - **V5**: Superior musical expressiveness with faster generation - **V4_5PLUS**: Enhanced tonal richness with new creative approaches Default: V4_5PLUS enum: - V4_5PLUS - V5 example: V4_5PLUS vocal_gender: type: string description: >- Preferred vocal gender for the generated vocals. - `m`: Male vocals - `f`: Female vocals **Note**: This parameter increases the probability but cannot guarantee the specified gender. enum: - m - f example: f style_weight: type: number description: >- Controls how strongly the specified style influences the generation. Range: 0-1, up to 2 decimals. Higher values result in stronger adherence to the specified style. minimum: 0 maximum: 1 example: 0.65 weirdness_constraint: type: number description: >- Controls the level of experimental creativity and unconventional elements. Range: 0-1, up to 2 decimals. - Lower values: More conventional vocals - Higher values: More experimental and unique vocal outputs minimum: 0 maximum: 1 example: 0.65 audio_weight: type: number description: >- Balances audio characteristics against other generation factors. Range: 0-1, up to 2 decimals. Adjusts the emphasis on audio quality and sonic features in the final output. minimum: 0 maximum: 1 example: 0.65 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 description: HTTP status code data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1757165031-uyujaw3d description: Unique task identifier for status tracking status: type: string enum: - not_started example: not_started description: Initial task status created_time: type: string format: date-time example: '2025-11-12T10:30:00' description: ISO 8601 timestamp when the task was created securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- All API endpoints require Bearer Token authentication Get your API Key: Visit the [API Key Management Page](https://vidgo.ai/apis/dashboard/api-key) to get your API Key Add it to the request header: ``` Authorization: Bearer VIDGO_API_KEY ``` ````