Upload avatar for the voice character with the specified ID

POST

https://v1.vocu.ai/api/voice/{id}/avatar

avatar must be a base64 data-URL string, not a multipart file. The string length is capped at roughly 14 MB, which corresponds to about 10 MB of original image — the limit is applied to the base64 character count (10 MB × 1.37). Exceeding it returns UPLOAD_TOO_LARGE.

The image is checked for safety: a rejection returns SAFETY_* with a traceId in the body, while any decode or processing failure collapses into VALIDATION_INVALID_FORMAT.

On success the avatar URL is written to metadata.avatar — re-uploading for the same voice overwrites the previous image, so CDN caches may take a while to reflect the change.

INFO

Deprecated alias: /api/tts/voice/{id}/avatar. 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

{
    "avatar": "data:image/png;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEuMSIgYmFzZVByb2ZpbGU9ImZ1bGwiIHdpZHRoPSIxMzQ2IiBoZWlnaHQ9IjI3ODAiPjxyZWN0IHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGZpbGw9IiNjY2E4NjgiLz48dGV4dCB4PSI2NzMiIHk9IjEzOTAiIGZvbnQtc2l6ZT0iMjAiIGFsaWdubWVudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSJ3aGl0ZSI+MTM0NngyNzgwPC90ZXh0Pjwvc3ZnPg=="
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://v1.vocu.ai/api/voice//avatar' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "avatar": "data:image/png;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEuMSIgYmFzZVByb2ZpbGU9ImZ1bGwiIHdpZHRoPSIxMzQ2IiBoZWlnaHQ9IjI3ODAiPjxyZWN0IHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGZpbGw9IiNjY2E4NjgiLz48dGV4dCB4PSI2NzMiIHk9IjEzOTAiIGZvbnQtc2l6ZT0iMjAiIGFsaWdubWVudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSJ3aGl0ZSI+MTM0NngyNzgwPC90ZXh0Pjwvc3ZnPg=="
}'

Responses

🟢200Successfully uploaded avatar

application/json

Avatar updated; returns the updated voice

Bodyapplication/json

Example

{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "042391f5-5887-403f-a42c-1a67680625bc",
        "idForGenerate": "3c83796b-8cc8-4b8e-a3e2-61761d4d258e",
        "name": "Duan Yuhang",
        "status": "pending",
        "metadata": {
            "avatar": "https://picsum.photos/seed/RsqU7i/371/940",
            "description": "Entrepreneur, inventor, activist",
            "prompts": [
                {
                    "id": "31ef37b0-a4b7-4c87-b6d1-4abfe8725027",
                    "name": "Carefree",
                    "promptOriginAudioStorageUrl": "https://storage.vocu.ai/prompt/260913/535265-playback-xe595e.mp3"
                }
            ]
        }
    }
}

🟠400Bad request

🟠401Unauthorized

🟠404Not found

🟠413Payload too large

🟠429Rate limited

🔴500Server error

Modified at 2026-08-23 09:24:46

Update a voice character's name and description

Delete Voice Character with the specified ID