Skip to main content

​
Endpoint

POST /api/v1/music/add-vocals
Asynchronous. Returns a task_id. Poll Get Task for results. Takes an existing clip and “paints” new vocal content over a specified time range using a sample source clip as the vocal reference.

​
Request body

FieldTypeRequiredDescription
chop_sample_clip_idstringYesClip ID of the vocal sample source.
chop_sample_start_sfloatNoStart time (seconds) in the sample clip. Default 0.
chop_sample_end_sfloatNoEnd time (seconds) in the sample clip. Default: full clip.
promptstringNoLyric content for the new vocal section. Supports Chinese and English.
tagsstringNoStyle tags (e.g. "流行 女声" or "pop female").
mvstringNoModel version override.
callback_urlstringNoWebhook URL for completion notification. See Webhooks.
retention_daysintegerNoDays to retain audio files. Default 7.

​
Response

{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}

​
Example

curl -X POST https://api.example.com/api/v1/music/add-vocals \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "chop_sample_clip_id": "abc123def456",
    "chop_sample_start_s": 10.0,
    "chop_sample_end_s": 25.0,
    "prompt": "[副歌]\n在这片土地上\n我找到了归宿",
    "tags": "流行 抒情"
  }'