Voice design
Design a voice from a description of how it should sound, and get previews of 10 to 60 seconds, the length an avatar's voice sample needs.
No recording of the voice you want? POST /v1/generation/voices
designs one from a description and returns voice previews. Each preview runs 10 to 60 seconds, the
length an avatar's voice sample needs, so you can pass it straight to
Create an avatar.
Design a voice
curl -X POST https://api.atmanity.us/v1/generation/voices \
-H "X-Api-Key: $ATMEE_API_KEY" \
-H "Idempotency-Key: 0b6e1f3c-8d2a-4c7e-9f15-2a7d9c4e8b31" \
-H "Content-Type: application/json" \
-d '{
"voiceDescription": "Female, 30-35. Persona: warm resort concierge. Emotion: welcoming, cheerful. Smooth timbre with gentle intonation and a moderate pace.",
"language": "en",
"avatarName": "Val"
}'| Field | Notes |
|---|---|
voiceDescription | Required. How the voice should sound: age, tone, pace, accent, character. 20 to 1,000 characters. |
language | The language the voice speaks: en (default), zh-TW, zh-CN, ja, ko, fr, vi, es, de, hi or ru. |
avatarName | Optional, up to 100 characters. The written sample says it. |
sampleText | Optional. What every preview says, in language. Without it, Atmee writes a greeting from the description. |
Write the description
A shape that works: "<Gender>, <age>. Persona: <2 to 5 words>. Emotion: <2 or 3 adjectives>. <1 or 2 sentences about timbre, pacing and delivery>." For example:
Female, 30-35. Persona: warm friendly guide. Emotion: welcoming, cheerful. Smooth, natural timbre with gentle intonation and a moderate pace.
Ask for an expressive, energetic delivery: it animates better than a flat one.
Write the sample text
Three or four sentences the avatar would say to a visitor, in its language, make the previews sound like a person rather than a generic greeting. The length decides how long a preview runs, so keep it within these limits:
| Script | sampleText length |
|---|---|
| Latin and Cyrillic (English, Spanish, Russian, …) | 220 to 600 characters |
| Chinese, Japanese and Korean | 120 to 300 characters |
| Hindi | 180 to 450 characters |
Don't use a real person's name. A "slower delivery" in the description doesn't make a preview longer; more sample text does.
Choose a preview
{
"voices": [
{
"upload": "upload:4c3b2a19-8f7e-4d6c-b5a4-93827160f5e4",
"url": "https://…/voice.mp3",
"expiresAt": "2026-11-05T09:12:44Z",
"durationSeconds": 18.4,
"spokenText": "Hi, I'm Val, your concierge at Grand Valley…",
"provider": "…",
"unavailable": false
}
],
"language": "en",
"failedProviders": [],
"replayed": false
}Every preview runs 10 to 60 seconds: a shorter one is made once more with a longer read, and
dropped if it is still short. durationSeconds is null when the provider didn't report the
length, and spokenText is the text the preview actually speaks.
Play each url and pick the one that sounds right: how a voice sounds is a judgement only a
listener can make. If none suits you, design again with a changed description or sample text; it's
a new call, charged again.
Pass the chosen upload as it is: assets.voice.url in
Create an avatar, the JSON form of
PUT /voice, or audio in a
video clip. It works for one avatar and expires 24 hours after it
was made. An Atmee V2 avatar's voice is cloned from the preview you pick.
Prices, retries and errors are the same for every generation call: see Generation.
Next steps
Portraits and enhancement
Generate portraits of an invented character from a description, or enhance and restyle a real photo. Up to four options per call, each ready to build an avatar or a clip.
Start a conversation session POST
Starts a full conversation: the avatar listens, thinks and answers in a LiveKit room the visitor joins.