Speech to Video

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	`GET /api/v2/stv/avatars`
Create a video	`POST /api/v2/stv`
Get video progress	`GET /api/v2/stv/progress/{id}`
List videos	`GET /api/v2/stv`
Get a video	`GET /api/v2/stv/{id}`
Download a video	`GET /api/v2/stv/{id}/download`
Delete a video	`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. 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:

Pick an avatar: List avatars and take a model_config_id.
Create: Create a video with your audio file and that ID. It returns straight away with status: "queued".
Poll: call Get video progress every few seconds until status is completed, failed or cancelled.
Download: once it’s completed, get the file from Download a video, or from videoAttachment.url in Get a video.

To make the audio in the first place, you can use Text to Speech.

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.
`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).

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. The message text is for humans and may change.

Getting Started

API Overview

Agents & Campaigns

Speech

Authentication

How it works

Video fields

Status values

Errors

​Authentication

​How it works

​Video fields

​Status values

​Errors

Authentication

How it works

Video fields

Status values

Errors