Avatars

An avatar is the face your persona presents everywhere a participant sees it: the prejoin card, the meeting room, and the embed widget. Avatars live in a catalog — a global curated set, plus (soon) avatars you generate or upload, which are private to your account.

Every persona works without an explicit avatar — a default image is used. Reach for these endpoints when you want the persona’s face to match its role: a recruiter that looks like a recruiter, a sales coach that looks the part.

Browse the catalog

curl "https://api.waterr.ai/v1/avatars?gender=female" \
  -H "Authorization: Bearer wai_<your_key>"

string

Business-role category, e.g. professional, recruiter, sales, coach, executive, casual, illustrated.

string

male, female, or neutral (illustrated/abstract avatars).

string

curated (global catalog), generated, or uploaded (your own).

Each avatar returns its id, image url, category, gender, and — when set — a default paired Voice.

Assign an avatar to a persona

curl -X PUT https://api.waterr.ai/v1/personas/PERSONA_UUID/avatar \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "avatar_id": "AVATAR_UUID", "sync_voice": true }'

string

ID from GET /avatars. Takes precedence over url. The avatar’s image URL and gender are copied onto the persona so voice pairing stays coherent.

string

Escape hatch: any hosted image URL. For best results match the catalog’s framing — 3:4 portrait, face centered, eyes about a third from the top — since the same image is cropped into circles and cards across the meeting UI.

boolean

default:"false"

When true and the avatar has a default voice, the persona’s voice_id switches to it.

You can also pass avatar_id directly when creating or updating a persona.

Create your own avatar

Point us at any hosted image and we take it from there: the image is fetched once, validated, and re-hosted on WaterrAI storage with immutable cache headers. Meetings load the avatar from our infrastructure (and the participant’s browser cache), never from your origin — so a slow CDN, hotlink protection, or a deleted file on your side can’t blank the avatar mid-call. It becomes part of your private catalog (source: uploaded, visible only to your account):

curl -X POST https://api.waterr.ai/v1/avatars \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-cdn.com/avatars/alex.jpg",
    "category": "sales",
    "gender": "male"
  }'

string

required

Public https URL of the image — jpeg, png, or webp; max 10MB; min 128×128px. Fetched once at creation, then never again (the original is kept in tags.source_url for reference). Match the catalog framing — 3:4 portrait, face centered, eyes about a third from the top — since the same image is cropped into circles and cards across the meeting UI.

string

default:"professional"

Any category string; used for filtering your catalog.

string

male, female, or neutral. Copied onto the persona on assignment so voice pairing stays coherent.

string

Voice UUID from Voices to pair when assigning with sync_voice: true.

Then assign it like any catalog avatar. Deleting an avatar you own removes it from your catalog; personas already wearing it keep the image.

AI avatar generation (describe the avatar you want, or restyle a photo) is coming to this API — the catalog model is already built for it.

All avatar endpoints

Method	Endpoint	Use
`GET`	`/avatars`	List the catalog
`GET`	`/avatars/{id}`	Get one
`POST`	`/avatars`	Create your own
`DELETE`	`/avatars/{id}`	Delete your own
`PUT`	`/personas/{id}/avatar`	Assign to a persona
`DELETE`	`/personas/{id}/avatar`	Clear from a persona

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Voices

Tools

Users

Guides

Integrations

Agent Skills

Avatars

Browse the catalog

Assign an avatar to a persona

Create your own avatar

All avatar endpoints

​Browse the catalog

​Assign an avatar to a persona

​Create your own avatar

​All avatar endpoints

Browse the catalog

Assign an avatar to a persona

Create your own avatar

All avatar endpoints