Changing Digital Human Backgrounds
This document describes how to use the API to replace the background of a Digital Human with a static image. This feature allows for greater customization and flexibility in how Digital Humans are presented.
The ability to change backgrounds is currently available for a select group of head visuals only. To find the head visual ID you'd like to use, please refer to the table below.
The process of changing the background involves several steps, including identifying head visual ID with repleceable background, uploading an image, triggering the background replacement and finally creating and configuring a head visual.
The following endpoints are used in the background replacement process:
We've created head visuals with associated assets that allow easy background replacement. Please identify the head visual ID you would like to replace background to using the folowing table:
Name | Avatar | Head Visual ID |
---|---|---|
Amy | ![]() | 7a2379c8-1c53-4d1e-9fe4-b9af7f3b6534 |
Ava | ![]() | e5c6f5d6-6e6e-4ce5-872d-159bcf2255d9 |
Hal | ![]() | 7af4cbe9-8702-4af8-9c55-e90cee6bfe02 |
Jo | ![]() | f0a341dd-206d-4786-849b-be587a8335dc |
Kai 1 | ![]() | 8810c132-3c67-4b6f-8990-8b822c82e450 |
Kai 2 | ![]() | 41fa882a-2c0c-400a-bce0-c7b45dd3ac85 |
Kai 3 | ![]() | f15bcc91-6f7b-4db5-a39c-8cc55d0c9a8a |
Lev 1 | ![]() | 605bc559-687a-47cb-b31a-4701c322d8ff |
Lev 2 | ![]() | aaa009b7-a54b-472b-922d-51e089390d70 |
Noa 1 | ![]() | 17eaa273-bfa0-4f1b-82ad-dcb4a21a9903 |
Noa 2 | ![]() | b799fe4e-f051-4b3a-87bd-f103b9b8649c |
Pia | ![]() | 3fb6c88a-b568-4cea-adf2-7d4156fd3ded |
If you are interested in creating a completely new head visual with replaceable background, please contact us.
- Endpoint: /image/upload
- Method: POST
- Description: Uploads the static image that will be used to replace the background.
- Request Body: (multipart/form-data)
- Response:
- token: A temporary token for the uploaded image.
- Error Handling:
- Invalid file type (.png, .jpg, .jpeg are allowed).
- File size exceeds the maximum allowed limit.
- Endpoint: /head_visual/replace-background
- Method: POST
- Description: Initiates the background replacement process.
- Request Body:
- Parameters:
- x-head-image-token-id (header)(string, required): The token of the uploaded replacement image.
- id: The ID of one of the head visuals from the table above.
- Response:
- A JSON object containing the URL of the new idle video with the replaced background. For example:
- Error Handling: Handle errors related to the background replacement, including:
- Invalid head visual ID.
- Invalid image token.
- Endpoint: /video/upload
- Method: POST
- Description: Upload the new video with replaced background.
- Request Body: (multipart/form-data)
- Response:
- token: A temporary token for the uploaded video. This token is used in subsequent steps.
- Error Handling:
- Invalid file type (.mp4 allowed).
- File size exceeds the maximum allowed limit.
- Endpoint: /head_visual/create
- Method: POST
- Description: Creates a new head visual using the video with replaced background.
- Request Body:
- Parameters:
- Include all the required parameters for the /head_visual/create endpoint.
- detector_version (string): You may or may not need to include it here, depending on your logic.
- Response:
- A JSON object containing the details of the newly created head visual, including its unique ID.
- Error Handling:
- Invalid video token.
- Ensure cut_timestamp is provided when the processor mode is two_loops.
- Endpoint: /head_visual/save
- Method: POST
- Description: Saves the newly created head visual.
- Request Body:
- Parameters:
- Include all the required parameters for the /head_visual/save endpoint.
- Response:
- A JSON object indicating the head visual has been saved.
- Error Handling:
- Ensure the task exist for a given head_visual_id.
- Check the task status is IN_PROGRESS.
- Endpoint: /head_visual/assign-organisation
- Method: PUT
- Description: Assigns the newly created head visual toy our organization
- Request Body:
- Parameters:
- Include all the required parameters for the /head_visual/assign-organisation endpoint.
- Response:
- A JSON object indicating the head visual has been assigned.
- Error Handling:
- Ensure the task exist for a given head_visual_id and org_id.
- Asynchronous Processing: Background replacement involves synchronous processing. Head visual creation, preprocessing of the video etc.