# AI Voice

An AI Voice is a cloned voice built from a recording you upload. Once cloned, it can read any text out loud through [AI Speech](https://docs.starkinfra.com/api/v2/ai-speech.md), and it can be attached to an [AI Agent](https://docs.starkinfra.com/api/v2/ai-agent.md) so every reply comes back with a spoken version ready to be synthesized.

Cloning is asynchronous. The voice is created in `processing` status and moves to `success` when it is ready to speak, or to `failed` when the recording could not be cloned. Poll the list until it leaves `processing`.

Send a clean sample of the speaker talking naturally. The audio travels as a base64 string and the format is detected from its own header — MP3, WAV, OGG, FLAC and WebM are all accepted.

### The AI Voice object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the AI Voice. This is the `voiceId` you send to other AI resources. |
| `name` | STRING | Name of the voice. Example: "Helena". |
| `status` | STRING | Current status of the voice. Options: "processing", "success", "failed". Only a voice in "success" can speak. |
| `description` | STRING | Free-text description of the voice. |
| `language` | STRING | Language the voice speaks. Options: "portuguese", "english". |
| `gender` | STRING | Gender of the voice. Options: "male", "female", "neutral". Empty string when none was set. |
| `errors` | LIST OF STRINGS | Reasons the cloning failed. Empty while the voice is healthy. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create an AI Voice

`POST /v2/ai-voice`

Upload a recording and start cloning it. The call returns immediately with the voice in `processing` status.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `audio` | REQUIRED | Base64-encoded recording of the speaker. Up to 10000000 characters. |
| `name` | OPTIONAL | Name of the voice. Up to 100 characters. Defaults to the voice's own id. |
| `description` | OPTIONAL | Free-text description of the voice. Up to 1000 characters. |
| `language` | OPTIONAL | Language the voice speaks. Options: `portuguese`, `english`. Defaults to `portuguese`. |
| `gender` | OPTIONAL | Gender of the voice. Options: `male`, `female`, `neutral`. |

**Request**

```python
import base64
import starkinfra

with open("helena.wav", "rb") as recording:
    audio = base64.b64encode(recording.read()).decode()

voice = starkinfra.aivoice.create(
    starkinfra.AiVoice(
        name="Helena",
        description="Calm Brazilian Portuguese voice for customer support",
        language="portuguese",
        gender="female",
        audio=audio
    )
)

print(voice)
```

**Response**

```python
AiVoice(
    audio=None,
    created=2022-01-01 00:00:00,
    description=Calm Brazilian Portuguese voice for customer support,
    errors=[],
    gender=female,
    id=5656565656565656,
    language=portuguese,
    name=Helena,
    status=processing,
    updated=2022-01-01 00:00:00
)
```

### List AI Voices

`GET /v2/ai-voice`

Get the voices in your workspace, newest first, in chunks of at most 100. This is the call to poll while a clone is being built.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results, returned by the previous call. |

**Request**

```python
import starkinfra

voices = starkinfra.aivoice.query()

for voice in voices:
    print(voice)
```

**Response**

```python
AiVoice(
    audio=None,
    created=2022-01-01 00:00:00,
    description=Calm Brazilian Portuguese voice for customer support,
    errors=[],
    gender=female,
    id=5656565656565656,
    language=portuguese,
    name=Helena,
    status=success,
    updated=2022-01-01 00:02:00
)
```

### Delete AI Voices

`DELETE /v2/ai-voice`

Delete up to 100 voices at once. The ids travel in the query string, not in the body.

The clone is removed from the provider and the stored recording is erased. Speeches already synthesized with the voice are kept.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `ids` | REQUIRED | Comma-separated list of voice ids to delete. Up to 100 ids. |

**Request**

```python
import starkinfra

voices = starkinfra.aivoice.delete(ids=["5656565656565656"])

for voice in voices:
    print(voice)
```

**Response**

```python
AiVoice(
    audio=None,
    created=2022-01-01 00:00:00,
    description=Calm Brazilian Portuguese voice for customer support,
    errors=[],
    gender=female,
    id=5656565656565656,
    language=portuguese,
    name=Helena,
    status=success,
    updated=2022-01-02 00:00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/ai-voice-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ai-voice-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ai-voice-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ai-voice-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ai-voice-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ai-voice-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ai-voice-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ai-voice-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ai-voice-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ai-voice-curl.md)