Voices

A voice is what speak reads with. Voixa ships built-in voices in ten languages, and you can clone your own from three to ten seconds of clean speech. Clones are private to your account unless you share them.

The voice model

Properties

  • Name
    voiceId
    Type
    string
    Description

    What you pass to speak. Built-in voices have readable ids such as vi-truc-ly or en-alba; clones have a UUID.

  • Name
    kind
    Type
    string
    Description

    preset for built-in voices, clone for cloned ones.

  • Name
    language
    Type
    string
    Description

    vi, en, zh, ja, ko, fr, de, it, es or pt. A voice reads the language it was made for.

  • Name
    name
    Type
    string
    Description

    Display name.

  • Name
    gender
    Type
    string
    Description

    female, male or neutral.

  • Name
    styles
    Type
    string[]
    Description

    Tags such as narrative, news, warm, upbeat, documentary.

  • Name
    sampleUrl
    Type
    string
    Description

    A short sample of the voice. Public for built-in voices; a signed one-hour URL for clones.

  • Name
    status
    Type
    string
    Description

    processing while a clone is being prepared, then ready or failed (with failReason). Built-in voices are always ready.

  • Name
    mine
    Type
    boolean
    Description

    true for clones you own — the only voices you can rename, share or delete.

  • Name
    shared
    Type
    boolean
    Description

    true when the clone is shared with every Voixa account.

GET/v1/voices

List voices

Built-in voices, your clones, and clones other accounts shared. Filter by language with ?language=vi.

Optional query

  • Name
    language
    Type
    string
    Description

    One of the ten language codes.

Request

GET
/v1/voices
curl "https://api.voixa.vovix.io/v1/voices?language=vi" \
  -H "x-api-key: $VOIXA_API_KEY"

Response

{
  "voices": [
    {
      "voiceId": "vi-truc-ly",
      "kind": "preset",
      "language": "vi",
      "name": "Trúc Ly",
      "gender": "female",
      "styles": ["narrative", "warm"],
      "sampleUrl": "https://…/samples/vi-truc-ly.wav",
      "status": "ready",
      "mine": false,
      "shared": false
    }
  ]
}
GET/v1/samples

Voice samples

Built-in voices only, each with a public sampleUrl and the sentence it speaks (sampleText). Meant for a voice picker inside your own product: call it from your server, cache the result, and hand the URLs to the browser — they need no key.

Request

GET
/v1/samples
curl "https://api.voixa.vovix.io/v1/samples?language=en" \
  -H "x-api-key: $VOIXA_API_KEY"
POST/v1/voices

Clone a voice

Cloning takes two calls and one upload, because the recording goes straight to storage instead of through the API:

  1. POST /voices/upload with { "format": "wav" } or "mp3" returns a voiceId and an uploadUrl (valid 15 minutes).
  2. PUT the recording to uploadUrl with the matching content-type.
  3. POST /voices with that voiceId. Voixa prepares the voice and reads a sample sentence with it; the response waits up to about 18 seconds and may still be processing.

Three to ten seconds of one person speaking, without music or background noise, works best. Cloning is available for every language except Chinese, Japanese and Korean.

Required attributes

  • Name
    voiceId
    Type
    string
    Description

    The id returned by POST /voices/upload.

  • Name
    name
    Type
    string
    Description

    Display name, 1–60 characters.

  • Name
    language
    Type
    string
    Description

    The language this voice will read.

Optional attributes

  • Name
    gender
    Type
    string
    Description

    female, male or neutral (default).

  • Name
    description
    Type
    string
    Description

    Up to 300 characters, searchable in Studio.

  • Name
    refText
    Type
    string
    Description

    What the recording says, if you know it.

Request

POST
/v1/voices
# 1. where to upload
curl -X POST https://api.voixa.vovix.io/v1/voices/upload \
  -H "x-api-key: $VOIXA_API_KEY" -H "content-type: application/json" \
  -d '{ "format": "wav" }'

# 2. the recording
curl -X PUT "$UPLOAD_URL" -H "content-type: audio/wav" --data-binary @me.wav

# 3. the voice
curl -X POST https://api.voixa.vovix.io/v1/voices \
  -H "x-api-key: $VOIXA_API_KEY" -H "content-type: application/json" \
  -d '{ "voiceId": "'$VOICE_ID'", "name": "Me", "language": "vi" }'
PATCH/v1/voices/{voiceId}

Update a clone

Rename or describe one of your clones, or share it. "shared": true lets every Voixa account list and use the voice (they cannot change or delete it); false withdraws it. Only ready voices can be shared.

Optional attributes

  • Name
    name
    Type
    string
    Description

    New display name.

  • Name
    description
    Type
    string | null
    Description

    New description, or null to clear it.

  • Name
    gender
    Type
    string
    Description

    female, male or neutral.

  • Name
    styles
    Type
    string[]
    Description

    Up to eight tags.

  • Name
    shared
    Type
    boolean
    Description

    Share with every account, or withdraw.

Request

PATCH
/v1/voices/{voiceId}
curl -X PATCH https://api.voixa.vovix.io/v1/voices/$VOICE_ID \
  -H "x-api-key: $VOIXA_API_KEY" -H "content-type: application/json" \
  -d '{ "shared": true }'
DELETE/v1/voices/{voiceId}

Delete a clone

Deletes the clone and its recording. Clips already made with it stay in your library.

Request

DELETE
/v1/voices/{voiceId}
curl -X DELETE https://api.voixa.vovix.io/v1/voices/$VOICE_ID \
  -H "x-api-key: $VOIXA_API_KEY"

Was this page helpful?