Update a Digital Human

This documentation explains how to update an existing Digital Human head configuration using the platform API.

The process to updating a Digital Human is very similar to that detailed in Create a Digital Human except that the PUT head/update endpoint is used, and instead of using the headVisualId as the primary identifier, the headId generated after creating the Digital Human is used.

Endpoint

URL: https://platform-api.unith.ai/head/update
Method: PUT
Description: This endpoint allows you to modify the configuration of a Digital Human head.

warning_amber

Important Note on Partial Updates

The request body for this endpoint should only contain the parameters you wish to update. Do not include the entire default request body or any fields with "string" as their value. Sending an empty or incomplete body can lead to unintended configuration changes or errors.

For a detailed explanation of each available parameter, please refer to the Digital Human Configuration Parameters.

Update Head Payload

Example: Updating an Existing Digital Human's Voice

To update only the voice and TTS provider for an existing Digital Human, your request body should only contain the id, ttsProvider, and ttsVoice parameters.

For more information on available voice options and their capabilities, please visit Voice Connectors

code

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",
  "ttsProvider": "ttsProvider of your choice",
  "ttsVoice": "voiceID"
}'

Replace yourHeadId, ttsProvider of your choice, and voiceID with the appropriate values for your configuration. Please refer to the following documentation to understand all the parameters available.

info

If you are using the GET /head/{id} endpoint before updating your digital human, you must first filter out certain parameters from the response. This is essential, as including them in the subsequent update will cause the process to fail.

Please follow the instructions below.

Retrieving current configuration of your existing digital human:

You can use the following endpoint to get the complete configuration of your digital human.

code

curl -X 'GET' \
  'https://platform-api.unith.ai/head/yourHeadId' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearer'

Please filter out the following parameters from the response before updating the digital human. If any of these parameters are accidentally included in the request, they will be ignored and their values will remain unchanged:

code

createdAt
updatedAt
publicId
promptConfig.id
documentJsonDto
documentUrl
encodedPath
iconConfig
headVisualId
isActive
orgId
orgPublicId
allowedOrigins
allowedIframeOrigins
videoCache
conversationSettings
splitter
expirationSeconds
ttsStream
organisation: {
  id
  createdAt
  updatedAt
  apiKey
  name
  publicId
  alias
  subscriptionType
  slots
  streaming
  isActive
  }
headVisualVideoUrl
posterVideoImage
ttsDisplayName

For example, a correct PUT /head/update request after filtering would look like this:

code

{
  "id": "yourHeadId",
  "name": "digitalHumanName",
  "alias": "digitalHumanAlias",
  "language": "en-US",
  "languageSpeechRecognition": "en-US",
  "phrases": [
    "phrase1",
  ],
  "ttsProvider": "yourTtsProvider",
  "operationMode": "oc",
  "ocProvider": "playground",
  "promptConfig": {
    "system_prompt": "yourSystemPrompt"
  },
  "ttsVoice": "yourTtsVoice",
  "greetings": "Hi there!",
  "voiceflowApiKey": null,
  "customWords": {
    "AI": "A eye",
    "UNITH": "junith"
  },
  "publicUrl": "https://xxxxx.unith.ai/ORG/headId?api_key=06d8axxxxx407d86",
  "fileUrl": null,
  "pluginOperationalModeConfig": null,
  "isRandomSuggestions": true,
  "semanticThreshold": 0
}

scheduleLast updated Feb 18, 2026