API Reference
API Reference / Endpoints / Music

Upload vocal reference

/v1/music/vocals/upload

Upload a vocal reference file and receive a vocal_id for later clone jobs.

POST/v1/music/vocals/upload
Auth: API keyBilling: FreeBehavior: SyncScopes: audio:generate
POSTSyncmultipartaudio:generate

When to use it

Use this before vocal cloning when you need to provide the reference voice as an audio file.

Behavior on success

Returns a completed payload on the normal success path.

Integration shape

Authorization model
audio:generate
Request format
multipart
Polling pattern
No polling required on the normal success path.

Request

FieldTypeRequiredDescription
filefileYesReference vocal audio in multipart field `file`.

Example request

POST /v1/music/vocals/upload
const form = new FormData();
form.append('file', fileInput.files[0]);

const response = await fetch('https://prod-backup-backend.wubble.ai/v1/music/vocals/upload', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WUBBLE_API_KEY}`,
  },
  body: form,
});

const payload = await response.json();
console.log(payload);

Example response

Response shapejson
{
  "success": true,
  "data": {
    "vocal_id": "voc_123",
    "status": "completed",
    "filename": "reference-vocal.wav",
    "bytes": 1245000,
    "content_type": "audio/wav"
  }
}

Implementation notes

This route is multipart only.
No idempotency middleware runs on this upload route.

Production guidance

Pair this route with idempotency on POST requests and either request polling or webhooks whenever the response is asynchronous.
Was this page helpful?
Previous
Clone vocalsNext