> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicmint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Instrumental

> Add AI-generated instrumental backing to an uploaded vocal audio clip

## Endpoint

```http theme={null}
POST /api/v1/music/add-instrumental
```

**Asynchronous.** Returns a `task_id`. Poll [Get Task](/api-reference/tasks/get) for results.

Takes a vocal audio clip (uploaded via [Upload Audio](/api-reference/music/upload)) and adds AI-generated instrumental music underneath it.

## Request body

| Field            | Type    | Required | Description                                                                           |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `clip_id`        | string  | **Yes**  | Clip ID of the source vocal audio (from [Upload Audio](/api-reference/music/upload)). |
| `start_s`        | float   | No       | Start time in seconds of the vocal segment to use. Default `0`.                       |
| `end_s`          | float   | No       | End time in seconds of the vocal segment. Default `0` (use full clip).                |
| `mv`             | string  | No       | Model version (e.g. `"chirp-v3-5"`). Uses default if omitted.                         |
| `callback_url`   | string  | No       | Webhook URL for completion notification. See [Webhooks](/api-reference/webhooks).     |
| `retention_days` | integer | No       | Days to retain audio files. Default `7`.                                              |

## Response

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
```

## Workflow

1. Upload your vocal audio via [Upload Audio](/api-reference/music/upload) → get `clipId`
2. Call this endpoint with the `clipId` → get `task_id`
3. Poll [Get Task](/api-reference/tasks/get) until `status = "completed"`
4. Access the generated track via `results[].audio_url`

## Example

```bash theme={null}
# 1. Upload vocal audio
CLIP_ID=$(curl -s -X POST https://api.example.com/api/v1/music/upload \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/my-vocals.mp3"}' \
  | jq -r '.data.clipId')

# 2. Add instrumental
curl -X POST https://api.example.com/api/v1/music/add-instrumental \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"clip_id\": \"$CLIP_ID\",
    \"start_s\": 0,
    \"end_s\": 30
  }"
```