--- title: Configuration Parameters slug: configuration-parameters docTags: createdAt: 2024-04-05T09:00:38.270Z --- 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](docId\:Gjy-Qc6AlW5TK6SsCxrpP) endpoint. :::hint{type="info"} Multiple parameters can be changed in a single update request. ::: :::hint{type="danger"} We distinguish between **streaming digital humans** (default) and **legacy synthesizer digital humans** (higher latency). Some parameters such as `text-splitter` or `ttsStream` need to be set accordingly. For embedding of the streaming digital humans, please refer to [our SDK documentation.](https://docs.unith.ai/embedding-streaming-digital-humans-default) ::: # 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 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 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" ] }' ``` :::hint{type="info"} In `doc_qa` mode, suggestions are **automatically generated** when you upload a document. Review and edit these suggestions to match your use case. Each new document upload overwrites the existing suggestions list, so keep a local backup before uploading new documents. ::: :::hint{type="warning"} Suggestions can only be clicked once per conversational session. After a user selects a suggestion, it becomes unavailable for the remainder of that session. ::: ### 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 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 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** :::hint{type="info"} The `id` parameter is required for all Digital Human update operations. You cannot update a Digital Human without providing its ID. ::: ### 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 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.](https://docs.unith.ai/webhook-api-for-digital-human-events) - **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](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=stt) **Type:** `string (BCP-47 language tag)` **Example:** `"en-US"` **Operating Modes:** `All modes` **Reference:** [Microsoft Azure Speech Service Language Support](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=stt) ```curl 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" }' ``` :::hint{type="info"} The default Speech Recognition provider is Microsoft `azure`. When using digital human in **streaming mode** (default) you can use `elevenlabs` as your speech recognition provider with automatic language detection. Please check our embed documentation for more info. ::: ### ttsProvider The text-to-speech engine used for audio synthesis. Available providers include ElevenLabs, Microsoft Azure, and custom [Voice Connectors](docId:7B9hwoMCbM_MR7OGI7R1e). **Type:** `string` **Example:** `"elevenlabs", "azure"` **Operating Modes:** `All modes` :::hint{type="warning"} When updating `ttsProvider`, make sure to include the id of the voice using `ttsVoice` parameter. ::: ### ttsVoice The voice that will be associated with the Digital Human. This list is sourced from our [Voice Connectors](docId:7B9hwoMCbM_MR7OGI7R1e). **Type:** `string` **Example:** `en-IN-AaravNeural` **Operating Modes:** `All modes` :::hint{type="info"} For optimal Digital Human performance, refer to the **[Voice Selection Guide](https://docs.unith.ai/voice-selection-guide-tts)** for recommended voices based on your TTS provider. ::: ### 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 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" } }' ``` :::hint{type="info"} Custom word pronunciations are voice-specific. A pronunciation that works for one voice may not be necessary or appropriate for another. Configure `customWords` independently for each Digital Human based on its assigned voice. ::: ### 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 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` :::hint{type="warning"} In **streaming frontend** mode, the interface language is **automatically detected** from the user's browser settings. For example, if a user's browser is configured to Spanish, the frontend will automatically load in Spanish — no manual configuration required. If you require a language that is not currently supported, contact the UNITH team to request it be added. ::: Use the endpoint below to retrieve the full list of currently supported UI languages. ```curl curl -X 'GET' \ 'https://platform-api.unith.ai/languages/all' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` ### Example: ```json "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)" } ``` *** # 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` :::BlockQuote \{ ... "operationMode": "voiceflow", "voiceflowApiKey": "your voiceflow conversation API key) ... } ::: | **Mode** | **Description** | **Use Case** | | -------- | ----------------------------------------------- | --------------------------------------------- | | `doc_qa` | Document-informed Q\&A using UNITH RAG pipeline | Knowledge bases, FAQ systems, document search | | `oc` | Open conversation powered by ChatGPT | General conversations, customer support | | `ttt` | Text-to-video mode | Pre-scripted video content generation | | `plugin` | Custom conversational engine integration | External AI systems, proprietary chatbots | See [Operation Modes definitions](docId\:HobOROpyEM9TuenMqcf-S) :::hint{type="danger"} Operation modes **cannot be changed** after creation. If you need to change the operation mode, you must create a new Digital Human. ::: *** ## 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` ```curl { "conversationSettings": { "chat_model_settings": { "llm_name": "gpt-4.1-mini-2025-04-14", "provider": "openai" "api_key": "yourApiKey" } } } ``` **Parameters** | **Fiel**d | **Type** | **Description** | **Example** | | --------- | -------- | -------------------------------------- | ------------------------------ | | llm\_name | string | Specific LLM model identifier | "gpt-4.1-mini-2025-04-14" | | provider | string | LLM provider | "openai", "anthropic", "azure" | | api\_key | string | Your api key for the selected provider | N/A | :::hint{type="warning"} Different LLM models have varying response times, token limits, and cost implications. Choose a model that balances performance requirements with your use case needs. ::: ### 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.](https://docs.unith.ai/semantic-cache-for-digital-human-responses) ### 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 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 }' ``` :::hint{type="info"} Enabling video caching significantly improves response times for frequently asked questions. This works in conjunction with `semanticThreshold` settings. ::: ### 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 :::hint{type="danger"} When using streaming mode you need to use a provider that supports audio streaming - `ttsStream`. `Text-splitter` also needs to be disabled in streaming mode. ::: :::hint{type="warning"} Streaming TTS can reduce perceived latency but may introduce audio playback issues on unstable network connections. ::: ### 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` :::hint{type="danger"} Text splitter - `splitter` needs to be **disabled** when using streaming mode, and it should be **enabled** with the legacy synthesizer. This will happen automatically when the videoStreaming parameter is toggled. ::: *** ## 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` :::hint{type="danger"} This parameter is only relevant if you are embedding **non-streaming** digital human. For embeding of the streaming digital human please refer to our SDK documentation. ::: ### 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 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" ] }' ``` :::hint{type="danger"} This parameter is only relevant if you are embedding **non-streaming** digital human. For embeding of the streaming digital human please refer to our SDK documentation. ::: *** ## 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.