Follow-up ActionsSuno
Add Vocals
Layer AI-generated vocals onto a completed Suno track.
POST /v2/music/suno/action — action: "add_vocals"
Generates a sung vocal layer on top of one of the parent job's tracks. It is
intended for instrumental parents (generated with instrumental: true),
turning a backing track into a complete song. The result is a fresh pair of
tracks — same shape as a generation — and can itself be
extended, covered, or split into stems.
Select the track with index (1 or 2) or with the trackId from the
parent's result.tracks[].id — exactly one of the two.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
parentJobId | string (uuid) | Yes | ID of the completed suno job to act on |
action | string | Yes | "add_vocals" |
index | number | One of index/trackId | Which of the parent's tracks to add vocals to: 1 or 2 |
trackId | string | One of index/trackId | Track ID from the parent's result.tracks[].id |
prompt | string | Yes | The lyrics to sing (max 5,000 characters). Structure markers like [Verse] / [Chorus] are supported |
title | string | No | Title for the result (max 80 characters). Defaults to the source track's title |
style | string | No | Vocal/music style tags (max 1,000 characters). Defaults to the source track's tags |
negative_tags | string | No | Styles to avoid (max 500 characters) |
webhookUrl | string | No | HTTPS URL that receives a JSON POST when the job reaches a subscribed event — see Webhooks for payload formats |
webhookEvents | string[] | No | Events to be notified about: "progress", "completed", "failed". Defaults to ["completed", "failed"] when webhookUrl is set |
The model version is always inherited from the parent.
Credits
11 credits per add-vocals (same as a generation — it produces 2 new tracks).
Example result
Once the job is COMPLETED, the result object on
GET /v2/jobs/:id contains a fresh pair of tracks:
{
"tracks": [
{
"id": "1d7f3a58-9c2b-4e6d-a804-5f1b8e3c7a92",
"audioUrl": "https://cdn2.apiframe.ai/audio/d4e5f6a7-b8c9-0123-def4-567890123456-0.mp3",
"imageUrl": "https://cdn2.apiframe.ai/audio/d4e5f6a7-b8c9-0123-def4-567890123456-0.jpeg",
"title": "Midnight Drive (Vocal)",
"tags": "synthwave, dreamy vocals",
"duration": 145.3
},
{
"id": "6b0e9c24-4a7f-4d1c-8f35-2e8d5a1b9c47",
"audioUrl": "https://cdn2.apiframe.ai/audio/d4e5f6a7-b8c9-0123-def4-567890123456-1.mp3",
"imageUrl": "https://cdn2.apiframe.ai/audio/d4e5f6a7-b8c9-0123-def4-567890123456-1.jpeg",
"title": "Midnight Drive (Vocal)",
"tags": "synthwave, dreamy vocals",
"duration": 141.7
}
]
}Each of these tracks can be the parent of another follow-up action.
Code examples
curl -X POST https://api.apiframe.ai/v2/music/suno/action \
-H "X-API-Key: afk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"parentJobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"action": "add_vocals",
"index": 1,
"prompt": "[Verse]\nHeadlights cut through the rain\nEvery mile erases your name\n\n[Chorus]\nMidnight drive, neon glow\nLetting go of all I know"
}'import requests
response = requests.post(
"https://api.apiframe.ai/v2/music/suno/action",
headers={
"X-API-Key": "afk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"parentJobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"action": "add_vocals",
"index": 1,
"prompt": (
"[Verse]\nHeadlights cut through the rain\n"
"Every mile erases your name\n\n"
"[Chorus]\nMidnight drive, neon glow\nLetting go of all I know"
),
},
)
print(response.json())const response = await fetch("https://api.apiframe.ai/v2/music/suno/action", {
method: "POST",
headers: {
"X-API-Key": "afk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
parentJobId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
action: "add_vocals",
index: 1,
prompt:
"[Verse]\nHeadlights cut through the rain\nEvery mile erases your name\n\n" +
"[Chorus]\nMidnight drive, neon glow\nLetting go of all I know",
}),
});
console.log(await response.json());body := `{
"parentJobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"action": "add_vocals",
"index": 1,
"prompt": "[Verse]\nHeadlights cut through the rain\n\n[Chorus]\nMidnight drive, neon glow"
}`
req, _ := http.NewRequest("POST", "https://api.apiframe.ai/v2/music/suno/action",
strings.NewReader(body))
req.Header.Set("X-API-Key", "afk_your_api_key_here")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)Try it
POST
/v2/music/suno/actionTry it