Add a style to the voice character with the specified ID

Append a style (prompt) to an existing voice. The new style is assigned a UUID as its promptId, which you then pass when generating; omitting it uses default.

Preconditions: the target must be a self-created voice (from === 'upload'). Voices bought from the market or imported from the library cannot take new styles and return AUTH_FORBIDDEN. A voice in creating returns 409 VOICE_CREATING; one in failed returns 400 VOICE_CREATE_FAILED.

Audio constraints for this endpoint: 20 MB data-URL cap (voice creation is 100 MB), at least 3 seconds of speech. Uploaded content is checked for safety; a rejection returns SAFETY_* with a traceId. language must use a full value; some endpoints silently downgrade illegal values to auto. See the "Languages and localization" document.

May return RATE_LIMIT_* (HTTP 429). Read Retry-After and retry with exponential backoff. See the "Errors" document.

TIP

Legacy voices are prepared automatically before the style is added. If that preparation fails the call returns VOICE_UNAVAILABLE (503) and can be retried later.

INFO

Deprecated alias: /api/tts/voice/{id}/prompt. See the site document "Versions and migration".

INFO

See the Errors document for the full code reference. Always use the X-Vocu-App-Request-Id response header when troubleshooting.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Path Params

Body Params application/json

Example

{
    "name": "Happy",
    "prompt": "data:audio/wav;base64,fMRLm9LywDeweSOsz0q9zahvHoMrnLvoUTippGeXDe33z0S8hs5tpRcTG3MY8QwG2N8aqVUiYNACiFJOa8OVI7n7JXdAN694A4XyAVQCu4GUjy6z0d3SiWmdolGKcKTQJ0V4PK25bgp9Jyp5uNAJDGZCHxErLo5fiTKffWmuDI3hboQUfbP3kRKQl746HMcemZrMoGeyWbtc8XBujLquIFGm9ZPsNWQNIIM1k9VuwJ5vIIYpg8lPjpikAHhPr5f3MVaS5U3XgbLlHk04zmokryHpvU54xs4asiHcRM0gaKHyM03HlxaH3nkN6FY39rJeTZtS5DZ1Tgn1jK3F8zVKFFOAx8wavYFuEiriRZO4IqwN5v7mNVqgJgYyH9TgcNnUmRP4WRwjcpWHZAZ1NPBB629y1XIt3ScxB16g4bdMOahsWQg1qJ6c9wJElSAzsiq6Z75gAR0f5Z1IvpqSSgBxMcMyVc5QgFHd3F5ldsZ2ExXNvlPZdqgm",
    "description": "Happy emotional style",
    "vocalFilter": false
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Successfully added character style

application/json

Style added; returns the updated voice with the new entry in metadata.prompts

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "22454287-ecbd-499c-9ccb-c60f2d38acc7",
        "idForGenerate": "3192abc5-9ab0-4235-be44-eb8a336338b9",
        "name": "Qian Lifang",
        "status": "lora-pending",
        "metadata": {
            "avatar": "https://loremflickr.com/2252/1664?lock=6544168410253842",
            "description": "Diving enthusiast",
            "prompts": [
                {
                    "id": "default",
                    "name": "Default Style",
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/530917/477883-playback-qmrue4.mp3"
                },
                {
                    "id": "238ab849-ac1b-408f-97dc-02645f3fb62d",
                    "name": "Happy",
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/964700/450066-playback-o364bm.mp3",
                    "description": "Happy emotional style"
                }
            ]
        }
    }
}

🟠400Bad request

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠409Conflict

🟠413Payload too large

🟠429Rate limited

🔴500Server error

🔴503Temporarily unavailable