Configuration parameters allow you to customize and personalize your Digital Human's behavior, appearance, and functionality. These attributes are available across all Digital Human creation methods and can be modified after initial setup to refine the end user experience.

Most parameters can be updated at any time using the Update a Digital Human endpoint.

Conversation Parameters

greetings

This is the welcome message that the Digital Human will deliver to the end user upon first interaction.

• Type: string
  • Example: ["Hi there, I am john"]
• Operating Modes: applies to all

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "greetings": "Hi there, I am John. How can I help you today?"
}'

suggestions

These are a list of menu-like options that suggest to the user what to engage the digital human about. These options are clickable via the UNITH front end.

• Type: list of strings.
  • Example: ["Who is UNITH", "Where are UNITH offices?"]
• Operating Modes: doc_qa, oc

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "suggestions": [
    "Who is UNITH?",
    "Where are UNITH offices located?",
    "Tell me about your services"
  ]
}'

isRandomSuggestions

Controls whether suggestions are displayed in random order or in the sequence defined in your suggestions list.

• Type: true/false
• Values: true (random order) or false (sequential order)
• Operating Modes: doc_qa, oc

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "isRandomSuggestions": true
}'

systemPrompt

Defines the behavioral instructions and personality for your Digital Human. This prompt guides how the Digital Human responds to user queries.

• Type: string
  • Example: ["You are an expert in biology."]
• Operating Modes: doc_qa, oc, plugin

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "systemPrompt": "You are an expert biology professor. Provide clear, educational answers with real-world examples."
}'

Identification Parameters

id

The unique identifier for your Digital Human. This ID is required for all update and management operations.

Type: string (UUID format)

Example: "a412345f-c123-1234-1234-bb85c95e1234"

Operating Modes: All modes

Location: Available in the UNITH interface under Edit > Basic Details

orgPublicId

Your organization's public identifier, visible in the UNITH interface.

• Type: string
• Example: "company"
• Operating Modes: applies to all

alias

The display name shown to end users when they interact with your Digital Human.

• Type: string
• Example: "David Beckham"
• Operating Modes: applies to all

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "alias": "Dr. Sarah Chen"
}'

name

Internal classification name used within the UNITH platform. This is the name we use in the interFace dashboard.

• Type: string
• Example: "beckham"
• Operating Modes: applies to all

videoStreaming

Digital human in streaming mode needs to have videoStreaming set to true. When enabled, some parameters such as splitter is disabled by default.

• Type: boolean
• Example: "true"
• Operating Modes: applies to all

enableEvents

Digital human can send events to an endpoint specified by you. To learn how to use our webhook API, please check the following page.

• Type: boolean
• Example: "true"
• Operating Modes: applies to all

Text-to-Speech (TTS) & Speech-to-Text (STT) Parameters

languageSpeechRecognition

Language code to improve speech recognition. Choose a value supported by Speech service

Type: string (BCP-47 language tag)

Example: "en-US"

Operating Modes: All modes

Reference: Microsoft Azure Speech Service Language Support

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "languageSpeechRecognition": "en-US"
}'

ttsProvider

The text-to-speech engine used for audio synthesis. Available providers include ElevenLabs, Microsoft Azure, and custom Voice Connectors.

Type: string

Example: "elevenlabs", "azure"

Operating Modes: All modes

ttsVoice

The voice that will be associated with the Digital Human. This list is sourced from our Voice Connectors.

Type: string

Example: en-IN-AaravNeural

Operating Modes: All modes

customWords

A dictionary mapping words to their custom pronunciations. Use this to override default pronunciation for brand names, acronyms, or specialized terminology.

Type: object (key-value pairs)

Example: {"UNITH": "You-nith", "API": "A P I"}

Operating Modes: All modes

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "customWords": {
    "UNITH": "You-nith",
    "Xavi": "Ha-vee"
  }
}'

phrases

A list of phrases used to improve speech recognition accuracy for brand names, proper nouns, and uncommon terms that may be difficult to recognize without prior knowledge.

Type: Array of strings

Example: ["UNITH", "Anthropic", "LangChain"]

Operating Modes: All modes

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "phrases": ["UNITH", "Anthropic", "LangChain"]
}'

User Interface Parameters

language

The display language for the UNITH frontend application interface (buttons, labels, system messages).

Type: string (BCP-47 language tag)

Example: "en-US", "es-ES", "fr-FR"

Operating Modes: All modes

Use the endpoint below to retrieve the full list of currently supported UI languages.

curl -X 'GET' \
  'https://platform-api.unith.ai/languages/all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

"ui_languages": {
    "ar-AE": "Arabic (United Arab Emirates)",
    "bg-BG": "Bulgarian (Bulgaria)",
    "bs-BA": "Bosnian (Bosnia and Herzegovina)",
    "cs-CZ": "Czech (Czechia)",
    "de-DE": "German (Germany)",
    "en-US": "English (United States)",
    "es-ES": "Spanish (Spain)",
    "fr-FR": "French (France)",
    "it-IT": "Italian (Italy)",
    "ka-GE": "Georgian (Georgia)",
    "kk-KZ": "Kazakh (Kazakhstan)",
    "lt-LT": "Lithuanian (Lithuania)",
    "lv-LV": "Latvian (Latvia)",
    "nl-NL": "Dutch (Netherlands)",
    "pl-PL": "Polish (Poland)",
    "pt-PT": "Portuguese (Portugal)",
    "ro-RO": "Romanian (Romania)",
    "ru-RU": "Russian (Russia)",
    "sk-SK": "Slovak (Slovakia)",
    "sr-RS": "Serbian (Cyrillic, Serbia)",
    "uk-UA": "Ukrainian (Ukraine)",
    "th-TH": "Thai (Thailand)",
    "hu-HU": "Hungarian (Hungary)",
    "id-ID": "Indonesian (Indonesia)"
  }

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "language": "es-ES"
}'

Operational Mode Parameters

operationMode

Defines the conversational framework and AI capabilities your Digital Human will use to process and respond to user queries.

Type: string (fixed values)

Operating Modes: Set during creation only

See Operation Modes definitions

Advanced Configuration Parameters

These parameters provide fine-grained control over performance, security, caching behavior, and integration settings for your Digital Human.

conversationSettings

Configures the Large Language Model (LLM) provider and specific model used for generating conversational responses.

• Type: object
• Operating Modes: doc_qa, oc, plugin

{
  "conversationSettings": {
    "chat_model_settings": {
      "llm_name": "gpt-4.1-mini-2025-04-14",
      "provider": "openai"
      "api_key": "yourApiKey"
    }
  }
}

Parameters

semanticThreshold

Controls the semantic similarity threshold for retrieving cached responses in conversations. For detailed information on semantic caching and performance optimization, check out the documentation here.

videoCache

Enables or disables video response caching. When enabled, generated video responses are stored and reused for identical or semantically similar queries.

• Type: boolean
• Default: true
• Operating Modes: All modes

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "videoCache": true
}'

ttsStream

Controls whether text-to-speech audio is streamed in real-time or pre-generated before delivery.

• Type: boolean
• Default: false
• Values:
  • true: Audio is streamed as it's generated (lower latency for first audio)
  • false: Audio is fully generated before delivery (more stable playback)
• Operating Modes: All modes

splitter

Controls text chunking behavior for long-form responses. When enabled, responses are split into smaller segments for processing.

• Type: boolean
• Default: false
• Operating Modes: All modes

Security & Embedding Parameters

allowedOrigins

Configures Cross-Origin Resource Sharing (CORS) settings to control which domains can access your Digital Human via web requests.

• Type: Array of strings
• Default: ["*"] (all origins allowed)
• Example: ["https://example.com", "https://app.example.com"]
• Operating Modes: All modes

allowedIframeOrigins

Specifies which domains are permitted to embed your Digital Human within an iframe. Provides an additional security layer beyond CORS.

• Type: Array of strings
• Default: [] (empty - no iframe embedding allowed)
• Example: ["https://trusted-partner.com", "https://internal-portal.company.com"]
• Operating Modes: All modes

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "yourHeadId",
  "allowedIframeOrigins": [
    "https://trusted-partner.com",
    "https://internal-portal.company.com"
  ]
}'

Important Notes

Parameter Updates: Most parameters can be updated multiple times after Digital Human creation using the /head/update endpoint. You can modify multiple parameters in a single request.

Operation Mode Immutability: The operationMode cannot be changed after creation. Plan your operation mode carefully based on your use case requirements.

Voice-Specific Settings: Parameters like customWords are voice-specific and may need adjustment when changing voices.

Voice provider and voice Id: When changing voice provider make sure to also include a specific voice id.

Bearer Token Required: All API requests require a valid Bearer token in the Authorization header.