Creating Head Visuals

this document describes how to create head visuals—the personalized visual representations of digital humans a head visual is essential for deploying a digital human it consists of a video asset that is preprocessed by the unith synthesis engine this processed video becomes the foundation for the head visual, which serves as the face of your digital human note once a head visual is created, multiple digital humans can share a single head visual id important considerations content policy unith reserves the right to remove any head visual that is deemed offensive, harmful, or inappropriate video best practices before you begin, please refer to our separate documentation on the best practices for creating idle videos for digital humans this will ensure optimal results maximum video length the maximum supported video length for head visual creation is currently 20 seconds for more details on video best practices, please refer to our video guidelines https //docs unith ai/video guidelines for avatar creation process overview the process of creating a custom head visual involves the following steps uploading the source video creating the head visual resource saving the head visual assigning the head visual to your organization api endpoints 1\ upload video endpoint /video/upload method post description uploads the video source for the head visual request body file the video file to upload (e g , video mp4) the file parameter name is important curl x 'post' \\ 'https //platform api unith ai/video/upload' \\ h 'accept application/json' \\ h 'authorization bearer yourauthbearertoken' \\ h 'content type multipart/form data' \\ f 'file=@/path/to/your/video mp4' # replace /path/to/your/video m response status code 200 (ok) response body { "token" "temporary video token" // the temporary token for the uploaded video } response parameters token (string) a temporary, unique token representing the uploaded video this token is required for the next step error handling the endpoint will return standard http error codes for invalid requests, upload failures, or server errors ensure your request is correctly formatted and the video file is valid 2\ create head visual endpoint /head visual/create method post description creates a new head visual resource from the uploaded video request body { "update" false, "detector version" "v2", "detector threshold" 0 2, "mode" "default", "cut timestamp" 0 1, "debug" false } request parameters update (boolean) indicates whether to update an existing head visual (set to false for new) don't change detector version (string) the version of the face detection algorithm to use use "v2" for best results detector threshold (number) the threshold for face detection don't change mode (string) the processing mode "default" is the standard mode don't change cut timestamp (number) the timestamp for cutting the video don't change debug (boolean, optional) if set to true, the response will include a task id if video processing fails, a zip file containing frames and face detection results will be provided for debugging curl example curl x 'post' \\ 'https //platform api unith ai/head visual/create' \\ h 'accept application/json' \\ h 'x head video token id yourtemporaryvideotoken' \\ h 'authorization bearer yourauthbearertoken' \\ h 'content type application/json' \\ d '{ "update" false, "detector version" "v2", "detector threshold" 0 2, "mode" "default", "cut timestamp" 0 1, "debug" false }' response status code 200 (ok) response body { "data" { "id" "yournewheadvisualid", // the unique id of the new head visual "task id" "yourtaskid" // the id of the processing task (only if debug=true) } } response parameters id (string) the unique identifier for the newly created head visual this id is used in subsequent steps task id (string, optional) the id of the video processing task this is only included if the debug parameter was set to true in the request error handling the endpoint will return standard http error codes for invalid requests, missing headers, or server errors 3\ save head visual endpoint /head visual/save method post description saves the head visual resource with the specified metadata request body { "id" "yournewheadvisualid", // the head visual id from the /head visual/create response "name" "youruniqueheadvisualname", // a unique name for the head visual "gender" "male" or "female", // the gender of the digital human "type" "talk" // the type of head visual } request parameters id (string, required) the id of the head visual to save (obtained from the /head visual/create response) name (string, required) a unique name for the head visual this name must be unique within your organization gender (string, required) the gender of the digital human use either "male" or "female" type (string, required) the type of head visual typically, this is "talk" categoryid (string, optional) the category id to assign to the head visual defaults to unset if omitted see the categories section below curl example curl x 'post' \\ 'https //platform api unith ai/head visual/save' \\ h 'accept application/json' \\ h 'authorization bearer yourauthbearertoken' \\ h 'content type application/json' \\ d '{ "id" "yournewheadvisualid", "name" "youruniqueheadvisualname", "gender" "female", "type" "talk" }' response status code 200 (ok) response body an empty string important notes the name parameter must be unique choose a descriptive and unique name for your head visual this endpoint may take some time to process , depending on the length of the uploaded video the head visual status will initially be "pending" until the video processing is complete you may need to check the status of the head visual separately if you need to confirm processing is done this pending state may take a few minutes and correlates to the length of the video being processed the url in the response body will be empty, unless debug was set to true, in which case the url of the debug zip file is returned error handling the endpoint will return standard http error codes for invalid requests, missing parameters, or if the head visual id is invalid it will also return an error if the chosen name is not unique categories as the number of head visuals grows, the platform provides a filtering system to help you organize and locate them efficiently using gender (male, female) and categories when saving a head visual, you can assign it to one of the following categories using its corresponding id endpoint /category/all method get description retrieves the list of existing categories curl x 'get' \\ 'https //platform api unith ai/category/all' \\ h 'accept application/json' \\ h 'authorization bearer yourbearer' in order to add a category to an existing head visual, use one of the existing category ids and assign it in your head visual save endpoint curl x 'post' \\ 'https //platform api unith ai/head visual/save' \\ h 'accept application/json' \\ h 'authorization bearer bearertoken' \\ h 'content type application/json' \\ d '{ "id" "yourheadvisualid", "name" "test video category julie", "gender" "male", "type" "talk", "categoryid" "id" // example 30000000 0000 0000 0000 000000000003 (real) }' reassigning a head visual you can reassign the head visual of an existing digital human at any time to do so, you will need both the head id and the head visual id you want to assign 1\ retrieve your head visual ids to retrieve the head visuals associated with your account, call the following endpoint curl x 'get' \ 'https //platform api unith ai/user/me' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' this returns your user and organization profile, including references to head visuals linked to your organization 2\ assign the head visual once you have both ids, use the following endpoint to reassign the head visual curl x 'put' \ 'https //platform api unith ai/head/assign visual' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' \\ h 'content type application/json' \\ d '{ "id" "yourheadid", "headvisualid" "yourheadvisualid" }' request parameters id (string, required) the unique identifier of the digital human (head) you want to update headvisualid (string, required) the unique identifier of the head visual to assign a single head visual can be shared across multiple digital humans simple head visual post processing guide this document outlines an optional, step by step procedure for post processing your source videos manually to achieve custom idle video this documentation assumes you have recorded your model according to the best practices described in the "creating head visuals" documentation and have a video with a green screen background general post processing procedure (default idle loop) this procedure focuses on creating a short, seamless idle loop for a default head visual 1\ creating the seamless idle loop the goal is to create a short, natural looking idle segment (under 5 seconds) that can be seamlessly looped the total length of your final video must be shorter than 10 seconds select software open your captured video in editing software (e g , davinci resolve, adobe premiere, etc ) identify loop points find a brief segment of the video (ideally less than 5 seconds) where the model's movement (e g , head movement, eye blinking) is natural and smooth avoid brisk or sudden movements , as these are highly visible when looping reverse and duplicate cut the selected segment, duplicate it, and reverse the speed of the duplicated clip by appending the reversed clip to the original, you create a perfect loop where the start and end frames match, ensuring a natural transition try to take one blink during the video, preferably around the middle of the recording — not at the beginning or end this helps create a more relaxed and natural appearance avoid a body or head movement in the first or last frame , we want a smooth movement and this will make the loop transition more noticeable 2\ keying and background removal key the green screen use keying tools (such as those available in after effects or davinci resolve) to accurately remove the green screen background from the subject 3\ adding a custom background select background add a custom background of your choice behind the keyed subject avoid distraction if you use a video background , ensure the movement or activity is minimal this video could also be turned into a loop to blend it better this prevents a noticeable change when transitioning from the static idle state to the active speaking state 4\ color correction and final adjustments color match perform color correction on the foreground (the model) to ensure the lighting and color tone seamlessly match the new background layer this can be done in any professional editing software 5\ exporting the final video the final video must adhere to the following specifications for processing by our synthesis pipeline as mentioned in the “head visual creation” documentation resolution 1280 x 720p (16 9 hd) frame rate 25 frames per second (25fps) format mp4 duration less than 10 seconds total size 3mb maximum key difference two loops video input when creating a video for the two loops (more expressive) head visual this format consists of a single video the creation process is simpler single continuous video you do not need to manually cut and reverse the video (step 1 is skipped) video structure the input video is a single, continuous recording where the first half is the still idle state, ( which will be defined by the cut timestamp) and the second half is the expressive state (e g , subject moving hands, changing facial expression) system handles looping when creating the head visual in two loops mode, you specify the cut timestamp where the transition between the idle and speaking states occurs our system automatically handles the necessary looping and inversion for both the idle and expressive segments to ensure seamless, non jarring transitions this distinction is crucial for two loops , your editing work is focused purely on keying, background, and color correction, as the platform manages the looping mechanism in the first part of the video, follow the same recommendations as for the default idle loop format to ensure a seamless infinite loop include one blink in the first 4 seconds , and another between second 4 and the end this enhances realism and avoids a robotic look as before, avoid noticeable body or head movement in the first or last frame to generate a smooth loop the two loops mode works slightly different between legacy digital humans and digital humans in streaming mode please check this page https //docs unith ai/expressive streaming digital humans for legacy and streaming digital humans using ai generation tools you have the freedom to use a variety of tools, including ai based solutions for video creation, source image generation, or face swapping however, please be aware training data our model was trained on real human video footage, and real video may deliver better performance than visibly ai generated content face detection our synthesis model relies on accurate face detection in every frame of the video ensure that any post processing or ai generation does not interfere with the clarity or consistency of the subject's face happy creating!