Avatar

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/waterr-ai/json-schema/waterr-ai-avatar-schema.json",
  "title": "Avatar",
  "description": "A catalog avatar — the visual identity a persona presents in prejoin cards and meetings. Global curated avatars have `owner_membership_id: null`; avatars you generate or upload are owned by your account and visible only to you.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/waterr-ai-api-openapi.yml#/components/schemas/Avatar",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "url": {
      "type": "string",
      "description": "Public image URL. Assigning the avatar copies this into the persona's `avatar` field."
    },
    "category": {
      "type": "string",
      "description": "Business-role category, e.g. `recruiter`, `sales`, `coach`, `executive`, `casual`, `illustrated`, `professional`."
    },
    "gender": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "male",
        "female",
        "neutral"
      ],
      "description": "Drives voice pairing. `neutral` for illustrated/abstract avatars."
    },
    "default_voice_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Suggested voice for this avatar. Applied when you set `sync_voice: true`."
    },
    "source": {
      "type": "string",
      "enum": [
        "curated",
        "generated",
        "uploaded"
      ],
      "description": "`curated` — global catalog. `generated`/`uploaded` — account-owned (generation API coming soon)."
    },
    "orientation": {
      "type": "string",
      "enum": [
        "portrait",
        "landscape"
      ],
      "description": "The avatar's shape, which also decides the meeting layout. `portrait` (3:4) renders a tile beside the participant's camera. `landscape` (16:9, framed like a video call) fills the meeting stage with the participant's camera floating in a corner. Measured from the image at ingest — never taken from the request body."
    },
    "environment": {
      "type": [
        "string",
        "null"
      ],
      "description": "Room the still was shot in, e.g. `hospital-clinic`, `conference-room`, `office-cityview`, `executive-office`, `startup-office`, `broadcast-studio`, `home-study`. `null` for the legacy studio portraits."
    },
    "identity_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "Groups every shape and room of the same face, e.g. `F-3`. Filter on it to offer the same person in another setting. `null` for avatars that are their own identity."
    },
    "video_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Seamless idle loop matching this exact still. When present the meeting plays it under the agent until a live renderer takes over, falling back to the still if it cannot load."
    },
    "owner_membership_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "`null` for the global curated catalog; your membership ID for avatars you own."
    },
    "tags": {
      "type": "object"
    },
    "width": {
      "type": [
        "integer",
        "null"
      ]
    },
    "height": {
      "type": [
        "integer",
        "null"
      ]
    },
    "Voice": {
      "$ref": "#/$defs/Voice"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "Voice": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "partner_voice_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "user_basic_info_id": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}