# Elai Documentation

> Documentation for Elai

## API Reference: Introduction
- [Getting Started With API](https://elai.readme.io/reference/getting-started-with-your-api.md): A step-by-step guide on getting started with using the Elai API.
- [API Use Cases](https://elai.readme.io/reference/api-use-cases.md)
- [Authentication](https://elai.readme.io/reference/authentication.md)
- [Errors and Limitations](https://elai.readme.io/reference/errors.md)
- [Prompt to video](https://elai.readme.io/reference/prompt-to-video-walkthrough.md)
- [Uploading media](https://elai.readme.io/reference/uploading-media.md)

## API Reference: Personalization API
- [Create personalized videos](https://elai.readme.io/reference/personalization.md): Using this API, you can generate multiple videos from just one video as a source. Just pass your customers' names and/or other important data via an API request or Zapier and get a personalized video…

## API Reference: Video API
- [Render a video](https://elai.readme.io/reference/render-video.md): Render an existing video that was created before using another request, or with Elai Builder. It can also trigger the re-rendering of failed videos of previous batch requests.  > ❗️ This endpoint…
- [Retrieve a video](https://elai.readme.io/reference/retrieve-video.md): Usable endpoint to retrieve a video's information, including rendering status.
- [Render/create a personalized batch](https://elai.readme.io/reference/render-personalized.md): Request to render or create a batch of videos (one or more) from a template.  At most **200** rows per request (`templateData`); beyond that the call is rejected with a `400`. Every generated video…
- [Update a video](https://elai.readme.io/reference/update-video.md): Usable endpoint to synchronise actual video information, including name, tags and slides.
- [Delete a video](https://elai.readme.io/reference/delete-video.md): You can use this endpoint to completely delete a video.
- [List videos](https://elai.readme.io/reference/list-videos.md): Usable endpoint to retrieve all of the videos' information, with filtering and sorting.
- [Create a video](https://elai.readme.io/reference/create-video.md): Request to create a new video.
- [Create from text, HTML or URL](https://elai.readme.io/reference/create-from-text-url.md): Generate a new video from URL, HTML or plain text.  The `{type}` segment selects the parser, and only `html` is special: anything else is read as plain text, which is why an invented `type` appears…
- [Copy/transform video](https://elai.readme.io/reference/copy-video.md): This API allows to duplicate videos and templates, as well as turn videos into templates and vice versa.
- [Translate video](https://elai.readme.io/reference/translate.md): Translate video into a new language
- [Create from PPTX/PPT](https://elai.readme.io/reference/create-from-pptx.md): Create a new video from ppt/pptx presentation
- [Upload custom voice](https://elai.readme.io/reference/upload-custom-voice.md): Use this API to upload custom mp3 file as your voice for specific slide.  Rate limited to **20 requests per minute** and **200 per hour**. This limit applies to every caller, not only API tokens.…
- [Copy/transform video (legacy alias)](https://elai.readme.io/reference/copy-video-by-template.md): Legacy alias of [`POST /videos/copy`](#operation/copy-video) — the same handler is mounted under both paths, so behaviour, request body and responses are identical.  Kept working for older…
- [Get the player payload for a video](https://elai.readme.io/reference/retrieve-player-payload.md): Returns the video shaped for the embedded interactive player — the payload the player runtime consumes, rather than the editable video document. Use `GET /videos/{videoId}` for editing and this for…
- [Get the source links of an AI summary video](https://elai.readme.io/reference/retrieve-video-source-links.md): For videos generated as an **AI summary of a Panopto session**, returns the original session's name and viewer URL, plus the containing folder and how many videos are in it.  Only meaningful for that…
- [List a video's exports](https://elai.readme.io/reference/list-video-exports.md): Lists the times this video was exported to an external system, newest first, with the user who did it.  Defaults to `target=panopto`; only entries matching the requested target are returned.…
- [Download a SCORM package](https://elai.readme.io/reference/download-scorm-package.md): Builds a SCORM package for the video and streams it back as a **zip file** (`Content-Type: application/zip`) — not JSON. The package is built on demand and deleted from the server once the response…
- [Inspect a presentation before importing it](https://elai.readme.io/reference/inspect-presentation.md): Uploads a PPTX/PDF and reports how many slides it has and how many of them have no speaker notes to use as speech — the pre-flight check before `POST /videos/from-presentation`.  Nothing is created…
- [Apply a brand kit to a video](https://elai.readme.io/reference/apply-brand-kit.md): Applies brand colours and/or a logo from a brand kit to the video.  Scope is controlled by the flags: `applyColors` and `applyLogo` choose what is applied, `allSlides` whether it covers the whole…
- [Get a video's edit history](https://elai.readme.io/reference/list-video-edit-history.md): Returns the video's name and its `VideoEditHistory` entries, each with the user who made the change.  > The handler logs and swallows any error instead of returning one, so a failure produces **no…

## API Reference: Story API
- [Story API overview](https://elai.readme.io/reference/story-api.md)
- [Apply template](https://elai.readme.io/reference/apply-template.md): Change slide visuals to new template
- [Generate slides/convert story](https://elai.readme.io/reference/generate-slides.md): Generate slides visuals from story texts
- [Append slides from pasted HTML](https://elai.readme.io/reference/paste-story-html.md): Parses an HTML fragment, splits it into slide-sized chunks with speech text, and appends the result to an existing video — the "paste rich text into the editor" path.  Behaviour worth knowing: -…
- [Full control](https://elai.readme.io/reference/story-exact-slides-match.md): Have a full control over matching your template slides with real values

## API Reference: AVATARS API
- [Avatar API Overview](https://elai.readme.io/reference/avatar-api-overview.md)
- [Avatars list](https://elai.readme.io/reference/avatars-list.md): Get all available avatars
- [Update avatar](https://elai.readme.io/reference/update-avatar.md): Use this method to set your custom avatar name and id, and to upload your video avatar's footage
- [Get one avatar](https://elai.readme.io/reference/retrieve-avatar.md): Returns a single avatar with its variants. Readable when the avatar belongs to your organization, is in the public catalog, or your workspace is on its `accountIds` allowlist.

## API Reference: Users api
- [List users](https://elai.readme.io/reference/list-users.md): Get the list of users in your account
- [Invite user](https://elai.readme.io/reference/create-user.md): Invite user to your account. User will receive an email with instructions to set the password.
- [Update user](https://elai.readme.io/reference/update-user.md): Change user data
- [Delete user](https://elai.readme.io/reference/delete-user.md): Delete user. All his assets will be assigned to account admin user.
- [Get the current user, workspace and plan](https://elai.readme.io/reference/retrieve-current-user.md): Returns the authenticated identity together with the workspace and organization it belongs to — plan, minute balance, seat limit, brand kits, pronunciation dictionary and the workspace's current…

## API Reference: VOICE API
- [Languages/Voices list](https://elai.readme.io/reference/voices-list.md): List of all supported languages and voices. List is an array of supported languages. Each language is an object with name, male and female, where you can find voices separated by gender.
- [Synthesise speech (voice preview)](https://elai.readme.io/reference/synthesize-speech.md): Renders `text` with the given voice and returns the audio inline as base64, plus its duration and — when available — word/marker timings.  This is the editor's "listen" action, so it has…
- [Get approximate duration](https://elai.readme.io/reference/get-speech-duration.md): You can get approximate duration of your speech before rendering  Provider names are lowercase, and the body is validated strictly — an unknown field, or a capitalised provider such as `Azure`, is…
- [List the workspace's custom voices](https://elai.readme.io/reference/list-custom-voices.md): Lists cloned/custom voices visible to the caller — those owned by the organization, the workspace, or the individual user. Standard catalog voices are not included; use `GET /voices` for those.
- [Preview voice-customization settings](https://elai.readme.io/reference/preview-voice-customization.md): Synthesises a **fixed sample sentence** (translated into the requested locale) with the supplied `stability` and `speed`, so a customization can be auditioned before it is saved. Your own text is not…
- [Submit a custom-voice recording](https://elai.readme.io/reference/submit-custom-voice.md): Attaches a recording to an existing `Voice` document, names it, moves it to status `2` (submitted) and emails the Elai avatars team to begin voice creation. It does **not** train anything…

## API Reference: Webhooks
- [Webhooks overview](https://elai.readme.io/reference/webhooks-overview.md)
- [Subscribe](https://elai.readme.io/reference/webhook-subscribe.md): Subscribe to `video_ready` and `video_error`, or replace the URL of an existing subscription. One webhook per workspace: posting again overwrites what was there.  The body is validated strictly — any…
- [Unsubscribe](https://elai.readme.io/reference/webhook-unsubscribe.md): You can use this endpoint to deactivate an active webhook.
- [Set secret token](https://elai.readme.io/reference/webhook-set-secret-token.md): Set the shared secret we sign each delivery with. Once set, every request carries `Elai-Timestamp` and `Elai-Signature`; without it, neither header is sent.  > ❗️ Subscribe first, then set the secret…

## API Reference: Other
- [Slide structure](https://elai.readme.io/reference/slide-structure.md): A detailed description of structuring each block of a slide.

## API Reference: Outline
- [Create an outline](https://elai.readme.io/reference/create-outline.md): Creates an outline, either from a topic (`prompt`) or from an existing video (`videoId`). Send exactly one of the two — never both. An outline is a stored, editable resource: generate chapters,…
- [Retrieve an outline](https://elai.readme.io/reference/retrieve-outline.md): Returns the outline with its drafts, including any chapters, speeches and quiz questions generated so far.
- [Update an outline](https://elai.readme.io/reference/update-outline.md): Edits the outline in place — this is the review step the retired /gpt flow had no equivalent for. Send `chapters` to replace the chapter set, or `drafts` for finer control; both write to…
- [Generate chapters](https://elai.readme.io/reference/generate-outline-chapters.md): Expands a topic into an ordered set of chapters, each with a title and bullet points, written onto `drafts[]`. Rate limited for API callers.
- [Generate a script](https://elai.readme.io/reference/generate-outline-script.md): Expands every chapter-bearing draft into a voice-over, written to `drafts[].speech`, and moves `status` to `script`. Takes no request body.  **Destructive:** re-running replaces every…
- [Generate quiz questions](https://elai.readme.io/reference/generate-outline-quiz.md): Generates quiz questions from the outline's speeches and adds them as quiz drafts. `quizSettings` here overrides the persisted settings for this call only.
- [Regenerate quiz questions](https://elai.readme.io/reference/regenerate-outline-quiz.md): Replaces the questions on the named quiz drafts.
- [Rewrite speech with instructions](https://elai.readme.io/reference/rewrite-outline-speech.md): Rewrites the speech on the named drafts following explicit instructions. Use this when you know what you want changed; use regenerate-speech to apply a named enhancement instead.
- [Regenerate speech](https://elai.readme.io/reference/regenerate-outline-speech.md): Regenerates the speech on the named drafts, applying `enhancement` as shared instructions. Mirrors the video `generate-speech` flow. Drafts with a chapter are regenerated from that chapter; drafts…
- [Build a video from an outline](https://elai.readme.io/reference/build-outline-video.md): Turns the outline into a video. Every field is optional — omit them all for the default template, no brand kit, and the root folder. Counts against the account's video creation limit. Render the…

## API Reference: LLM
- [Generate speech for slides](https://elai.readme.io/reference/llm-generate-speech.md): Writes speech for the named slides from their on-canvas content, following `enhancement` as instructions. Use this for slides that have no speech yet; use rewrite-speech to change speech that already…
- [Rewrite speech for slides](https://elai.readme.io/reference/llm-rewrite-speech.md): Rewrites the existing speech on the named slides following `enhancement` as instructions.  Replaces the retired `POST /gpt/{videoId}` and `POST /gpt/{videoId}/{slideId}`. Where those took one of ten…

## API Reference: Uploads
- [Retrieve signed URL](https://elai.readme.io/reference/retrieve-signed-url.md): API to retrieve signed URL to upload media directly to our storage
- [Confirm upload](https://elai.readme.io/reference/upload-confirm.md): Confirm that a file has been uploaded successfully
- [List media library assets](https://elai.readme.io/reference/list-uploads.md): Lists the workspace's uploaded assets, newest-updated first by default. `frame`, `audio` and `logo` assets are always excluded — use `GET /uploads/frames` and `GET /uploads/music` for those.  When no…
- [List background-music assets](https://elai.readme.io/reference/list-music-tracks.md): Returns up to **100** audio assets for the workspace, sorted by most recently updated. Not paginated — `offset` and `limit` are ignored.
- [List avatar frames](https://elai.readme.io/reference/list-avatar-frames.md): Lists `frame` assets — the decorative frames that can be placed around an avatar.  Unlike the other upload endpoints this one is **not scoped to your workspace**: it returns every frame in the…
- [Check whether assets are used in videos](https://elai.readme.io/reference/check-upload-usage.md): Given a list of asset URLs, reports which of them are referenced by at least one video in the workspace. Use it before deleting assets to warn about breaking existing videos.
- [Move several assets into a folder](https://elai.readme.io/reference/move-uploads.md): Moves every listed asset into `uploadFolderId`. Omit `uploadFolderId` (or send `null`) to move the assets back to the root of the media library.  The move is all-or-nothing at validation time: if any…
- [Move one asset into a folder](https://elai.readme.io/reference/move-upload.md): Moves a single asset. Omit `uploadFolderId` (or send `null`) to move it to the root of the media library.
- [Delete several assets](https://elai.readme.io/reference/delete-uploads.md): Permanently deletes the listed assets, including the underlying files in object storage. Videos that reference a deleted asset are **not** updated — check `POST /uploads/checkUploadUsage` first.  If…
- [Delete one asset](https://elai.readme.io/reference/delete-upload.md): Permanently deletes an asset and its stored file. Videos referencing it are not updated.  If the asset is the workspace's primary logo, the next available logo is promoted automatically.
- [Upload a background-music track for a video](https://elai.readme.io/reference/upload-music-track.md): Uploads an audio file as a background-music asset for the given video.  Non-MP3 input is transcoded to MP3 with ffmpeg before storage, so WAV, M4A and similar formats are accepted. The stored asset…

## API Reference: Upload folders
- [Create a media-library folder](https://elai.readme.io/reference/create-upload-folder.md): Creates a folder in the media library, optionally nested under `parentUploadFolderId`.  Folder names must be unique within the same parent. Only **root-level** folders count against the plan's folder…
- [Search media-library folders](https://elai.readme.io/reference/search-upload-folders.md): Lists folders matching a Mongo-style `match` filter, always constrained to the caller's workspace.  With no `match.parentUploadFolderId`, only root-level folders are returned. Pass…
- [Get a folder with its children and ancestors](https://elai.readme.io/reference/retrieve-upload-folder.md): Returns one folder with its immediate `children` populated and `parentUploadFolders` — the ancestor chain ordered from the root down.  A `POST` despite being a read: the sort option travels in the…
- [Rename or move a folder](https://elai.readme.io/reference/update-upload-folder.md): Renames a folder, or moves it under a different parent.  **Rename wins over move.** The two operations are mutually exclusive in one call: if `name` is present the folder is renamed and…
- [Delete a folder and everything in it](https://elai.readme.io/reference/delete-upload-folder.md): **Recursive and permanent.** Deletes the folder, every descendant folder, and every asset inside that subtree — including the stored files.  The response returns signed URLs for the deleted assets…
- [Get folder contents summary](https://elai.readme.io/reference/retrieve-upload-folder-info.md): Reports how many assets the folder's whole subtree contains and which of them are referenced by videos. Intended as the confirmation step before a recursive delete.
- [Get a folder's breadcrumb trail](https://elai.readme.io/reference/retrieve-upload-folder-breadcrumbs.md): Returns the path from the media-library root to the folder, ready to render as breadcrumbs. The first entry is always the synthetic root (`{ name: 'Media library', id: null }`).  Each entry carries…
- [List all folder names](https://elai.readme.io/reference/list-upload-folder-names.md): Returns just the names of every media-library folder in the workspace, at any depth — used to check name collisions before creating a folder. No ids, no nesting information.

## API Reference: Templates
- [List slide templates](https://elai.readme.io/reference/list-templates.md): Lists the templates available to the workspace: its own private templates first, then the shared public catalog.  Sorting is fixed — by aspect ratio (16:9, then 1:1, then the rest), private before…
- [Get one slide template](https://elai.readme.io/reference/retrieve-template.md): Returns a single template with its full slide content and signed asset URLs — enough to create a video from it via `POST /videos/copy`.  Private templates are readable only by the workspace that owns…

## API Reference: Voice customizations
- [List voice customizations](https://elai.readme.io/reference/list-voice-customizations.md): Lists every saved voice customization in the workspace. A customization is a named bundle of TTS settings (stability, speed, similarity, style) bound to one voice, referenced from a slide via…
- [Create a voice customization](https://elai.readme.io/reference/create-voice-customization.md): Creates a named settings bundle for a voice.  Two mutually exclusive shapes, discriminated by `customVoiceId`: - **standard voice** — send `language` **and** `locale`, and no `customVoiceId`; -…
- [Update a voice customization](https://elai.readme.io/reference/update-voice-customization.md): Updates the `name`, the `settings`, or both. At least one of the two must be present, and `settings` is replaced wholesale rather than merged — send all four values.
- [Delete a voice customization](https://elai.readme.io/reference/delete-voice-customization.md): Deletes the customization and cascades: slides referencing it are cleared and the affected cached audio is invalidated, so those slides re-synthesise with plain voice settings on the next render.

## API Reference: Quiz
- [Generate quiz questions from a video](https://elai.readme.io/reference/generate-quiz-from-video.md): Reads the speech text of the selected slides and generates quiz questions with an LLM.  Nothing is saved: the questions come back for the caller to place on slides (`PATCH /videos/{videoId}`).…
- [Rephrase or regenerate one quiz question](https://elai.readme.io/reference/regenerate-quiz-question.md): Takes an existing question and returns a new version of it. Stateless — nothing is persisted.  Two modes, with mutually exclusive knobs:  **`rephrase`** — improve the wording. Answer count, quiz type…
- [Render a quiz question to canvas objects (test endpoint)](https://elai.readme.io/reference/build-quiz-question.md): > **Test endpoint.** It exists to verify quiz rendering on the video-render service and is not used by the Elai web app, which builds question objects in the browser. Treat the response shape as…

## API Reference: Live streams
- [List live-avatar streams](https://elai.readme.io/reference/list-streams.md): Lists the workspace's streams, newest first, 50 per page.
- [Open a live-avatar stream](https://elai.readme.io/reference/open-stream.md): Allocates a GPU host, starts a WebRTC session and returns the SDP offer to answer.  The handshake is: `POST /streams` → answer the offer with `PUT /streams/{streamId}` → trickle ICE candidates with…
- [Re-negotiate an open stream](https://elai.readme.io/reference/renegotiate-stream.md): Asks the GPU host for a **fresh** SDP offer for an already-open stream — use it to recover a dropped peer connection without losing the session. Answer it with `PUT /streams/{streamId}` as on open.
- [Answer the WebRTC offer](https://elai.readme.io/reference/answer-stream-offer.md): Submits the client's SDP answer, completing the handshake.  If the GPU host rejects the answer the stream is closed server-side — but this endpoint still returns `200 {}`, so check stream status…
- [Close a stream](https://elai.readme.io/reference/close-stream.md): Closes the stream and releases the GPU host, finalising the minutes charge.  Idempotent in the useful direction: closing an id that does not exist returns `200`. Closing an already-closed stream is…
- [Send an ICE candidate](https://elai.readme.io/reference/send-stream-candidate.md): Forwards one trickle-ICE candidate to the GPU host. Call it once per candidate the browser emits.
- [Make the avatar speak](https://elai.readme.io/reference/speak-on-stream.md): Synthesises `text` and streams the avatar speaking it over the open WebRTC connection. Queued behind anything already playing — use `DELETE /streams/render/{streamId}` to cut in.
- [Interrupt the avatar](https://elai.readme.io/reference/interrupt-stream-speech.md): Stops playback immediately and clears anything queued — the barge-in used when a viewer starts talking over the avatar.
- [Get a chat reply for a stream](https://elai.readme.io/reference/stream-chat-reply.md): Runs the built-in demo conversational agent over the supplied message history and returns its reply. Backs the interactive demo on the Elai site; it is not a general-purpose chat API and the…

## API Reference: Account & API tokens
- [Get the workspace API configuration](https://elai.readme.io/reference/retrieve-api-config.md): Returns the workspace's API configuration together with the name and email of the account admin the token resolves to.  An API token always authenticates as the workspace's **admin** user…
- [Rotate the workspace API token](https://elai.readme.io/reference/generate-api-token.md): Generates a new 32-character API token for the workspace and returns it.  > ⚠️ **This rotates the token you are calling with.** The previous token stops working the moment this call succeeds, so a…
- [Revoke the workspace API token](https://elai.readme.io/reference/revoke-api-token.md): Clears the workspace's entire `apiConfig` — the API token **and** the configured outgoing webhook (URL, secret, technical email).  > ⚠️ **Self-revoking and not recoverable.** After this call the…