Delete a custom voice via the xAI API

Remove a custom voice and its stored reference audio when a clone is obsolete, failed a listening pass, or you need to free a slot under the thirty-voice team cap before creating another. Official Custom Voices documents DELETE https://api.x.ai/v1/custom-voices/{voice_id} authorized with a Bearer API key. A successful delete returns {"deleted": true}. Afterward, GET/PATCH on that id return 404, and TTS or Speech-to-Speech calls that still pass the old voice_id fail with an unknown-voice error. Confirm the id first with List custom voices via the xAI API so you never delete the wrong clone by display name alone.

What you need

An API key on the owning team and the exact eight-character voice_id are required, and Custom Voices remains United States–only except Illinois per the docs. Creation paths stay in Create a custom voice; metadata-only fixes stay in Update custom voice metadata via the xAI API. Downstream synthesis jobs include Convert text to speech with the Grok Voice API and Stream text to speech with the Voice API. More voice jobs live on the Voice hub.

Delete one voice by id

1. Export credentials and the id you intend to remove so the delete call can be reviewed before it runs against production catalogs:

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

2. Optionally re-list and match name / created_at so the id is the intended clone before any irreversible DELETE:

curl -s "https://api.x.ai/v1/custom-voices?limit=100"   -H "Authorization: Bearer ${XAI_API_KEY}"

3. Delete the voice with a Bearer call against the Custom Voices path on https://api.x.ai:

curl -X DELETE "https://api.x.ai/v1/custom-voices/${VOICE_ID}"   -H "Authorization: Bearer ${XAI_API_KEY}"

4. Expect {"deleted": true}, re-list to confirm the id is gone, then update any apps, WebSocket URIs, or Speech-to-Speech session.update payloads that still hard-code the old id before the next TTS call.

Cap and recreate

The docs cap custom voices at thirty per team, and create after the cap returns 400 until something is deleted or limits are raised with xAI. Delete-then-create is also the only supported way to change the underlying audio after a bad recording, because PATCH never replaces the reference clip.

Pitfalls

Deleting without rotating production TTS configs leaves live traffic on an unknown voice_id that starts failing immediately on the next synthesis request. Treating delete as reversible loses the reference audio, so download or archive the clip beforehand if you still need a backup of the spoken sample. Using a key from a different team yields 404 even when the id string looks correct for another team's clone.