Avatar WEB API

Contents

1   Usage examples

If you want to try out Avatar WEB API in action right now, please see the samples below.

Before you begin, please check our recommendations for improving the resulting model (in the order of significance):

Curl samples
  • metaperson_2.0 sample - authorize, create a Player ID, create an avatar, poll its status, and download its mesh and texture using the curl utility and Exports API. See also frequently asked questions on export parameters usage here: FAQ
  • Selfie code sample - create a selfie upload page and avatar once the selfie is uploaded using the curl utility
Other samples
  • js sample - authorize, create an avatar, poll its status and download its files with Avatar Exports API in JavaScript. Also, visualize the computed avatar with three.js
  • Python script - authorize, create Player ID, create an avatar, poll its status, and download its mesh and texture with Python script

More API usage examples are coming.

2   API basics

Root API URL: https://api.avatarsdk.com/

API endpoints produce JSON responses unless stated otherwise. Please see the Content-Type HTTP Header for a particular response format.

All POST requests accept multipart/form-data unless stated otherwise.

2.1   Authentication with OAuth 2.0

Before any of the API methods can be used, you should generate an application identifier (referenced later as client_id) for your app. This identifier is used to obtain the access token which is then used to sign actual API requests. You could use one of the official libraries listed on the OAuth site (recommended) or any other on your taste to add OAuth 2.0 support to your app.

To get your client_id and client_secret, please sign up for the AvatarSDK developer account.

Besides client_id and client_secret (depending on the application authorization grant type) you will need the following settings:

For more information on grant types, see section 4 of the OAuth 2.0 RFC document.

2.3   Filtering

Results of list-retrieving requests may be filtered by some fields of requested objects (e.g. creation time, status, etc.) by specifying filters as a query parameter. All filters are case-insensitive unless stated otherwise. Filters may be specified several times. In this case, they all will be joined via logical AND. See example below:

$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -X GET "https://api.avatarsdk.com/avatars/?status=completed&description=fb"
> GET /avatars/?status=completed&description=fb HTTP/1.1
> User-Agent: curl/7.35.0
> Host: api.avatarsdk.com
> Accept: */*
> Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu
>
< HTTP/1.0 200 OK
< Date: Mon, 03 Apr 2017 04:08:15 GMT
< Link: <https://api.avatarsdk.com/avatars/?description=fb&status=completed>; rel="first", <https://api.avatarsdk.com/avatars/?description=fb&page=1&status=completed>; rel="last"
< Vary: Accept, Cookie
< Content-Type: application/json
< Allow: GET, POST, HEAD, OPTIONS
<
[...]

Please see the filters section in particular request documentation to find available filters.

2.4   Developer/Client access

API has two different access modes: developer and client access. The Client access mode is slightly more restricted in terms of access to some methods: e.g. it is restricted to list all avatars created with the same client_id and allowed to list only those created with the same PlayerUID, etc.

Please see the detailed description for each particular method to find more information about available access modes and their restrictions.

It is highly recommended to use Client access in applications released into production: malicious users won't be able to access or delete data of other users even if client_id and client_secret are compromised.

Client access mode requires signing each request with a PlayerUID identifier along with the OAuth access token. To do this you need to register PlayerUID once per unique application (e.g. on the first launch) and then sign each request with this PlayerUID via X-PlayerUID HTTP header. See example below:

$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" -X GET "https://api.avatarsdk.com/avatars/"
> GET /avatars/ HTTP/1.1
> User-Agent: curl/7.35.0
> Host: api.avatarsdk.com
> Accept: */*
> Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu
> X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596
>
< HTTP/1.0 200 OK
< Date: Mon, 03 Apr 2017 04:08:15 GMT
< Vary: Accept, Cookie
< Link: <https://api.avatarsdk.com/avatars/>; rel="first", <https://api.avatarsdk.com/avatars/?page=1>; rel="last"
< Content-Type: application/json
< Allow: GET, POST, HEAD, OPTIONS
<
[...]

2.5   Throttling

To keep our system stable and healthy, we introduced a throttling mechanism that limits how many HTTP requests any particular client is allowed to make. Current limits are set to the following values:

  • 75 requests per minute per unique PlayerUID in Client access mode
  • 150 requests per minute for an entire account in Developer access mode

Please note: in the Client access mode there is no limit to the number of requests per SDK account. To avoid throttling, please make sure to follow these guidelines:

  • Make sure you are not using Developer access mode in production
  • Make sure that every user of your app has a unique PlayerUID associated with it, and that all requests are signed with this PlayerUID. Even if your app or game does not have user accounts, you should still register a unique ID for every client or device. Otherwise, you'll face throttling issues

If an application exceeds limits it will receive HTTP 429 TOO MANY REQUESTS response code and Retry-After HTTP Response Header will be set to the number of seconds the application will need to wait to perform the next request. See example below:

$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -X GET "https://api.avatarsdk.com/avatars/"
> GET /avatars/ HTTP/1.1
> User-Agent: curl/7.35.0
> Host: api.avatarsdk.com
> Accept: */*
> Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu
>
< HTTP/1.0 429 TOO MANY REQUESTS
< Date: Mon, 03 Apr 2017 04:08:15 GMT
< Retry-After: 10
< Vary: Accept, Cookie
< Content-Type: application/json
< Allow: GET, POST, HEAD, OPTIONS
<
{"detail":"Request was throttled. Expected available in 10.0 seconds."}

3   Avatars

3.1   Available pipelines

We are constantly working on our avatars' improvements in quality, recognizability, and feature set. This way we have released several avatar pipelines. Each avatar pipeline may have a pipeline subtype - a different set of features available, different model topology, etc. Please find a list of currently available avatar pipelines with their subtypes below (listed in the chronological order).

Please note: the rest of this document describes WEB API for the metaperson_2.0 pipeline. Please find documentation for other pipelines by the link provided in the corresponding section below.

Source photo

3.1.1   animated_face

deprecated

Bald head with the optional set of blendshapes for animations (45 facial, 17 visemes) and separate haircuts.

Documentation is available in the separate document.

Model sample

3.1.2   head_1.2

Predicted head, haircut, and bust. All-in-one model with unique topology. Supports export parameters (multiple formats, unified or separate meshes, textures, etc).

Documentation is available in the separate document.

Model samples

3.1.3   head_2.0

deprecated

Predicted head, haircut, and bust with unique topology. Hairstyle is represented with a separate mesh (except for bust/static subtype), and a bust can be removed (head/mobile subtype). Supports export parameters (multiple formats, unified or separate meshes, textures, etc). Tolerates rotated persons on the source photos (see samples below).

Documentation is available in the separate document.

Model samples

3.1.4   body_0.3

deprecated

Predicted bald head and full body model with fixed topology, predicted and artificial haircuts, and artificial outfits. Predictions of the body shape may be improved by specifying the height, weight, gender, and body measurements of the model. The model skeleton is also available for use with animations. Support various export options via the export parameters (multiple formats, unified or separate meshes, textures, etc).

Documentation is available in the separate document.

Model samples

3.1.5   metaperson_2.0

Evolution of Metaperson subtype of body_0.3 pipeline. Contains blendshapes to customize the face and body after the creation of an avatar, skeleton, and PBR textures. The facial texture has much better quality. Avatar bodies have fixed topology. Support of various export options via the export parameters (multiple formats, unified or separate meshes, textures, etc).

Please note: access via the REST API is available on the Enterprise subscription plan only.

You also can integrate it into your project using an iframe and JS API on the Pro or Enterprise plans. Please visit https://docs.metaperson.avatarsdk.com/ for more information.

Please note: this pipeline utilizes export parameters and static resources

Available subtypes:

  • female, male
Model samples

Available LODs:

  female male
LOD1 LOD2 LOD1 LOD2
avatar part vertices faces vertices faces vertices faces vertices faces
AvatarBody 7131 12672 3409 5604 7131 12672 3347 5494
AvatarEyelashes 6300 4900 130 160 6300 4900 130 160
AvatarHead 7419 14404 1760 3314 7419 14404 1760 3314
AvatarLeftCornea 457 830 138 244 457 830 138 244
AvatarLeftEyeball 481 791 148 200 481 791 148 200
AvatarRightCornea 457 830 138 244 457 830 138 244
AvatarRightEyeball 481 791 148 200 481 791 148 200
AvatarTeethLower 2511 3464 253 406 2511 3464 253 406
AvatarTeethUpper 2497 3654 306 394 2497 3654 306 394
Total 27734 42336 6430 10766 27734 42336 6368 10656

3.2   Pipelines availability on subscription plans

  Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0 body_0.3 metaperson_2.0
base/legacy base/legacy, base/mobile, base/static bust/mobile, bust/static, head/mobile female, male, mobile female, male
Available starting Plus Plus Pro Pro Enterprise

3.3   Computation parameters

Avatar computation parameters contain a set of flags and parameters to fine-tune the avatar computation process. These parameters have two levels of detail:

  1. The first level is the parameter categories. E.g. set of model_info, avatar modifications, etc. Please find all available categories with their description in the sections below.
  2. The second level is parameter types: enumerable and key-value parameters. Avatar computation parameters affect the computation process only if they are specified explicitly. Enumerable parameters are simply listed as JSON arrays, and key-value parameters are specified as JSON objects. The value type is parameter-dependent. Please see the parameter description in the sections below. Please note: all parameters are considered enumerable by default unless stated otherwise.

Please see the parameters retrieval request to retrieve a list of available and default parameters for each particular pipeline and pipeline subtype on your account.

3.3.1   Model info

Avatar SDK is capable of providing some meta-information about computed avatars from source photos like an age, gender, hair and skin color, etc. There are several items that are provided by default (i.e. without explicit request), as well as some items that should be requested explicitly. Please see avatar model information request to find out how to retrieve the computed information.

Items provided by default are:

eye_iris_color : color [1]
Average eye iris color computed from a submitted photo
eyebrows_color : color [1]
Average eyebrows color computed from a submitted photo
hair_color : color [1]
Average haircut color computed from a submitted photo
lips_color : color [1]
Average lips color computed from a submitted photo
pipeline : string
Avatar pipeline requested to compute, i.e. metaperson_2.0
pipeline_subtype : string
Avatar pipeline subtype requested to compute, i.e. female or male
skin_color : color [1]
Average skin color computed from a submitted photo

Please find colors correspondence on the image below

Colors correspondence

Please find the list of items need to be requested explicitly below:

age : string
Classify a person's age from a submitted photo. Currently, possible values are child and not_child. age_confidence also will be present in model_info to represent the confidence of age classification with a value in the range [0.5, 1] inclusive
gender : string
Predict a person's gender from a submitted photo. Possible values are male and female. gender_confidence also will be present in model_info to represent the confidence of gender prediction with a value in the range [0.5, 1] inclusive
race : string

Predict the person race from the submitted photo. Currently, three races are predicted (asian, black, and white) with certain confidence for each race in the range [0, 1] inclusive. The resulting information will include the most probable race with its confidence and a JSON Object with all races with their confidences. Please see the sample model info below:

{
    "race": "white",
    "race_confidence": 1,
    "races": {
        "asian": 5.285300192295339e-13,
        "black": 4.953061250034807e-08,
        "white": 1
    },
}

3.3.1.1   Usage examples

curl
$ curl -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" \
       -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" \
       -X POST \
       "https://api.avatarsdk.com/avatars/" \
       -F "pipeline=metaperson_2.0" \
       -F "pipeline_subtype=female" \
       -F "name=info test" \
       -F "parameters={\"model_info\": [\"age\"]}" \
       -F "photo=@photo.jpg"

{
    "code": "d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91",
    "created_on": "2019-10-01T08:16:03.831260Z",
    "description": "",
    "name": "test",
    "progress": 0,
    "status": "Uploading",
    "url": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/"
}

$ curl -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" \
       -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" \
       -X GET \
       "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/model_info/"

{
    "pipeline": "metaperson_2.0",
    "pipeline_subtype": "female",
    "age": "not_child",
    "age_confidence": 1
}

3.3.2   Avatar modifications

Avatar SDK is aimed at producing recognizable photo-realistic avatars. However, there is demand for avatar modifications, leaving avatars recognizable, though. Please find available avatar modifications below.

Please note: all parameters for this category are key-value, and modify the original avatar respectively its description.

remove_smile : boolean

Attempt to remove a smile on the submitted photo before the actual avatar computation starts. Currently detects and removes mostly open smiles (e.g. smiles with mouth open). The status of a smile removal may be obtained later from the model information JSON Object by the remove_smile key (see avatar model information retrieval request). Please find the model comparison below.

Please note: modifies original photo, thus avatars computed on the same source photo with and without this flag may appear slightly different.

Please note: set to true by default

Models comparison
remove_stubble : boolean

Attempt to remove a stubble on the submitted photo before the actual avatar computation starts. The status of a stubble removal may be obtained later from the model information JSON Object by the remove_stubble key (see avatar model information retrieval request). Please find the model comparison below.

Please note: modifies the original photo, thus avatars computed on the same source photo with and without this flag may appear slightly different.

Models comparison
remove_glasses : boolean

Attempt to remove glasses on the submitted photo before the actual avatar computation starts. The status of glasses removal may be obtained later from the model information JSON Object by remove_glasses key (see avatar model information retrieval request). Please find the model comparison below

Models comparison

3.3.2.1   Usage examples

curl
$ curl -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" \
       -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" \
       -X POST \
       "https://api.avatarsdk.com/avatars/" \
       -F "pipeline=metaperson_2.0" \
       -F "pipeline_subtype=female" \
       -F "name=modifications test" \
       -F "parameters={\"avatar_modifications\": {\"remove_smile\": false}}" \
       -F "photo=@photo.jpg"

3.4   Avatar Assets

MetaPerson avatars may be customized using avatar assets such as different outfits, glasses, jewelries, hair styles etc. Most of the assets are made of a separate set of meshes and textures and should be adjusted for each particular avatar to match it geometry in run time (see notes on blendshapes for each particular asset category section), or may be adjusted during avatar export process. Please see export parameters samples for each particular asset category section to find out how to add an asset to an avatar.

3.4.1   Haircuts

We have a set of artificial haircuts that are modified during the avatar computation process to match each particular avatar head geometry:

metaperson set

A set of haircuts for metaperson_2.0 pipeline

Haircuts samples

Several haircuts have a mirrored version with _mirrored suffix (i.e. Haircut22_mirrored) which looks like below:

Mirrored Haircut22 sample

Please find the list of mirrored haircuts below:

Mirrored haircuts
Haircut1, Haircut4, Haircut5, Haircut6, Haircut7, Haircut8, Haircut9, Haircut11, Haircut12, Haircut13, Haircut14, Haircut16, Haircut17, Haircut18, Haircut21, Haircut22, Haircut23, Haircut24

Please note: in case when avatar head is modified with blendshape from face_modifications set in runtime, corresponding blendshape also should be applied to the selected haircut to avoid meshes intersections. When blendshapes values are specified in the blendshapes section of export parameters, haircuts are modified correspondingly during the export.

generated haircut

This haircut is unique and generated for each particular avatar to match the haircut from the source photo. Please note: if it is detected that the source photo does not have a haircut (i.e. a bald person) - there will be no generated haircut in the list of available haircuts for the computed avatar.

Please note: the generated haircut is specified as HaircutGenerated in export parameters and present as an avatar head blendshape named Haircut. To demonstrate it you also need to blend its texture with the avatar head texture.

Please use haircuts section in the export parameters to add haircuts to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "haircuts": {
    "list": ["Haircut0", "Haircut1", "Haircut2", ...],
    "embed": false,
    ...
  },

  ...
}

It is also possible to add your haircut: contact us at support@avatarsdk.com

Please see the enumerable export parameters retrieval request to retrieve a list of available haircuts for a particular pipeline type and pipeline subtype for your account.

3.4.2   Outfits

Avatar SDK provides artificial outfits for full-body avatars. Each outfit consists of mesh, texture, body visibility mask, roughness, metalness, and normals map. Alpha channel from the body visibility mask should be applied to the avatar body such that the avatar body becomes transparent to avoid body and outfit overlap during avatar animation. Please note: each outfit is provided with a separate body visibility mask, thus the corresponding mask should be applied.

Please note: in case when avatar body is modified with blendshape from body_shape set in runtime, corresponding blendshape also should be applied to the selected outfits to avoid meshes intersections. When blendshapes values are specified in the blendshapes section of export parameters, outfits are modified correspondingly during the export.

metaperson set

Set of complete outfits adapted for metaperson_2.0 avatar bodies.

Female outfits samples
Male outfits samples
outfits_top set

Set of outfits, applicable to the upper body (e.g. t-shirt, hoodie, etc.)

Female outfits samples
Male outfits samples
outfits_bottom set

Set of outfits, applicable to the lower body (e.g. pants, jeans, etc.)

Female outfits samples
Male outfits samples
outfits_shoes set

Set of shoes (e.g. shoes, sneakers, etc.)

Female outfits samples
Male outfits samples

Please use outfits / outfits_top / outfits_bottom / outfits_shoes sections in the export parameters to add outfits to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "outfits": {
    "list": ["Akna", "Arpi", "Chatin", ...],
    "embed": false,
    ...
  },

  ...
}

Please see the enumerable export parameters retrieval request to retrieve a list of available outfits.

3.4.3   Hats

MetaPerson avatars (metaperson_2.0 pipeline) have a set of hats available via the export parameters

Please note: in case when avatar head is modified with blendshape from face_modifications set in runtime, corresponding blendshape also should be applied to the selected hat to avoid meshes intersections. When blendshapes values are specified in the blendshapes section of export parameters, hats are modified correspondingly during the export.

metaperson set

Set of various hats

Female outfits samples
Male outfits samples

Please note: baseball_cap_Vachagan hat currently works best with HaircutGenerated or without haircut at all. In case of HaircutGenerated please set baseball_cap_Vachagan_haircut blendshape on baseball_cap_Vachagan and AvatarHead and unset Haircut blendshape on AvatarHead to avoid meshes intersections.

Please note: Ghutra hat currently may be applied only to avatars without haircut.

Please use hats section in the export parameters to add hats to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "hats": {
    "list": ["baseball_cap_Vachagan"],
    "embed": false,
    ...
  },

  ...
}

3.4.4   Glasses

MetaPerson avatars (metaperson_2.0 pipeline) have a set of glasses available via the export parameters

metaperson set

Set of various glasses

Glasses samples

Please use glasses section in the export parameters to add glasses to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "glasses": {
    "list": ["glasses_00", "glasses_01", ...],
    "embed": false,
    ...
  },

  ...
}

3.4.5   Earrings

MetaPerson avatars (metaperson_2.0 pipeline) have a set of earrings available via the export parameters

metaperson set

Set of various earrings

Earrings samples

Please use earrings section in the export parameters to add earrings to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "earrings": {
    "list": ["earrings_01", "earrings_02", ...],
    "embed": false,
    ...
  },

  ...
}

3.4.6   Necklaces

MetaPerson avatars (metaperson_2.0 pipeline) have a set of necklaces available via the export parameters

Please note: in case when avatar body is modified with blendshape from body_shape set in runtime, corresponding blendshape also should be applied to the selected necklace to avoid meshes intersections. Additionally, blendshape with the selected outfit name should be set for the selected necklace. When blendshapes values and outfits are specified in the blendshapes section of export parameters, necklaces are modified correspondingly during the export.

metaperson set

Set of various necklaces

Necklaces samples

Please note: necklaces are currently compatible with the limited set of outfits: Akna, ARPI, saree_Aramazd, jacket_Arteni, jacket_Tavush, top_Khustup, top_Lessing, t-shirt_ARPI, t-shirt_Vardenis. Additionally, pendant_04 and pendant_05 are not compatible with the jacket_Arteni outfit.

Please use necklaces section in the export parameters to add necklaces to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "necklaces": {
    "list": ["chain_lite", "chain_tight", ...],
    "embed": false,
    ...
  },

  ...
}

3.4.7   Blendshapes

Different blendshapes sets are available, depending on your use case: general animation, lip-sync, overall avatar shape modification, etc. Please consult each blendshapes set description for more information.

Please note: when avatar head/body shape is modified with blendshape in runtime, avatar asset also should be modified with the corresponding blendshape to avoid avatar mesh intersection. When blendshapes values are specified in the blendshapes section of export parameters, avatar assets are modified correspondingly during the export.

body_shape

Set of blendshapes to modify body shape

blendshapes names
Chest-, Chest+, Forearms-, Forearms+, General-, General+, Hips-, Hips+, Legs-, Legs+, Neck-, Neck+, Shoulders-, Shoulders+, Waist-, Waist+,
face_modifications

Set of blendshapes to modify the facial shape

blendshapes names
EyeB_Dn_L, EyeB_Dn_R, Eye_Blink_L, Eye_Blink_R, EyeB_Up_L, EyeB_Up_R, Eye_Dn_L, Eye_Dn_R, Eyelid_Hood_L, Eyelid_Hood_R, Eyelid_RollDn_L, Eyelid_RollDn_R, Eye_Monolid, Eye_SquintH_L, Eye_SquintH_R, Eye_Squint_L, Eye_Squint_R, Eye_Squiz_L, Eye_Squiz_R, EyeT_Up_L, EyeT_Up_R, Eye_Up_L, Eye_Up_R, Eye_Wink_HL, Eye_Wink_HR, Eye_Wink_L, Eye_Wink_R, Face_Lower_In, Face_Lower_Out, Head_Cheek_In, Head_Cheek_Out, Head_Height_Dn, Head_Height_Up, Head_Thick, Head_Thin, Head_Vol_Dn, Head_Vol_Up, Head_Width_Dn, Head_Width_Up, Jaw_Chin_Long, Jaw_Chin_Sharp, Jaw_Chin_Short, Jaw_Chin_Smooth, JawLine_Narrow, JawLine_Widen, Jaw_Narrow, Jaw_Sharp, Jaw_Sides_Dn, Jaw_Sides_Up, Jaw_Smooth, Jaw_Widen, Lips_Large, Lips_Narrow, Lips_Tighten, Nose_Bulge, Nose_Close, Nose_Dn, Nose_Large, Nose_Left, Nose_Long, Nose_Open, Nose_Right, Nose_Sharp, Nose_Short, Nose_Tip_Down, Nose_Tip_Left, Nose_Tip_Right, Nose_Tip_Up, Nose_Up_L, Nose_Up, Nose_Up_R, Nose_Wings_Dn, Nose_Wings_In, Nose_Wings_Out, Nose_Wings_Up, Pupil, Iris_Bigger, Iris_Smaller
mobile_51

Set of 51 facial blendshapes. This set is compatible with Apple ARKit: https://developer.apple.com/documentation/arkit/creating_face-based_ar_experiences

blendshapes names
browDownLeft, browDownRight, browInnerUp, browOuterUpLeft, browOuterUpRight, cheekPuff, cheekSquintLeft, cheekSquintRight, eyeBlinkLeft, eyeBlinkRight, eyeLookDownLeft, eyeLookDownRight, eyeLookInLeft, eyeLookInRight, eyeLookOutLeft, eyeLookOutRight, eyeLookUpLeft, eyeLookUpRight, eyeSquintLeft, eyeSquintRight, eyeWideLeft, eyeWideRight, jawForward, jawLeft, jawOpen, jawRight, mouthClose, mouthDimpleLeft, mouthDimpleRight, mouthFrownLeft, mouthFrownRight, mouthFunnel, mouthLeft, mouthLowerDownLeft, mouthLowerDownRight, mouthPressLeft, mouthPressRight, mouthPucker, mouthRight, mouthRollLower, mouthRollUpper, mouthShrugLower, mouthShrugUpper, mouthSmileLeft, mouthSmileRight, mouthStretchLeft, mouthStretchRight, mouthUpperUpLeft, mouthUpperUpRight, noseSneerLeft, noseSneerRight
visemes_14
Set of 14 visemes (PP, FF, TH, DD, kk, CH, SS, nn, RR, aa, E, ih, oh, ou). This set is compatible with Oculus Lipsync.
visemes_15
Set of 14 visemes (PP, FF, TH, DD, kk, CH, SS, nn, RR, aa, E, ih, oh, ou) and one additional blendshape: Laughter. This set is identical to Oculus Lipsync visemes. You can find more details here: https://developer.oculus.com/documentation/audiosdk/latest/concepts/book-audio-ovrlipsync/

Please find our guides on how to use visemes for lipsync here: https://docs.avatarsdk.com/unity-plugin/3.0.1/additional_samples.html

Please use blendshapes section in the export parameters to add blendshapes to the avatar export like in the sample below:

{
  "format": "gltf",
  "embed": true,

  ...

  "blendshapes": {
    "list": ["face_modifications", "mobile_51", ...],
    ...
  },

  ...
}

Please see the enumerable export parameters retrieval request to retrieve a list of available blendshapes for a particular pipeline type and pipeline subtype for your account.

3.5   Export parameters

Avatar's export parameters contain a set of flags and parameters to specify what resulting avatar downloadable data should include: model format, set of textures, blendshapes, whether to embed all these assets into the one model or save as separate files, etc.

The general format for export parameters is the following:

{
  "flag": value,

  "category": {
    "textures": {
      "list": [values],
      "flag": value
    },

    "list": [values],
    "flag": value
  }
}

Export parameters consist of top-level and category-level flags. Top-level flags are applied to the whole avatar and its categories (unless stated otherwise). Category-level flags are applied only to this particular category and overwrite top-level flags if they are of the same name and specified explicitly.

The category may contain enumerable values (like haircuts). These values must be specified within the list key of this particular category. Please look at the enumerable export parameters retrieval request to retrieve a list of available export parameters for each particular category for the pipeline and the pipeline's subtype for your account.

Top-level and category-level sections may contain an optional textures section. Please look at the enumerable export parameters retrieval request to retrieve a list of available textures for each particular category. Texture lists, flags, and the section itself are also inherited by the categories from the top-level value and may be overwritten at the category level. To export all available textures, you can specify all of them in the top-level textures section, non-existent textures for the particular avatar part will not trigger an error and will be skipped on export computation.

Default export parameters are the following:

{
  "format": "gltf",
  "embed": true,
  "lod": "LOD1",
  "split_vertices": false,
  "export_quads": false,
  "finalize": false,
  "apply_visibility_masks": true,
  "make_public": false,
  "make_public_direct": false,
  "remove_neck_layers": 0,
  "transparent_cornea": false,

  "textures": {
    "list": [],
    "profile": "2K.png",
    "embed": false
  },

  "avatar": {
    "list": [
      "AvatarBody",
      "AvatarLeftCornea",
      "AvatarRightCornea",
      "AvatarLeftEyeball",
      "AvatarRightEyeball",
      "AvatarEyelashes",
      "AvatarHead",
      "AvatarTeethLower",
      "AvatarTeethUpper"
    ],

    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,

    "textures": {
      "list": [
        "Color",
        "GltfMetallicRoughness",
        "Normal"
      ],

      "embed": null                // i.e. top-level value
    },

    "colors": null                 // i.e. no recolor
  },

  "haircuts": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "textures": null,              // i.e. top-level value
    "color": null                  // i.e. no recolor
  },

  "outfits": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,
    "textures": null               // i.e. top-level value
  },

  "outfits_top": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,
    "textures": null               // i.e. top-level value
  },

  "outfits_bottom": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,
    "textures": null               // i.e. top-level value
  },

  "outfits_shoes": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,
    "textures": null               // i.e. top-level value
  },

  "hats": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "apply_visibility_masks": true,
    "textures": null               // i.e. top-level value
  },

  "glasses": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "textures": null               // i.e. top-level value
  },

  "earrings": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "textures": null               // i.e. top-level value
  },

  "necklaces": {
    "list": [],
    "format": null,                // i.e. top-level value
    "embed": null,                 // i.e. top-level value
    "lod": null,                   // i.e. top-level value
    "textures": null               // i.e. top-level value
  },

  "blendshapes": {
    "list": [],
    "values": null,                // no blendshapes deformations
    "embed": true                  // i.e. top-level value
  }
}

See also frequently asked questions on export parameters usage here: FAQ

3.5.1   Available flags

apply_visibility_masks : boolean
Invisible avatar body mesh faces are removed (i.e., specified outfit body_visibility_mask is applied to the mesh). It may be used to explicitly turn off mesh modification for the whole avatar or the particular outfit assets category (e.g. only for shoes). See also FAQ
color : color [1]
If texture supports recoloring, this flag specifies the base color for the recoloring process
colors : JSON object

Recolor avatar parts. Currently supported parts are: skin, lips, eyebrows, iris, sclera. To recolor particular avatar part, specify part: color [1] pair in form of:

...
"colors": {
  "skin": { "red": 210, "green": 166, "blue": 146 },
  "lips": { "red": 187, "green": 127, "blue": 115 },
  ...
},
...

Please note: eyes recoloring requires additional steps, see note in FAQ

embed : boolean

If the avatar format (i.e. top-level format) supports sub-meshes/textures (i.e. fbx, gltf, glb) this flag indicates whether to embed this particular category of meshes/textures into the avatar or store these resources as separate files. If avatar format does not support sub-meshes/textures - the flag is set to false and category meshes/textures are saved as separate files

Please note: the value of the top-level flag is not propagated to the textures section and must be specified explicitly to embed textures. See also FAQ

export_quads : boolean
Change meshes topology to quads instead of triangles. Applicable only for fbx file format as for now.
finalize : boolean

Produce a final avatar mesh:

  • invisible avatar body mesh faces are removed (i.e., specified outfit body_visibility_mask is applied to the mesh) unless apply_visibility_masks is set to false explicitly for the whole avatar or for the particular outfit category
  • avatar haircut renamed to haircut. The generated haircut blendshape will be applied with a factor set to 1, and texture will be blended into the head texture
  • avatar outfit renamed to the corresponding outfit category (i.e., outfit/outfit_upper/outfit_lower)
  • avatar texture parts recoloring applied

See also FAQ

Please note: it is your responsibility to specify only one conflicting avatar part at a time: i.e. only one haircut/outfit/etc.

format : string
File format for the resulting mesh. The top-level flag defines the format of the avatar, category-level flag defines the format of the mesh for this particular category. Currently supported options include gltf, glb, fbx, obj, ply, and bin (blendshapes only)
list : list
List of enumerable values of assets to export for this particular category. Please see the enumerable export parameters retrieval request to retrieve a list of available enumerable export parameters for each particular category for pipeline and pipeline subtype on your account
lod : string
Level of details for exported mesh. Please find more information on mesh properties in the LOD table in the available pipelines section. See also FAQ
make_public : boolean

Make avatar model export available through a direct link without API authentication. Valid only for models with embedded sub-meshes and textures, as only the avatar.zip archive is processed. The public link will be available through the public_file field of avatar export like in the example below:

 {
    "avatar_code": "3135741b-0a6f-45df-a71e-fdca65ee9dcd",
    "code": "cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570",
    "comment": "finalize",
    "created_on": "2024-08-13T12:16:14.499757Z",
    "files": [
        {
            "category": null,
            "file": "https://api.avatarsdk.com/avatars/3135741b-0a6f-45df-a71e-fdca65ee9dcd/exports/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/files/avatar/file/",
            "identity": "avatar",
            "static_files": []
        }
    ],

    /* public url */
    "public_file": "https://metaperson.avatarsdk.com/public/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/avatar.zip",

    "status": "Completed",
    "url": "https://api.avatarsdk.com/avatars/3135741b-0a6f-45df-a71e-fdca65ee9dcd/exports/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/"
}

See also FAQ

make_public_direct : boolean
Make avatar model export available through a direct link without a zip archive. Please note: works only for fbx and glb export formats. Applied if make_public is set to true. See also FAQ
profile : string
Each avatar part (head, body, outfit, etc.) has its own set of textures at the original resolution (SOURCE.png profile). Several more convenient combinations of format and resolutions are added as texture profiles (e.g., 1K.jpg, 2K.jpg, 4K.jpg, etc.). Textures are not upscaled, thus, there will be no 4K file for the 1K source, and the 4K requested profile may contain links to 2K textures. Available texture profiles and their contents for each avatar part may be obtained using the static resources list request. See also FAQ
remove_neck_layers : integer

Remove n lower layers of avatar head neck. Useful when only AvatarHead is exported to integrate with custom body, and it is needed to adjust avatar's neck height. Valid range is 0 - 12. Please note, that lower 8 layers (for LOD1) do not depend on the head (on the submitted photo), they are always the same (i.e. fixed). So if you need to connect the head to the other body and need to get fixed cut contour, you should avoid using cutting more than 8 layers.

There are different values for different lod levels:

  • LOD1: cut range 0 - 12, 8 fixed layers
  • LOD2: cut range 0 - 8, 5 fixed layers

See sample renders for different values below:

remove_neck_layers comparison

See also FAQ

split_vertices : boolean
Add vertices such that each vertice has exactly one UV-map coordinate
transparent_cornea : boolean
Apply transparency to the cornea material. Useful to recolor eyes. Please note: not all mesh formats supports transparent materials. See also FAQ
values : JSON object

Avatar blendshapes deformations factors in the form of

{
  "blendshape_set": {"blendshape_name": value, ...},
  ...
}

Please find available blendshape names and set names in the blendshapes parameters section

3.5.2   Export files

When export parameters are specified, algorithms generate export which consists of one or several export files depending on specified export parameters flags. In order to download all avatar's data, all files within one export have to be downloaded. Export file names are unique within one export and consistent from avatar to avatar export thus you may set priority to download export files in your application: e.g. avatar itself first, then its haircuts, etc.

Please see the avatar exports list request to find out how to list available avatar exports and their export files.

3.5.3   Static export files

Some export files may contain files, that are not modified from export to export: e.g. normals map or default, non-recolored haircut textures. These files are explicitly listed within each export file. They may be downloaded only once and cached on the client side for other export files to save bandwidth and minimize export download size. Please note: they still have to be downloaded separately from the export file for the first time as they are not included in the export file archive.

Please see the avatar exports list request description to find information about static files' retrieval.

3.6   Static resources

While the shape and texture are different for each particular avatar face, there are still a lot of other resources that do not change and may be reused within avatars with minimal or no modification at all: e.g. artificial haircut textures, outfits, etc. If your application generates a lot of avatars, it may be convenient to download these static resources once and reuse them for future avatars saving bandwidth. Furthermore, you can start these resources download in advance, even before the avatar computation is completed, minimizing the time until the avatar is ready to be displayed.

Please see the static resources list request to find more information on how to retrieve available static resources and how to retrieve the resources themselves.

[1](1, 2, 3, 4, 5, 6, 7) Color is represented as a JSON object with red, green, and blue keys and [0, 255] values inclusive for corresponding color channels. E.g. {"red": 222, "green": 173, "blue": 190}

4   Methods

4.1   Players

Player model DTO [*]:

{
  // Absolute URL to this DTO
  "url": string,

  // Player unique identifier (PlayerUID)
  "code": string,

  // ISO 8601 datetime
  "created_on": string,

  // May be used to contain arbitrary information for your taste
  "comment": string
}
[*]DTO is an acronym for Data Transfer Object

4.1.1   List

Method
GET
URL
/players/
Description
Retrieve a paginated list of registered players available for your developer account. Available only in developer access mode. See the pagination section for paginated response details. See the response example below:
[
  {
    "url":"https://api.avatarsdk.com/players/9418fd52-baef-401c-a2b3-e6fe16d93596/",
    "code":"9418fd52-baef-401c-a2b3-e6fe16d93596",
    "created_on":"2017-04-03T04:08:15.589833Z",
    "comment":""
  },
  ...
]
Filters
  • created_before - filter Players with creation datetime before specified one (inclusive)
  • created_after - filter Players with creation datetime after specified one (inclusive)
  • comment - filter by part of the Player comment

4.1.2   Retrieve

Method
GET
URL
/players/{code}/
Description
Retrieve a particular instance of Player identified by code URL part. See player DTO for the response format description. Available in developer and client access modes.

4.1.3   Create

Method
POST
URL
/players/
Description
Register a new Player. See player DTO for the response format description. Available in developer and client access modes.
Request parameters
No request parameters are required.

4.2   Parameters

Parameters DTO:

{
  // Category of parameters. E.g. 'model_info', 'avatar_modifications', etc.
  "category": [
    // List of parameter names
    "name",
    ...
  ],
  ...
}

4.2.1   Retrieve

Method
GET
URL
/parameters/(available | default)/{pipeline}/
Description

Retrieve all available or default parameters for specified pipeline and default pipeline subtype. Use filters to retrieve parameters for the non-default pipeline subtype. The response is one key-value pair with pipeline_subtype as a key and parameters as a value.

Parameters may be just copy-pasted as-is (or partially) into the parameters field of create avatar request parameters. The only exception is the avatar_modifications parameters category: this category contains key-value parameters. See the avatar modification parameters section for details.

Please see the example response below (a little bit shortened for the sake of simplicity):

{
  "female": {
    "model_info": [
      "gender",
      "race",
      "age",
      "hair_color",
      "skin_color",
      "eye_sclera_color",
      "eye_iris_color"
    ],
    "avatar_modifications": [
      "remove_smile",
      "remove_glasses",
      "remove_stubble"
    ]
  }
}
Filters
  • pipeline_subtype - filter by non-default pipeline subtype. See available pipelines for details about available pipeline subtypes

4.3   Enumerable export parameters

Enumerable export parameters DTO:

{
    // export parameters category
    "category": {
      "list": [
        // list of enumerable parameters
        values
      ],
      "textures": [
        // list of textures available for the category
        values
      ]
    }
    ...
}

4.3.1   Retrieve

Method
GET
URL

/export_parameters/available/{pipeline}/

Retrieve all available enumerable export parameters for specified pipeline and a pipeline subtype. Use filters to retrieve parameters for the non-default pipeline subtype. The response is a JSON object of available enumerable values for each export parameters category.

Please see the example response below (a little bit shortened for the sake of simplicity):

{
  "avatar": {
    "list": [
      "AvatarBody",
      "AvatarHead",
      ...
    ],
    "textures": [
      "Color",
      "GltfMetallicRoughness",
      "Normal",
      "Roughness",
      "UnityMetallicSmoothness"
    ]
  },
  "haircuts": {
    "list": [
      "HaircutGenerated",
      "Haircut0",
      ...
    ],
    "textures": [
      "Color",
      "Normal",
      ...
    ]
  }
}
Filters
  • pipeline_subtype - filter by subtype. See available pipelines for details about available pipeline subtypes

4.4   Static resources

Static resources DTO:

{
  // Pipeline subtype. E.g. 'female', 'male', etc.
  "pipeline_subtype": {

    // Asset category. E.g. 'avatar', 'haircuts', etc.
    "category": {

      // Asset name. E.g. 'AvatarHead', 'Haircut1', etc.
      "asset": {

        // Asset LOD. E.g. 'LOD1', 'LOD2', etc.
        "lod": {

          // Asset textures
          "textures": {

            // Texture Profile. E.g., '1K.jpg', '1K.png', etc.
            "texture_profile": {

              // Texture Profile Variant. E.g., 'base', 'stripes', etc. Mostly for outfits
              "profile_variant": {

                // Key: texture name. E.g. 'Color', 'Normal', etc.
                // Value: absolute URL to the corresponding texture file
                "texture_name": URL,
              },
            },
          },
          ...
        },
        ...
      },
      ...
    },
    ...
  },
  ...
}

4.4.1   List

Method
GET
URL
/static_resources/{pipeline}/
Description

Retrieve a JSON object with all available static resources for the specified pipeline. Please find the JSON object format in the static resources DTO section above.

The size of the resulting JSON may be reduced by applying request filters (i.e. retrieve only particular LODs and formats). Please see the filters section below.

To retrieve the resource itself, follow the URL in the corresponding asset section.

Please see the example response below (shortened for the sake of simplicity):

{
  "female": {
    "avatar": {
      "AvatarHead": {
        "LOD1": {
          "textures": {
            "2K.jpg": {
              "base": {
                "Color": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Color_2K.jpg",
                "Normal": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Normal0_2K.jpg",
                "GltfMetallicRoughness": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_GltfMetallicRoughness_2K.jpg",
                "Roughness": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Roughness_2K.jpg"
              }
            }
          }
        },
  ...
}
Filters

Please note: all filters are case-sensitive.

Multiple values may be specified via , (comma) sign, e.g. ?lod=LOD1,LOD2

  • pipeline_subtype - pipeline subtype, e.g. female
  • category - asset category, e.g. avatar
  • asset - asset name, e.g. AvatarHead
  • lod - asset LOD, e.g. LOD1
  • texture_profile - texture Profile, e.g. 2K.jpg

4.5   Avatars

Avatar model DTO:

{
  // Absolute URL to this DTO
  "url": string,

  // Avatar identifier
  "code": string,

  // Avatar models computing status. One of [Uploading, Queued, Computing, Completed, Failed, Timed Out]
  "status": string,

  // Optional more verbose description of status field above. Mostly set
  // for `Failed` status
  "status_verbose": {"code": int, "message": string},

  // Current progress of avatar status. In rage [0:100]
  "progress": integer,

  // Avatar name
  "name": string,

  // Pipeline used to calculate avatar
  "pipeline": string,

  // Avatar description
  "description": string,

  // ISO 8601 datetime
  "created_on": string,

  // ISO 8601 last change datetime. May be `null` if it hasn't changed yet since the creation
  "ctime": string,

  // Absolute URL to retrieve Avatar source image thumbnail
  "thumbnail": string,

  // Absolute URL to retrieve JSON object with this avatar meta-information
  "model_info": string,

  // Absolute URL to retrieve a list of available avatar exports for this avatar model
  "exports": string
}

4.5.1   List

Method
GET
URL
/avatars/
Description
Retrieve a paginated list of available avatar models for your account. Available in developer and client access modes. In the client access mode list of avatars is restricted to models created by specified PlayerUID. See the pagination section for paginated response details. See the response example below:
[
  {
    "url":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/",
    "code":"b63f9737-8594-460a-99a4-74e60b042bd4",
    "status":"Completed",
    "progress":100,
    "name":"Leo",
    "pipeline": "metaperson_2.0",
    "description":"",
    "created_on":"2017-04-03T04:08:15.589833Z",
    "ctime":null,
    "thumbnail":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/thumbnail/"
  },
  ...
]
Filters
  • name - filter by part of the avatar name
  • description - filter by part of the avatar description
  • status - filter by part of the avatar status
  • created_before - filter avatars with creation datetime before specified one (inclusive)
  • created_after - filter avatars with creation datetime after specified one (inclusive)
  • changed_before - filter avatars with change datetime before specified one (inclusive)
  • changed_after - filter avatars with change datetime after specified one (inclusive)
  • pipeline - filter by used pipeline

4.5.2   Retrieve

Method
GET
URL
/avatars/{code}/
Description
Retrieve a particular instance of avatar identified by the code URL part. See avatar DTO for the response format description. Available in developer and client access modes.

4.5.3   Create

Method
POST
URL
/avatars/
Description

Create a new avatar calculation task. Available in developer and client access modes. After POSTing a request, the avatar photo for the calculation is uploaded to the calculation backend (state Uploading), then Queued until a free calculation backend is found, then Computing, and finally Completed.

In some cases, the calculation task may be Failed due to a bad (blurry/dark/etc.) photo being submitted or for some other reasons. In rare cases task may be Timed out - calculation took too long time.

It is your responsibility to poll the avatar calculation task for progress (status and progress fields of avatar DTO). Access to the URL fields of the incomplete avatar will not succeed.

Request parameters

Accepts multipart/form-data requests with the following fields:

  • name - new avatar name

  • description - new avatar description

  • photo - new avatar source photo. Either a photo or a selfie must be provided. Error is returned if none or both are provided

  • selfie - selfie code. Please see the selfies section to learn more about selfies. Either a selfie or a photo must be provided. Error is returned if none or both are provided. Error is returned if the selfie file has not uploaded yet by the end-user

  • pipeline - an optional field to specify which pipeline to use for new avatar generation. Please see the the available pipelines for the list of possible field values. The assumed value is animated_face if the form field is not provided

  • pipeline_subtype - modification of pipeline. Please see available pipelines for the list of possible field values

  • parameters - specific parameters to compute for the submitted avatar. See parameters DTO for this field format. If no value is submitted - it is replaced with default parameters for the specified pipeline and (optionally) pipeline subtype. See the parameters retrieval request to find out default/available parameters for pipeline type/subtype pairs. If no parameters are required to compute the avatar - submit an empty JSON object: {}

  • export_parameters - parameters to specify what resulting avatar downloadable data should include: like model format, set of textures, blendshapes, whether to embed all these assets into the one model or save as separate files, etc. Please see the export parameters section to find out more.

    Please note: if this section is empty - no avatar exports will be created.

  • export_comment - avatar export comment. An arbitrary string, note to self, etc.

4.5.4   Update

Method
PATCH, PUT
URL
/avatars/{code}/
Description
Update the name/description of the particular avatar model identified by the code URL part. The PATCH method supports partial update (e.g. only one field may be submitted), PUT method requires both fields to be submitted. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID.
Request parameters

Accepts multipart/form-data requests with the following fields:

  • name - new avatar name
  • description - new avatar description

4.5.5   Delete

Method
DELETE
URL
/avatars/{code}/
Description
Delete the particular avatar model identified by the code URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID.

4.6   Avatars count

4.6.1   Retrieve

Method
GET
URL
/avatars/count/
Description

Retrieve the number of avatars created (created field), the number of free avatars left (i.e. included in your billing plan, prepaid field), and the number of avatars to be paid (to_pay field) in the current billing period.

The time frame to count avatars may be specified with since and until filters. In this case, only the number of created avatars is returned.

Please see the example response below:

{
  "created": 8192,
  "prepaid": 0,
  "to_pay": 2192
}
Filters
  • since - count avatars created after the specified date (inclusive), iso8601 format
  • until - count avatars created before the specified date (exclusive), iso8601 format

4.7   Avatar thumbnail

4.7.1   Retrieve

Method
GET
URL
/avatars/{code}/thumbnail/
Description
Retrieve the thumbnail of the submitted for calculations avatar photo.
Request Parameters
  • max_w - limit thumbnail width, in range (0, 1024]
  • max_h - limit thumbnail height, in range (0, 1024]

4.8   Avatar model information

4.8.1   Retrieve

Method
GET
URL
/avatars/{code}/model_info/
Description

Retrieve JSON object with avatar model meta-information. There are several items that are provided by default (i.e. without explicit request), as well as some items that should be requested explicitly. Please see model info parameters section for details.

Please see the example response below:

{
    "age": "not_child",
    "age_confidence": 1,
    "eye_iris_color": {
        "blue": 86,
        "green": 86,
        "red": 91
    },
    "eyebrows_color": {
        "blue": 56,
        "green": 72,
        "red": 114
    },
    "gender": "female",
    "gender_confidence": 1,
    "hair_color": {
        "blue": 50,
        "green": 73,
        "red": 108
    },
    "lips_color": {
        "blue": 111,
        "green": 120,
        "red": 200
    },
    "pipeline": "metaperson_2.0",
    "pipeline_subtype": "female",
    "race": "white",
    "race_confidence": 1,
    "races": {
        "asian": 5.285300192295339e-13,
        "black": 4.953061250034807e-08,
        "white": 1
    },
    "remove_smile": false,
    "skin_color": {
        "blue": 132,
        "green": 158,
        "red": 211
    }
}

4.9   Selfies

For some applications, it may be the case, that the camera or selfie photo is not available within the same device (e.g. an application on a desktop computer without an attached web camera). At the same time, almost everyone has cameras or selfies on his/her mobile phone, but it may be inconvenient to transfer these photos to the device with the application.

The solution is to create a selfie upload page, visit it within the mobile device, and upload a new or existing selfie photo. For end-user convenience, the QR code with the upload page URL is also available. After uploading the photo, the application could download the photo and continue its workflow of avatar creation. It is also possible to avoid the photo download step by passing the selfie code into the avatar creation request directly.

Please note: only one photo can be uploaded per selfie upload page. To upload a new photo, a new selfie upload page must be created.

Selfie model DTO:

{
  // Selfie code
  "code": string,

  // ISO 8601 datetime after which, the selfie will be unavailable (24 hours currently)
  "expires": string,

  // Absolute URL to selfie file
  "file_url": string,

  // Absolute URL to QR code file with selfie upload page URL
  "upload_page_qr": string,

  // Absolute URL to selfie upload page
  "upload_page_url": string,

  // Flag indicates whether the upload page visited
  "upload_page_visited": boolean,

  // Absolute URL to this DTO
  "url": string
}

4.9.1   Create

Method
POST
URL
/selfies/
Description
Create a new selfie upload page. Please see the selfie DTO for the response format.

4.9.2   Retrieve QR code

Method
GET
URL
/selfies/{code}/qr/
Description
Retrieve the QR code with the upload page URL as a PNG image file.

4.9.3   Retrieve

Method
GET, HEAD
URL
/selfies/{code}/file/
Description
Retrieve end-user photo. If the end-user has not uploaded the file yet, the request will end with HTTP 204 NO CONTENT. It is convenient to check file status with a HEAD request first and download it with a GET request once the HTTP 200 response code is returned.

4.10   Avatar exports

Avatar export DTO:

{
  // Avatar identifier
  "avatar_code": string,

  // Avatar export identifier
  "code": string,

  // Avatar export comment, may be `null` if not present
  "comment": string,

  // ISO 8601 datetime
  "created_on": string,

  // List of Avatar Export files
  "files": [

    // Avatar Export file
    {
      // Category of Avatar Export file
      "category": string,

      // Absolute URL to retrieve the Avatar Export file zip archive
      "file": string,

      // Avatar Export file identifier
      "identity": string,

      // List of Static files for Avatar Export file
      "static_files": [

        // absolute URL to retrieve Static file
        string
      ]
    },

    ...
  ],

  // Status of Avatar Export. One of [Queued, Computing, Completed, Failed]
  "status": string,

  // Absolute URL to this DTO
  "url": string
}

4.10.1   List

Method
GET
URL
/avatars/{code}/exports/
Description
Retrieve a list of all available Avatar exports for a particular Avatar. The code key identifies the particular Avatar export. Please see the example response below:
[
    {
        "avatar_code": "e56d6044-fdbf-4cbf-86df-793bf21494f4",
        "code": "c0fc0ece-e291-4bbe-bdf2-ece270e0e065",
        "created_on": "2020-11-16T12:57:03.641470Z",
        "files": [
            {
                "category": null,
                "file": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/avatar/file/",
                "identity": "avatar",
                "static_files": []
            },
            {
                "category": "blendshapes",
                "file": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/mobile_51/file/",
                "identity": "mobile_51",
                "static_files": []
            },
            {
                "category": "haircuts",
                "file": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/Haircut0/file/",
                "identity": "Haircur0",
                "static_files": [
                    "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/Haircur0/static_files/texture.png"
                ]
            }
        ],
        "status": "Completed",
        "url": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/"
    }
]

4.10.2   Retrieve

Method
GET
URL
/avatars/{code}/exports/{export_code}/files/{export_file}/file/
Description

Retrieve a particular Avatar export file. Avatar is identified by the code URL part, Avatar export is identified by the export_code URL part, and the export file is identified by the export_file URL part. Please see the avatar export DTO to see where to find each URL part.

Please note: all export files and their static files must be downloaded to retrieve full Avatar export.

4.10.3   Create

Method
POST
URL
/avatars/{code}/exports/
Description

Create a subsequent avatar export on already Completed avatar. Please see the avatar export DTO section for the response format. May be useful to create finalized avatar export with different list of assets (see the finalize export flag).

After POSTing a request, the avatar export task is created and being transitioned through the following states: Queued, Computing, Completed, Failed. It is your responsibility to poll the avatar export task for the progress.

Request parameters

Accepts multipart/form-data requests with the following fields:

  • parameters - avatar export parameters. Please see the export parameters section for the format description
  • comment - avatar export comment. An arbitrary string, note to self, etc.