# Design a voice from a description

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

`POST /v1/generation/voices`

Designs voice previews from a description of how the voice should sound.
Every preview runs 10 to 60 seconds, the length a v2 avatar's voice
sample needs: a preview under 10 seconds is made once more with a longer
read and dropped if it is still short, and one over 60 seconds is
dropped. A preview whose length the provider did not report has
`durationSeconds: null`.

`sampleText`, when given, is what every preview says, in `language`:
220-600 characters for Latin and Cyrillic scripts, 120-300 for Chinese,
Japanese and Korean, 180-450 for Hindi. Without it, Atmee writes a
greeting from the description, long enough for 10 seconds. Each preview
reports the text it actually speaks (`spokenText`).

Each preview is returned as `upload:<uploadId>`, which `POST /v1/avatars`
(`assets.voice`) and the JSON form of `PUT /v1/avatars/{avatarId}/voice`
take as they are, plus a short-lived `url` to play it. The price,
charging and `Idempotency-Key` work as for
`POST /v1/generation/portraits`. Requires `generation:write` and
`avatars:write`.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | A new UUID minted for this request. Reuse it only to retry the same request: a retry never charges twice and returns the first result. A malformed key, or a key already used with different inputs, gets 400 invalid_input. |

## Request body

- `application/json`: `DesignVoiceRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceDescription` | string | yes | How the voice should sound: age, tone, pace, accent, character. |
| `avatarName` | string | no | The avatar's name; the written sample says it. |
| `language` | string (`en`, `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `vi`, `es`, `de`, `hi`, `ru`) | no | The language the voice speaks. Default `en`. |
| `sampleText` | string | no | What every preview says, in `language` (per-script lengths in the operation's description). Absent, Atmee writes it. |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | The voice previews (or the replayed first result). | `DesignedVoicesResponse` |
| `400` | invalid_input (an Idempotency-Key that is not a UUID or was used with different inputs; an input the operation cannot take, or for a clip one the renderer could not use, named as input_failure image or audio) \| moderation_flagged (the description, name, sample text, prompt or photo was flagged; change it) | `ApiErrorResponse` |
| `401` | Missing or invalid API key -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `402` | insufficient_credits (the balance is below the price; top up, don't retry) \| api_key_spend_cap_reached | `ApiErrorResponse` |
| `403` | insufficient_scope (an API key needs both generation:write and avatars:write) \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| v2_access_required (clips only; the v2 renderer is invite-only and this account has not been let in yet) | `ApiErrorResponse` |
| `409` | request_in_progress (a call with this Idempotency-Key is still running, or its charge could not be confirmed; retry it with the same Idempotency-Key after Retry-After and get its one result, charged once -- a new key could charge twice) \| account_ambiguous (a user token of several accounts without X-Account-Id) | `ApiErrorResponse` |
| `422` | Request body failed schema validation (e.g. a voiceDescription outside 20-1000 characters), or the Idempotency-Key header is missing. | none |
| `429` | rate_limited -- the account has too many generation calls running, or made too many in the last minute; retry after Retry-After. | `ApiErrorResponse` |
| `502` | provider_failed -- no provider returned a usable output; nothing was charged. | `ApiErrorResponse` |
| `503` | generation_unavailable -- this instance does not offer generation. | `ApiErrorResponse` |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voices` | array of `DesignedVoice` | yes |  |
| `language` | string (`en`, `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `vi`, `es`, `de`, `hi`, `ru`) | yes |  |
| `microcreditsCharged` | integer | yes | What this call charged (100 microcredits = 1 credit); 0 on a replay. |
| `replayed` | boolean | yes | True when an earlier call with the same Idempotency-Key was replayed. |
| `failedProviders` | array of string | yes | The providers that returned nothing usable. |