Upload audio for voice conversion

The first step of voice conversion (VC). Only the URL returned here can be passed as input_audio to POST /api/tts/simple-generate or to an audio content block in an asynchronous job — an arbitrary external URL is rejected with TTS_INPUT_AUDIO_INVALID, because the server validates both host and reserved path.

audio must be a data-URL string beginning with data:audio/...;base64,, not a multipart file. Constraints:

20 MB after decoding → exceeded gives UPLOAD_TOO_LARGE

300 seconds (5 minutes) of duration → exceeded gives VALIDATION_TOO_LONG

Content-safety screening for everyone except admin / enterprise → a rejection gives SAFETY_CONTENT_REJECTED with a traceId

Uploaded audio is transcoded to MP3 at 320 kbps before storage, so the duration and URL in the response describe the transcoded file rather than the bytes you sent. Input that ffmpeg cannot parse returns UPLOAD_AUDIO_INVALID.

Dedicated rate limit (free individual accounts only): 20 requests per 10 minutes, after which you get a 429 with Retry-After. This bucket is separate from the 8-per-10-minutes bucket used by voice creation and style addition.

Error responses take the shape { status, code, message, requestId? }. code is always the parent code — sub codes only change message and never appear in the body. requestId is present only on reportable-tier errors, so use the X-Vocu-App-Request-Id response header when troubleshooting (it is written unconditionally on every response). See the "Errors" document for the full code reference.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

Example

{
    "audio": "data:audio/wav;base64,X2WDzbOHAPf88clAqELykihJsChXfWwV1C4Oqx9nFyZp82bzq4EOcrzuCWAIiU9AOovOJRMQRJjkslpXTJuNf5D8wfdrfCRM1JHqktqEDCeFVgZhfl2pVbcRyWDVEybArGf4KCYDIJC9DlpdxZIqXDBOPIznQ5RuyACOKx9HN0zzfVtKeAbW7ujKTiRR3DiHsTrWq7g11bLKznC5Lzjg0cEN0bPDnZdEvs0acuOzRFSQCAoweCyCrkBJv0KM9EjOyRlvsGby7Zqg4odsDqok6NmhN0wpmcoUO7cHjoVitVtnBHtjrf3SpnQ2YhRyEDnWql5i12thBqF6lpZ2j8RjxW4HYBkcdSRkJxZC1QzHdozblKfbkaRJ26Z3Rz2t2mY98pxNUmpHiJD8PWSTJbg3q0YLXu2pFFZ729XN2aGTRA3imzfsjE6vNtN4j8PM7HieHw9yHhX15W4QPJyrTtNVdVj8O3eVYmNlQmwiMNlYfdU2tpZfdxNE"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200成功上传音频文件

application/json

Uploaded; data.url can be used directly as input_audio, and data.duration is the transcoded length in seconds

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "url": "https://storage.vocustatic.com/vc-input/8ca08a3e-6ea4-4f6f-aa1a-73de8c388035/5d25c563-1387-40f7-b5bf-4897add4b6d1.mp3"
    }
}

🟠400请求有误

🟠401没有权限

🟠413

🟠429

🔴500服务器错误

🔴503服务器故障