Avatar Config

AvatarConfig holds the caller’s tenant-level avatar and voice defaults — used by an embedded session when the Agent it’s running against does not itself override a given field (e.g. avatarGlb, ttsVoice on the agent). There is exactly one AvatarConfig per tenant: it is never created directly and never has its own id-based lookup — you always read or write “the current tenant’s config,” full stop.

This page documents the two operations that touch it: avatarConfig (read) and upsertAvatarConfig (create-or-update). For where these defaults actually get used to synthesize speech or transcribe audio at runtime, see Avatar Service REST API — that is a separate REST service that consumes these settings (and any per-agent overrides), not this GraphQL API.

All operations on this page require a valid JWT (Authorization: Bearer <token>) — see Authentication.

Every request in this reference must include the x-huat-platform: customer header in addition to standard GraphQL headers.

The AvatarConfigDto type

Field	Type	Notes
id	Int!	Internal row id — not something you pass back into any mutation; there is only ever one row per tenant.
gender	AvatarGender!	FEMALE | MALE.
glbModel	String!	Default 3D avatar model filename. See agentConfigOptions in Agents for the current catalog of valid values.
voiceTier	VoiceTier!	STANDARD | WAVENET | NEURAL2.
languageCode	String!	Default TTS/STT language code, e.g. en-US.
speakingRate	Float!
liveTalkingUrl	String	Optional override URL for the live-talking/lipsync module.
createdAt	DateTime!
updatedAt	DateTime!

enum AvatarGender {
  FEMALE
  MALE
}

enum VoiceTier {
  STANDARD
  WAVENET
  NEURAL2
}

Note that AvatarGender here (FEMALE/MALE) is a different enum from the Agent-level AvatarGenderCode (F/M) documented in Agents — they are not interchangeable, don’t reuse one value in place of the other.

---

Queries

avatarConfig

Fetches the caller’s tenant-level avatar/voice defaults (used by the embedded avatar SDK when an Agent does not override them).

Auth: JWT

avatarConfig: AvatarConfigDto!

Request

query GetAvatarConfig {
  avatarConfig {
    id
    gender
    glbModel
    voiceTier
    languageCode
    speakingRate
    liveTalkingUrl
  }
}

POST /graphql
Content-Type: application/json
Authorization: Bearer <jwt>
x-huat-platform: customer

Response

{
  "data": {
    "avatarConfig": {
      "id": 1,
      "gender": "FEMALE",
      "glbModel": "avatar-01.glb",
      "voiceTier": "STANDARD",
      "languageCode": "en-US",
      "speakingRate": 1.0,
      "liveTalkingUrl": null
    }
  }
}

---

Mutations

upsertAvatarConfig

Creates or updates the caller’s tenant-level avatar/voice defaults. There is exactly one AvatarConfig per tenant — this always upserts, never creates a duplicate. The first call for a tenant with no existing row creates it; every subsequent call updates the same row in place. Every field on the input is optional — send only what is changing.

Auth: JWT

upsertAvatarConfig(input: UpsertAvatarConfigInput!): AvatarConfigDto!

UpsertAvatarConfigInput fields (all optional)

Field	Type	Notes
gender	AvatarGender	FEMALE | MALE.
glbModel	String
voiceTier	VoiceTier	STANDARD | WAVENET | NEURAL2.
languageCode	String
speakingRate	Float
liveTalkingUrl	String

Request

mutation UpsertAvatarConfig($input: UpsertAvatarConfigInput!) {
  upsertAvatarConfig(input: $input) {
    id
    gender
    glbModel
    voiceTier
    languageCode
    speakingRate
  }
}

{
  "input": {
    "gender": "FEMALE",
    "glbModel": "avatar-01.glb",
    "voiceTier": "NEURAL2",
    "languageCode": "en-US",
    "speakingRate": 1.0
  }
}

POST /graphql
Content-Type: application/json
Authorization: Bearer <jwt>
x-huat-platform: customer

Response

{
  "data": {
    "upsertAvatarConfig": {
      "id": 1,
      "gender": "FEMALE",
      "glbModel": "avatar-01.glb",
      "voiceTier": "NEURAL2",
      "languageCode": "en-US",
      "speakingRate": 1.0
    }
  }
}

Calling this again later with just { "speakingRate": 1.2 } updates the same row’s speakingRate while leaving gender, glbModel, voiceTier, and languageCode untouched.

---

How this relates to Agents and the avatar service

• Tenant-level defaults (this page) — one row per tenant, read via avatarConfig, written via upsertAvatarConfig. Used as the fallback when an Agent doesn’t specify its own avatarGlb, voiceTier, ttsVoice, etc.
• Per-agent overrides — set directly on the Agent (avatarGlb, avatarGender, voiceTier, ttsVoice, ttsLang, speakingRate on AgentDto/CreateAgentInput/UpdateAgentInput) — see Agents and the Agents API reference. An agent-level value always takes precedence over the tenant default when both are set.
• Actual speech synthesis / transcription — happens in a separate REST service, not this GraphQL API. Once an agent’s (or the tenant’s default) voice/avatar settings are resolved, the embedded SDK calls that service directly to synthesize speech and transcribe audio in real time — see Avatar Service REST API.

---

See also

• Agents — conceptual guide to per-agent voice/avatar overrides
• Agents API reference — full field reference for agent-level avatar/voice fields
• Avatar Service REST API — the runtime TTS/STT service that consumes this config
• Evaluation & Export
• API Reference: Overview