# Replace the avatar's voice sample

URL: https://www.atmee.ai/docs/v2/api/reference/avatars/replaceAvatarVoice

`PUT /v1/avatars/{avatarId}/voice`

One 10-60 s recording of clear speech (mp3, wav, m4a, aac, ogg, flac, opus or webm,
<= 12 MB) as the `file` part. Silence, pure tones or heavy noise fail the voice stage.
Or, on an instance that keeps uploads (where `POST /v1/uploads` answers),
`application/json`: `{"voice": "<https URL | upload:<uploadId>>"}`, the
sample by URL or by a `voice` upload, consumed when the replacement succeeds.
Re-runs only the build stages that depend on this part; poll
`GET /v1/avatars/{avatarId}` for progress. Requires `avatars:write`.
A draft is given its voice this way; on v2 it captures the first
candidate once the portrait is there too.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | path | yes |  |

## Request body

- `multipart/form-data`: object
- `application/json`: `AvatarVoiceJsonRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voice` | `AssetRefString` | yes |  |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Accepted; the affected build stages re-run. | `AvatarPartResponse` |
| `400` | invalid_upload (also a JSON body on an instance without uploads, which takes multipart only) \| invalid_manifest \| invalid_url \| fetch_failed \| upload_not_found \| upload_kind_mismatch | none |
| `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 |
| `403` | insufficient_scope \| avatar_not_allowed \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| v2_access_required (engine v2 is invite-only and this account has not been let in yet) | none |
| `404` | avatar_not_found | none |
| `409` | upload_not_ready \| upload_consumed \| upload_expired \| upload_in_use \| account_ambiguous (a user token of several accounts without X-Account-Id) | none |
| `413` | Upload exceeds the size limit | none |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | string | yes |  |
| `status` | string (`building`) | yes |  |