# Voice design

URL: https://www.atmee.ai/docs/v2/api/generation/voices

> 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`](/docs/v2/api/reference/generation/designVoice)
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](/docs/v2/api/create-avatar).

## Design a voice

```bash
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

```json
{
  "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](/docs/v2/api/create-avatar), the JSON form of
[`PUT /voice`](/docs/v2/api/reference/avatars/replaceAvatarVoice), or `audio` in a
[video clip](/docs/v2/api/generation/video). 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](/docs/v2/api/generation).

- [Create an avatar](/docs/v2/api/create-avatar): Build an avatar with the portrait and voice you picked.
- [Video generation](/docs/v2/api/generation/video): Make a clip that speaks the voice.