---
title: "List your elements"
method: GET
path: "/elements"
tags: ["Elements"]
---

# List your elements

`GET /elements`

Returns your saved elements: people/characters, products/props, and places, plus the built-in ones. Elements carry a real reference photo.

**How to use them:** mention an element in a video script as `@handle` (for example `[@Dhiva holding @Red-Bottle] Meet the founder...`) and its photo is fed to the image model, so the same face or product appears consistently across the whole video. Characters can also be used as `avatarId` for talking-head videos.

Create new elements with `POST /elements` or in the AITuber dashboard.

## Query parameters

- `type` 'character' | 'prop' | 'location' — Filter by element type. Omit for all.

## Response `200`

OK

- object[]
  - `id` string, uuid, required — Element ID. For characters, this is also a valid `avatarId` for avatar videos.
  - `name` string, required — Element name.
  - `handle` string, 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.
  - `description` string, nullable, required — Optional context notes. Appearance always comes from the photo, not from this text.
  - `custom` boolean, required — True for elements you created, false for built-in ones.
  - `previewImageUrl` string, nullable, required — The reference photo.

## Other responses

- `401` — 401
- `402` — 402
- `403` — 403

---

[API](https://skmtc.net/aituber/apis/aituber-api.md) · [All operations](https://skmtc.net/aituber/apis/aituber-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aituber/aituber-api/revisions/35448566f143/schema)