# AI Speech

An AI Speech is text read out loud by one of your [AI Voices](https://docs.starkinfra.com/api/v2/ai-voice.md). You send the text and the voice id; the response carries the synthesized audio as a base64 MP3.

Synthesis is synchronous: by the time the call returns, the speech is either in `success` status with its audio attached, or the request failed and nothing was produced.

Every speech is stored, so you can fetch its audio again later by id without paying for a second synthesis.

### The AI Speech object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the AI Speech. |
| `voiceId` | STRING | Id of the AI Voice that read the text. |
| `text` | STRING | Text that was read out loud. |
| `status` | STRING | Current status of the speech. Options: "processing", "success", "failed". |
| `audio` | STRING | Base64-encoded MP3 of the synthesized speech. Returned on creation and when the speech is fetched by its id, not in the list. |
| `voiceName` | STRING | Name of the voice that read the text. Only returned when `expand=voiceName` is sent. |
| `errors` | LIST OF STRINGS | Reasons the synthesis failed. Empty while the speech 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 Speech

`POST /v2/ai-speech`

Read a text out loud with one of your voices. The voice must be in `success` status — a clone that is still processing cannot speak yet.

To give an agent a voice, feed it the reply's `speech` field rather than its `text`: `speech` is already stripped of Markdown, URLs and code, which is what makes it sound natural.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `voiceId` | REQUIRED | Id of the AI Voice that should read the text. |
| `text` | REQUIRED | Text to read out loud. Between 1 and 100000 characters. |

**Request**

```python
import starkinfra

speech = starkinfra.aispeech.create(
    starkinfra.AiSpeech(
        voice_id="5656565656565656",
        text="I am sorry about the delay. I can open a delivery check for order 1234 right now."
    )
)

print(speech)
```

**Response**

```python
AiSpeech(
    audio=SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA...,
    created=2022-01-01 00:00:00,
    errors=[],
    id=1212121212121212,
    status=success,
    text=I am sorry about the delay. I can open a delivery check for order 1234 right now.,
    updated=2022-01-01 00:00:01,
    voice_id=5656565656565656,
    voice_name=None
)
```

### List AI Speeches

`GET /v2/ai-speech`

Get the speeches in your workspace, newest first, in chunks of at most 100. The audio is not included — fetch a speech by its id to get it.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `voiceName`. When `fields` is also sent, the expanded attribute must be listed there too. |
| `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

speeches = starkinfra.aispeech.query(expand=["voice_name"])

for speech in speeches:
    print(speech)
```

**Response**

```python
AiSpeech(
    audio=None,
    created=2022-01-01 00:00:00,
    errors=[],
    id=1212121212121212,
    status=success,
    text=I am sorry about the delay. I can open a delivery check for order 1234 right now.,
    updated=2022-01-01 00:00:01,
    voice_id=5656565656565656,
    voice_name=Helena
)
```

### Get an AI Speech

`GET /v2/ai-speech/:id`

Get a single speech by its id, with its audio attached as a base64 MP3.

Send `fields` without `audio` to read the speech's metadata without downloading the file.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the speech entity. |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. The audio is only attached when `fields` is omitted or lists `audio`. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `voiceName`. |

**Request**

```python
import starkinfra

speech = starkinfra.aispeech.get("1212121212121212")

print(speech)
```

**Response**

```python
AiSpeech(
    audio=SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA...,
    created=2022-01-01 00:00:00,
    errors=[],
    id=1212121212121212,
    status=success,
    text=I am sorry about the delay. I can open a delivery check for order 1234 right now.,
    updated=2022-01-01 00:00:01,
    voice_id=5656565656565656,
    voice_name=None
)
```

## 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-speech-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ai-speech-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ai-speech-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ai-speech-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ai-speech-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ai-speech-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ai-speech-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ai-speech-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ai-speech-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ai-speech-curl.md)