> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olimi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech to Video

> Turn an audio file into a video of an avatar speaking it.

Upload speech, pick an avatar, and get back an MP4 of the avatar saying it, lip-synced to the audio. These endpoints let you create talking-avatar videos from your own systems, and list, download and delete them.

| Endpoint | Request |
| - | - |
| [List avatars](https://docs.olimi.ai/api-reference/endpoint/speech/list-stv-avatars.md) | `GET /api/v2/stv/avatars` |
| [Create a video](https://docs.olimi.ai/api-reference/endpoint/speech/create-stv.md) | `POST /api/v2/stv` |
| [Get video progress](https://docs.olimi.ai/api-reference/endpoint/speech/get-stv-progress.md) | `GET /api/v2/stv/progress/{id}` |
| [List videos](https://docs.olimi.ai/api-reference/endpoint/speech/list-stv.md) | `GET /api/v2/stv` |
| [Get a video](https://docs.olimi.ai/api-reference/endpoint/speech/get-stv.md) | `GET /api/v2/stv/{id}` |
| [Download a video](https://docs.olimi.ai/api-reference/endpoint/speech/download-stv.md) | `GET /api/v2/stv/{id}/download` |
| [Delete a video](https://docs.olimi.ai/api-reference/endpoint/speech/delete-stv.md) | `DELETE /api/v2/stv/{id}` |

## Authentication

Send your API key in the `X-API-KEY` header on every request, to the base URL `https://api-eg.olimi.ai`. See [API Authentication](https://docs.olimi.ai/api-auth.md).

You only ever see the videos that belong to the company your API key is issued to.

## How it works

Video generation runs in the background:

1. **Pick an avatar:** [List avatars](https://docs.olimi.ai/api-reference/endpoint/speech/list-stv-avatars.md) and take a `model_config_id`.
2. **Create:** [Create a video](https://docs.olimi.ai/api-reference/endpoint/speech/create-stv.md) with your audio file and that ID. It returns straight away with `status: "queued"`.
3. **Poll:** call [Get video progress](https://docs.olimi.ai/api-reference/endpoint/speech/get-stv-progress.md) every few seconds until `status` is `completed`, `failed` or `cancelled`.
4. **Download:** once it's `completed`, get the file from [Download a video](https://docs.olimi.ai/api-reference/endpoint/speech/download-stv.md), or from `videoAttachment.url` in [Get a video](https://docs.olimi.ai/api-reference/endpoint/speech/get-stv.md).

To make the audio in the first place, you can use [Text to Speech](https://docs.olimi.ai/api-reference/endpoint/speech/text-to-speech.md).

## Video fields

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The video's ID. |
| `name` | string \| null | Your label, if you sent one. |
| `status` | string | See [Status values](#status-values). |
| `progress` | string | How far along it is, from `"0.00"` to `"1.00"`. A decimal, sent as a string. |
| `configId` | string | The avatar used. |
| `errorCode` | string \| null | Why it failed, when `status` is `failed` or `cancelled`. |
| `errorMessage` | string \| null | A human-readable reason, when it failed. |
| `width` | integer \| null | Video width in pixels. |
| `height` | integer \| null | Video height in pixels. |
| `audioDuration` | string \| null | Length of the audio in seconds, as a string. |
| `videoDuration` | string \| null | Length of the video in seconds, as a string. |
| `audioAttachment` | object | The audio you uploaded: its `id`, `originalName` and `mimeType`. |
| `videoAttachment` | object \| null | The finished video: its `id`, `originalName`, `mimeType` and a temporary `url`. `null` until it's ready. |
| `createdAt` | string | When the video was created (ISO 8601, UTC). |
| `updatedAt` | string | When it last changed (ISO 8601, UTC). |

> [!NOTE]
>
> Responses also carry internal fields. They may change without notice, so rely only on the fields listed on this page.

### Status values

| Value | Meaning |
| - | - |
| `queued` | Waiting to start. |
| `processing` | Being generated. `progress` rises towards `1`. |
| `completed` | Ready to download. |
| `failed` | Generation didn't produce a video. See `errorCode` and `errorMessage`. |
| `cancelled` | Stopped before it finished. |

## Errors

Always branch on `statusCode` first. Errors from this API come in three shapes:

* **`401` and `404`:** `{ "statusCode", "errorCode", "message" }`, for example `errorCode: "stv_job_not_found"`.
* **`400`:** `{ "statusCode", "message", "error" }`. There's no `errorCode`; the `message` says what went wrong.
* **Validation (`422`):** `message` is a list of what went wrong.

| Status | `errorCode` or `message` | When |
| - | - | - |
| `400` | `Audio file is required` | Create only. The request had no `audio` file. |
| `400` | varies | Create only. The video service rejected the job. The `message` says why. |
| `400` | `Failed to fetch avatars from generation service` | List avatars only. The avatar list couldn't be loaded. Try again later. |
| `400` | `Video is not generated or ready for download` | Download only. The video isn't `completed` yet. |
| `400` | `Validation failed (uuid is expected)` | The `id` in the URL isn't a valid UUID. |
| `401` | `unauthenticated` | The `X-API-KEY` header is missing or the key isn't valid. |
| `404` | `stv_job_not_found` | No video with that `id` belongs to your company, or it was deleted. |
| `413` | none | Create only. The audio file is larger than 100 MB. |
| `422` | none | Create only. `configId` is missing. |

An unknown `configId` doesn't return an error: the video is created, then ends with `status: "failed"` and an `errorMessage` saying the configuration wasn't found. Take `configId` from [List avatars](https://docs.olimi.ai/api-reference/endpoint/speech/list-stv-avatars.md).

The `message` text is for humans and may change.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.