Update custom voice metadata via the xAI API

Change display labels on an existing custom voice when the clone audio is fine but the name, description, tone, or use-case tags no longer match how the team catalogs voices. Official Custom Voices documents PATCH https://api.x.ai/v1/custom-voices/{voice_id} with a JSON body of optional fields. Omitted fields stay unchanged, JSON null clears a value, and empty strings are rejected with 400. The endpoint never replaces the underlying reference audio; re-record by deleting and creating a new voice. Start from a known id via List custom voices via the xAI API or the console Copy Voice ID action described in Create a custom voice.

What you need

An API key for the owning team and a voice_id that belongs to that team are required before any PATCH, because unknown ids or other teams' voices return 404. Allowed metadata includes name, description, gender (male / female / neutral), accent, age (young / middle-aged / old), language, use_case (for example narration, conversational, educational), and tone (for example warm, calm, professional). Neighboring jobs include Convert text to speech with the Grok Voice API and Delete a custom voice via the xAI API. More voice jobs live on the Voice hub.

Patch labels without re-cloning

1. Export the API key and the target voice id outside of source control so the PATCH never embeds secrets in scripts checked into git:

export XAI_API_KEY="your_api_key"
export VOICE_ID="nlbqfwie"

2. Send only the fields you intend to change in a JSON body, leaving every other property omitted so the server keeps prior values:

curl -X PATCH "https://api.x.ai/v1/custom-voices/${VOICE_ID}"   -H "Authorization: Bearer ${XAI_API_KEY}"   -H "Content-Type: application/json"   -d '{"description":"Updated after a tuning pass.","tone":"calm"}'

3. Expect HTTP 200 with the full updated voice object, including the unchanged voice_id and created_at, then confirm TTS still uses the same id because synthesis follows the original reference clip rather than the new labels.

4. Clear an optional string field by PATCHing that field to JSON null, and never send "" because the docs reject empty strings with 400.

When to delete instead

PATCH is the right tool for catalog hygiene and support runbooks that rename voices after a brand pass without touching audio. When the spoken timbre itself is wrong, follow Delete a custom voice via the xAI API and create a fresh clone from a better reference clip rather than expecting metadata to reshape audio.

Pitfalls

Sending empty-string values fails validation even though omitting the field would have been a no-op and left the prior label intact. Assuming PATCH re-uploads audio leaves bad clones in place until you DELETE and create again from a cleaner reference. Patching a voice owned by another team returns 404 and looks like a typo'd id when the real issue is team scope on the API key.