Voices

A voice is a resource, not a string. GET /v1/voices is your library, every entry has an id like ev_1a2b3c4d, and that one id is what every surface reads — synthesis, a live session, an interpreted call.

curl https://api.eesi.ai/v1/voices \
  -H "Authorization: Bearer $EESI_API_KEY"

from eesi_sdk import EESIClient

with EESIClient(api_key="sk-eesi-...") as client:
    for voice in client.list_voices().data:
        print(voice.voice_id, voice.name, voice.status, voice.is_builtin)

import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({ apiKey: process.env.EESI_API_KEY });

const { data } = await client.listVoices();
for (const voice of data) {
  console.log(voice.voice_id, voice.name, voice.status, voice.is_builtin);
}

The list holds two kinds of entry, and they behave identically everywhere except deletion. Built-in voices are a curated global library shared by every organization; you cannot rename or delete them. Cloned voices belong to your organization and are yours to change and erase.

The invariant

Every voice — cloned or built-in — resolves to a stored reference clip. That is not a convention. It is what keeps a voice the same voice.

The synthesis model conditions the speaker on audio, not on a name. Given nothing to condition on, its auto mode samples a new speaker on every generation: in a batch job you would notice an odd timbre, and in a live session you get an agent that changes voice between sentences. So every entry in the library points at audio. A cloned voice stores the clip you uploaded. A built-in voice is designed once from a text vocabulary and the generated clip is frozen as its reference. Naming a voice_id is how you get the same speaker twice. Two consequences worth holding on to:

A long document does not drift. Splitting text across many POST /v1/audio/speech calls is safe, because each call resolves the same clip. See Text to speech.
Describing a voice is not the same as naming one. The instructions field takes a voice-design description, and it is read only when voice does not resolve to a stored clip. A description constrains the speaker; it does not pin it.

Where a `voice_id` is read

Surface	Where the id goes
`POST /v1/audio/speech`	The `voice` field.
`WS /v1/realtime`	`session.audio.output.voice` in a `session.update`. The gateway also accepts the older top-level `session.voice` and copies it into the nested field, but the nested one is what the serving model reads.
`POST /v1/story` blocks	Each block’s `voice_id`. Synthesis still happens through `/v1/audio/speech`.

The retired omni realtime id did not support cloned voices. Its adapter sent no reference audio upstream, so an ev_… id there has no effect rather than an error — the session runs in the model’s own voice. Check supports_cloning on GET /v1/audio/models before you assume a voice will carry.

Clone a voice

Cloning is a multipart/form-data upload of a few seconds of clean speech.

curl https://api.eesi.ai/v1/voices \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -F file=@dana.wav \
  -F name=Dana \
  -F consent_attested=true \
  -F category=conversational \
  -F gender=female \
  -F accent=british

from eesi_sdk import EESIClient

with EESIClient(api_key="sk-eesi-...") as client:
    with open("dana.wav", "rb") as clip:
        voice = client.create_voice(
            file=("dana.wav", clip, "audio/wav"),
            name="Dana",
            # A voiceprint is biometric data. Omit this and the upload is
            # refused with a 400 before the audio is read.
            consent_attested=True,
            category="conversational",
            gender="female",
            accent="british",
        )

print(voice.voice_id, voice.status)  # ev_1a2b3c4d processing

import { readFile } from "node:fs/promises";
import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({ apiKey: process.env.EESI_API_KEY });

const bytes = await readFile("dana.wav");
const voice = await client.createVoice({
  file: new Blob([bytes], { type: "audio/wav" }),
  name: "Dana",
  consentAttested: true,
  category: "conversational",
  gender: "female",
  accent: "british",
});

console.log(voice.voice_id, voice.status);

Field	Required	Notes
`file`	Yes	The reference clip. Up to 10 MB, and it must carry an `audio/*` content type.
`name`	Yes	1 to 255 characters. The only field you can change later.
`consent_attested`	Effectively	Defaults to `false`, and `false` is a 400. See below.
`category`	No	`general` (default), `conversational`, `narrative`, `podcast`, `customer-service`, `corporate`, `advertising`, `characters`. Browsing metadata.
`gender`	No	`female`, `male` or `neutral`. Deliberately coarse — the library filters on it.
`accent`, `description`, `language`	No	Catalogue metadata, up to 32 / 500 / 16 characters.
`engine`	No	`nur-tts-v1` (default) or `omnivoice`.
`ref_text`	No	Accepted, and then replaced. See below.

Cloning is asynchronous

The voice appears at once with status: "processing" and moves to ready when its reference clip has been trimmed, transcribed and encoded — or to failed, with the reason in error. Poll GET /v1/voices/{voice_id}, or watch the library. Using a voice before it is ready is a 400 that names the status, not a wait:

{
  "error": {
    "message": "Voice `ev_1a2b3c4d` is not ready yet (status: processing).",
    "type": "invalid_request_error",
    "param": "voice"
  }
}

`ref_text` no longer does what it looks like

The preparation step always transcribes the clip itself and overwrites whatever ref_text you sent. The field is still accepted, and supplying it changes nothing about the resulting voice.

This is deliberate, and it fixed a bad failure. The synthesis model concatenates the reference transcript with your input and crops by the clip’s duration, so the transcript has to be the words that are actually in the audio the encoder sees. The console used to send the unread prompt script instead, and every synthesis in those voices spoke the script rather than the requested sentence. Transcribing the trimmed clip is the only way to keep the two in step. The consequence for you: a clip that transcribes to nothing fails the clone outright, with status: "failed". That is a recording problem, and the fix is a better clip rather than a better field. See Voice cloning. consent_attested=true is required, and it is checked before the upload is even read: audio there is no right to clone is audio that is never taken. The timestamp lands on the voice as consent_attested_at. An attestation records your claim. Nothing verifies who is speaking on the clip, so keep your own evidence of the speaker’s permission, and read Compliance before you clone somebody who is not you.

Hear it before you commit

POST /v1/voices/{voice_id}/preview synthesizes one fixed sentence and streams back mp3. You do not choose the text, and that is the point: two voices previewed on the same sentence are comparable, where two voices reading their own best lines are not. There is no SDK method, so call it directly:

import httpx

response = httpx.post(
    f"https://api.eesi.ai/v1/voices/{voice_id}/preview",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=60,
)
response.raise_for_status()
with open("preview.mp3", "wb") as f:
    f.write(response.content)

A preview is a real synthesis: it costs audio seconds, and it counts against both the per-minute request limit and the free plan’s daily ceiling. GET /v1/voices/{voice_id}/sample is the cheaper sibling. It returns a short-lived signed URL for the reference clip itself — the recording for a clone, the frozen design output for a built-in — so playing a voice in a library list costs a storage read rather than a GPU pass:

{ "url": "https://storage.example.com/...", "content_type": "audio/wav" }

To hear arbitrary text in a voice, use text to speech with voice set to the id.

Rename, and delete

# Rename. `name` is the only mutable field.
curl -X PATCH "https://api.eesi.ai/v1/voices/$VOICE_ID" \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dana (support)"}'

# Erase the clip, then the row.
curl -X DELETE "https://api.eesi.ai/v1/voices/$VOICE_ID" \
  -H "Authorization: Bearer $EESI_API_KEY"

The name is the only thing you can change, on purpose. Everything else on the row describes the recording, and a voiceprint whose reference audio could be swapped after consent was attested would make the attestation meaningless. Deleting means the bytes are gone: the reference clip, the cached prompt encoding and any rendered preview all go, and then the row. If storage refuses, nothing is deleted and the voice stays visible so the delete can be retried — better than half-succeeding in silence. Built-in voices refuse both operations with a 400.

A cloned voice is erased automatically three years after its last use. Using it resets the clock, so a voice in production never expires out from under you, but one cloned once and shelved will go, along with its reference audio. Built-in voices are synthesized rather than recorded from a person and have no such clock.

Designing a voice instead of cloning one

When you do not need a specific person, describe a voice rather than recording one. The accepted vocabulary is a fixed list the serving model publishes rather than free text, so read it instead of guessing:

curl https://api.eesi.ai/v1/audio/voice-design \
  -H "Authorization: Bearer $EESI_API_KEY"

The response groups the terms by category — gender, age, pitch, style, accent. Pass a description built from them as instructions on POST /v1/audio/speech, with voice left as auto. A described voice carries no likeness rights and no retention clock, and it is also not a stable speaker: if you want the same voice tomorrow, the built-in library is where designed voices live once they have been frozen to a clip.

Cost and limits


Clone	100 credits, charged when the voice row is created. Deleting the voice does not refund it.
Free plan	Exactly one clone, ever. The next attempt is a `403 plan_required` until the organization buys credits.
Balance	A clone needs the full 100 credits available, not the ordinary small floor, so a near-empty account is refused with `429 insufficient_quota`.
Upload	10 MB, `audio/*`.
Sample URLs	Signed for 15 minutes. A preview is not a URL; it streams mp3 back on the request.
Retention	Three years from last use, then automatic erasure.

Status	`code`	What happened
400	—	`consent_attested` was missing or `false`.
400	—	The file is empty, or its content type is not audio.
400	—	You tried to rename or delete a built-in voice.
403	`plan_required`	The free plan’s single clone is spent.
404	—	No voice with that id in your organization. A voice from another organization is a 404, not a leak.
413	`content_size_limit_exceeded`	The clip is over 10 MB.
429	`insufficient_quota`	The balance cannot cover 100 credits.
502	—	The reference audio could not be erased, so nothing was deleted. Retry.
503	—	Preparation could not be scheduled. The voice was not created.

Voice cloning

What makes a clip good, and what a bad one sounds like.

Clone a voice

Upload, preview, and use the id in both places.

Text to speech

Where the voice field goes.

Live

Setting the voice on a live session.

Start here

Realtime interaction

Speech

Platform

The invariant

Where a `voice_id` is read

Clone a voice

Cloning is asynchronous

`ref_text` no longer does what it looks like

Hear it before you commit

Rename, and delete

Designing a voice instead of cloning one

Cost and limits

Next

Voice cloning

Clone a voice

Text to speech

Live

​The invariant

​Where a voice_id is read

​Clone a voice

​Cloning is asynchronous

​ref_text no longer does what it looks like

​Consent is checked before the audio is read

​Hear it before you commit

​Rename, and delete

​Designing a voice instead of cloning one

​Cost and limits

​Next

Voice cloning

Clone a voice

Text to speech

Live

The invariant

Where a `voice_id` is read

Clone a voice

Cloning is asynchronous

`ref_text` no longer does what it looks like

Consent is checked before the audio is read

Hear it before you commit

Rename, and delete

Designing a voice instead of cloning one

Cost and limits

Next