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

string

portrait or landscape. Omit to get both. See Portrait or landscape — this is also the meeting’s layout.

string

Every shape and room of the same face, e.g. F-3. Use it to offer the same person in a different setting.

Each avatar returns its id, image url, category, gender, orientation, environment, identity_key, an optional video_url idle loop, and — when set — a default paired Voice.

Portrait or landscape

An avatar carries its own shape, and the shape decides how the meeting is laid out. There is no separate layout setting to keep in sync: assign the face and you have chosen the stage.

`orientation`	Image	In the meeting
`portrait`	3:4, face centered, eyes about a third from the top	A tile beside the participant’s camera
`landscape`	16:9, framed like a video call — head and shoulders, eye-level camera, a real room behind	Fills the stage; the participant’s camera floats in a corner, the way Google Meet shows the active speaker

Landscape avatars in the curated catalog carry an environment naming the room they were shot in — hospital-clinic, hospital-ward, conference-room, conference-glass, home-warm, home-bright, home-study, home-kitchen, home-evening — so you can match the setting to the conversation. identity_key groups both shapes of one face, so the same person can be offered in either layout:

curl "https://api.waterr.ai/v1/avatars?orientation=landscape&identity_key=F-3" \
  -H "Authorization: Bearer wai_<your_key>"

When video_url is present it is a seamless idle loop of that exact still — the meeting plays it under the agent until the live renderer takes over, and falls back to the still if it can’t.

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 one of the two catalog shapes: 3:4 portrait (face centered, eyes about a third from the top) or 16:9 landscape framed like a video call.

string

Optional room label for a landscape avatar, e.g. hospital-ward. Free text — it is shown to your creators when they pick a face.

orientation is measured from the image, not taken from the request body. A 3:4 still labelled landscape would be stretched across the meeting stage, so the image itself decides.

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.

Generate an avatar from a photo

The curated catalog is generated to a spec the live renderer was tuned on: camera at eye level, face centred, mouth closed, webcam framing, a real room out of focus. A selfie rarely matches that — shot from above, tilted, mouth open — and the renderer shows it as lag and drift in the lip-sync. POST /avatars/generate turns any photo of a person into a still that does match, keeping their face and putting them in a room you choose, in either shape.

curl -X POST https://api.waterr.ai/v1/avatars/generate \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://your-cdn.com/photos/priya.jpg",
    "environment": "conference-room",
    "orientation": "landscape",
    "persona": "woman in her 30s in a navy blazer"
  }'

It answers 202 Accepted straight away with the new avatar in status: "generating" and a poll path. Generation takes 20–90 seconds; poll GET /avatars/{id} until status is active (the url is now the still) or failed (tags.generation.error says why). The result is yours (source: generated), shows up in GET /avatars like an upload, and can be assigned to a persona the same way.

string

An avatar you can see — curated or your own — whose face to use. Give this or source_url. The result inherits its identity_key, so one person can be generated into several rooms and still be recognised as one identity.

string

Public https URL of a photo of the person (jpeg, png or webp, max 10MB). Fetched once for the generation and not stored; the generated still is what gets hosted.

string

required

The room. One of the slugs from GET /avatars/environments: home-warm, home-bright, home-study, home-kitchen, home-evening, office-loft, desk-workspace, business-minimal, studio-editorial, hospital-clinic, hospital-ward, conference-room, conference-glass.

string

default:"landscape"

landscape (1920×1080, fills the meeting stage with the participant in a corner) or portrait (810×1080, sits beside the participant’s camera). This is the one place orientation is accepted as input, because here the image is produced to order — the resulting row is still measured and recorded like any other.

string

Optional, up to 300 characters. Describes the same person — age, wardrobe, hair — never the framing or the room, which are fixed. If it conflicts with the photo, the photo wins; it can’t be used to put someone else in the frame.

string

Defaults to the source avatar’s category, else professional.

string

male, female or neutral. Defaults to the source avatar’s.

Generation is metered: 20 per account per rolling 24 hours by default. Past that the endpoint answers 429. A generating row counts, so a client that retries on timeout should poll the row it already has rather than start another.

GET /avatars/environments returns the current room list and the accepted orientations, so a picker never has to hard-code either.

All avatar endpoints

Method	Endpoint	Use
`GET`	`/avatars`	List the catalog
`GET`	`/avatars/{id}`	Get one
`POST`	`/avatars`	Create your own
`POST`	`/avatars/generate`	Generate one from a photo
`GET`	`/avatars/environments`	Rooms available for generation
`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

Memory

Post-Meeting Data

Goals

Voices

Tools

Guardrails

Meeting Skills

Users

Guides

Integrations

Agent Skills

Avatars

Browse the catalog

Portrait or landscape

Assign an avatar to a persona

Create your own avatar

Generate an avatar from a photo

All avatar endpoints

​Browse the catalog

​Portrait or landscape

​Assign an avatar to a persona

​Create your own avatar

​Generate an avatar from a photo

​All avatar endpoints

Browse the catalog

Portrait or landscape

Assign an avatar to a persona

Create your own avatar

Generate an avatar from a photo

All avatar endpoints