latestOpenAPI 3.1.12026-08-22330162.7 KB

35448566f143

Elements

Create an element

Saves a reusable element (a person/character, product/prop, or place) with a reference photo.

Photo source, one of:

imageUrl: a public URL; we download and store it.
imageAssetId: an asset from POST /uploads with purpose element-image.

After creating: mention it in scripts as @handle (returned in the response) to put it in faceless videos, or use a character's id as avatarId for talking-head videos.

The photo is the single source of truth for how the element looks. Use description for context (what it is, when to use it), never for appearance.

post/elements

Request body

namestring required

Element name, used to build the @handle. Letters, numbers, spaces, and hyphens work best (e.g. "Dhiva", "Red Bottle").

type'character' | 'prop' | 'location' required

character = a person or mascot (also usable as an avatar), prop = an object or product, location = a place.

descriptionstring

Optional context notes (what it is, when to use it). Do NOT describe appearance; the photo decides how the element looks.

imageUrlstring

Public URL of the reference photo (JPEG, PNG, or WebP, max 25MB). We download and store it. Use this OR imageAssetId.

imageAssetIdstring uuid

An asset from POST /uploads with purpose element-image. Use this OR imageUrl.

Response

idstring uuid required

Element ID. For characters, this is also a valid avatarId for avatar videos.

namestring required

Element name.

handlestring required

Mention this element in a video script as @handle to put it in the video.

type'character' | 'prop' | 'location' required

character = a person or mascot, prop = an object or product, location = a place.

descriptionstring nullable required

Optional context notes. Appearance always comes from the photo, not from this text.

customboolean required

True for elements you created, false for built-in ones.

previewImageUrlstring nullable required

The reference photo.