Creating Head Visuals

this document describes how premium users with api access can create custom head visuals this feature enables you to create personalized visual representations of digital humans a head visual is a fundamental requirement for successfully deploying a new digital human it comprises of a video that is preprocessed by the unith synthesis engine this video is then used as the basis for defining a head visual object that is effectively the face used for 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 please refer to this file to follow the best practices when creating new video our synthesis pipeline works with 16 9 hd videos (1280x720p) in 25fps https //archbee doc uploads s3 amazonaws com/qelxhuxaai6vrgbp6s4oh hv6qpxqfsda7paqilxfkj 20250505 074810 pdf 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 headers accept application/json authorization bearer \<yourauthbearertoken> (replace \<yourauthbearertoken> with your actual authorization token) content type multipart/form data 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 headers accept application/json x head video token id \<yourtemporaryvideotoken> (replace \<yourtemporaryvideotoken> with the token from the /video/upload response) authorization bearer \<yourauthbearertoken> (replace \<yourauthbearertoken> with your authorization token) content type application/json 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 headers accept application/json authorization bearer \<yourauthbearertoken> (replace \<yourauthbearertoken> with your authorization token) content type application/json 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" 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 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 4\ assign head visual to organization endpoint /head visual/assign organisation method put description assigns the newly created head visual to your organization, making it available for use request headers accept / authorization bearer \<yourauthbearertoken> (replace \<yourauthbearertoken> with your authorization token) content type application/json request body { "id" "yourheadvisualid", // the head visual id from the /head visual/save response "orgids" \[ "yourorgid" // your organization id ] } request parameters id (string, required) the id of the head visual to assign (obtained from the /head visual/create or /head visual/save response) orgids (array, required) an array containing the id(s) of the organization(s) to which the head visual should be assigned in most cases, this will be an array with a single organization id curl example curl x 'put' \\ 'https //platform api unith ai/head visual/assign organisation' \\ h 'accept / ' \\ h 'authorization bearer yourauthbearertoken' \\ h 'content type application/json' \\ d '{ "id" "yourheadvisualid", "orgids" \[ "yourorgid" ] }' response status code 200 (ok) response body (presumably empty, but include an example if available) post assignment after successful assignment, the new head visual will be accessible within the interface platform and/or via the api, depending on your system configuration error handling the endpoint will return standard http error codes for invalid requests, missing parameters, or if the head visual id or organization id is invalid