docs / endpoints / add-vocals
POST/v1/add-vocals

Turn an instrumental into a song: point it at an existing instrumental track and provide the lyrics (or a description of them), and it sings them over the music. Returns 202 Accepted with a generation object of type: "add_vocals", then completes asynchronously.

$Billing: 11 credits per request — two variations included. Free with a sandbox key.

## Request body

audio_urlrequiredstringPublic URL of the instrumental track to add vocals to.
promptrequiredstringThe lyrics to sing, or a description of them. Up to 5,000 characters.
stylestringVocal/musical style tags, up to 1,000 characters.
titlestringTrack title, up to 100 characters.
negative_tagsstringStyles to avoid, up to 500 characters.
vocal_gender"m" | "f"Preferred vocal gender.
style_weightnumberHow strongly to follow style, 0–1.
weirdnessnumberHow experimental the result should be, 0–1.
audio_weightnumberHow closely to follow the source audio, 0–1.
modelstringGeneration model, default v5. See models.
webhook_urlstringHTTPS URL to POST the completed generation to. See webhooks.

## Example request

POST /v1/add-vocalsbash
curl https://api.songapi.dev/v1/add-vocals \
  -H "Authorization: Bearer $SONGAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.songapi.dev/gen_h2vJk8…/clip_1.mp3",
    "prompt": "[Verse]\nWindows down, radio loud…",
    "vocal_gender": "f"
  }'

Poll GET /v1/generations/:id or use a webhook, exactly as with generate.