Create a reusable user voice

POST /v1/audio/voices

Saves a reusable voice in the service host's library from a short reference clip and its transcript. Do not supply model. Use the returned voice.id for synthesis or deletion.

Guide and examplesSpeech and voice library All endpoints

Request body

multipart/form-dataRequired

audio_samplefileRequiredRequired reference audio, up to 10 MiB. Use a short, clear clip.

ref_textstringRequiredTranscript of the reference audio.

namestringRequiredDisplay name for the voice, returned under names.

consentbooleanRequiredRequired: true.true

languagestringLanguage of the reference audio, such as zh-CN or en-US. Omitting it stores the voice as zh-CN. See /docs/languages#by-api for how each API uses language codes.Default "zh-CN"

speaker_descriptionstringOptional description of the speaker, returned under descriptions.

Responses

200The created voice. Inspect its compatibility before selecting a synthesis model.

successboolean

voiceobjectOne voice record. Names and descriptions are locale maps, not a single name string.

idstringVoice ID, for example builtin:bright-girl or user:<uuid>.

namesobject

descriptionsobject

supported_languagesstring[]

originstringFor example cloned.

compatibilityobject[]Per-model compatibility. Availability alone does not guarantee compatibility with every speech model.

availableboolean

created_by_userbooleanOnly user voices can be deleted; built-in voices are immutable.

{
  "success": true,
  "voice": {
    "id": "user:00000000-0000-4000-8000-000000000001",
    "names": {
      "en-US": "My voice"
    },
    "descriptions": {},
    "supported_languages": [
      "en-US"
    ],
    "origin": "cloned",
    "compatibility": [],
    "available": true,
    "created_by_user": true
  }
}

400Invalid request. Fix the request before retrying; use error.code for program logic and error.param to locate the input.

401Invalid or missing API key.

403Host or origin is not allowed, or the license was rejected. Inspect error.code to tell them apart.

413Request body exceeds 512 MiB.

503A required local model is still being prepared (model_downloading) or the service is busy (service_busy). Honor Retry-After when present.