Generate a voice preview by remixing / translating existing audio

Using an existing audio clip as reference, generate a remixed voice preview. Session, quota, concurrency, and billing rules are identical to "generate a voice preview from a text description".

Two modes

`remix_mode`	Meaning	`instruct`	`language`
`normal` (default)	Remix the reference audio's timbre per the description	required (1 ~ 2048 characters)	optional, not validated
`translate`	Keep the timbre; translate the reference audio and dub it into the target language	ignored	required, and must not be `auto`

language in translate mode is strictly validated: it must be one of the 9 values in auto / zh / en-us / ja / ko / fr-fr / pt / de / es / yue
except auto, otherwise VALIDATION_BAD_PARAMS.
Short aliases are normalized first (en → en-us, fr → fr-fr, modules/validationConstants.js:103-112), so both spellings pass.

Audio source: pick one of two

At least one of voiceId (+ optional promptIdx) and source_audio_url must be provided; providing neither returns VALIDATION_BAD_PARAMS.
source_audio_url only accepts a data: URL or an http(s) address whose domain has been allowlisted by ops; anything else is always VALIDATION_BAD_PARAMS.

Many optional tuning parameters

The parameters below all accept both camelCase and snake_case spellings, and follow the same tolerance rule:
out-of-range or wrong-type values are silently dropped and fall back to server defaults; they do not error.
This is intentional (these parameters are purely additive capability), but it also means a misspelled parameter name produces no hint — check against this document.

Error-code downgrade notes

When resolving the reference voice fails, only VOICE_NOT_FOUND is passed through as-is;
an unpurchased market voice (internal MARKET_VOICE_NOT_FOUND) and lack of access (internal AUTH_FORBIDDEN)
are not on the passthrough allowlist (modules/routeHelpers.js:1008) and both end up downgraded to 500 SYSTEM_INTERNAL_ERROR.

This endpoint has a single path; there is no /api/tts/voice/... compatibility alias.

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.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Responses

🟢200成功

application/json

改造试听生成成功，sessionId 用于后续确认

Bodyapplication/json

Example

{
    "status": 200,
    "data": {
        "sessionId": "6b0e94d3-1c72-4a85-b3f6-08de5217ca49",
        "previewAudioUrl": "https://storage.vocu.ai/voice-design/2f81b40c-9d63-4e17-a5b8-31c7d0e926af/6b0e94d3-1c72-4a85-b3f6-08de5217ca49-remix.wav",
        "text": "Hello, nice to meet you. I hope we work well together.",
        "remix_mode": "translate",
        "no_content": false,
        "source_tags": [
            "speech"
        ]
    }
}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠404记录不存在

🟠429

🔴500服务器错误

Generate a voice preview by remixing / translating existing audio

Two modes#

Audio source: pick one of two#

Many optional tuning parameters#

Error-code downgrade notes#

Request

Request Code Samples

Responses

Two modes

Audio source: pick one of two

Many optional tuning parameters

Error-code downgrade notes