1.6.1   Haircuts

animated_face pipeline produced bald avatars (i.e. just head, without any haircut). We have two sets of artificial haircuts (availability depends on pricing plan) which should be modified to match particular avatar head geometry:

• base set: 3 male and 3 female haircuts
• facegen set: 39 haircuts in total, some of them are unisex

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

Parameters availability

1.6.2   Blendshapes

Avatar SDK supports animated avatars using blendshapes. There are three different blendshapes sets available which should be used depending on your use-case: general animation or lip-sync. Please consult blendshapes set description for more information. Please note that legacy blendshapes set is not recommended to use in the new application as it will be deprecated eventually.

legacy_45

The basic set of 45 facial blendshapes.

visems_17

Set of 15 visemes (aa, ch, ee, ih, oh, ou, th, dd, ff, kk, nn, pp, rr, sil, ss) and two additional blendshapes: frown and smile. This set is compatible with Oculus Lipsync that required these 15 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 visems for lipsync here: https://docs.avatarsdk.com/unity-plugin/1.7.0/lipsync_samples.html

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

Parameters availability

1.6.3   Model Info

Avatar SDK is capable to provide some meta-information about computed avatar from source photo like haircut, skin, eyes color, etc. Please find the list of available meta-information parameters below:

hair_color

Compute average haircut color [1] from a submitted photo.

predict_haircut

Predict which haircut from the base and the facegen sets matches best to the submitted photo. haircut_name will contain corresponding haircut identifier. May contain special value absolutely_bald which represents the absence of haircut. Please note: predicted haircut is independent on which haircuts were requested to compute with a particular avatar.

skin_color

Compute average skin color [1] from a submitted photo

gender

Predict 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 value in the range [0.5, 1] inclusive

age

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 value in the range [0.5, 1] inclusive

facial_landmarks_68

Compute facial landmarks. Landmark coordinates are represented as flat JSON Array with X, Y, Z float components sequence for each landmark, or NaN (for each component) if no landmark detected

eye_sclera_color

Compute average eye sclera color [1] from a submitted photo

eye_iris_color

Compute average eye iris color [1] from a submitted photo

lips_color

Compute average lips color [1] from a submitted photo

Colors correspondence

Parameters availability

1.6.4   Avatar Modifications

Avatar SDK is aimed to produce recognizable photo-realistic avatars. However, there is demand on avatars modifications, leaving avatar recognizable, though. Please find available avatar modifications below.

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

allow_modify_neck : boolean

By default, all avatars have the same neck mesh across all models. If flag set to true, neck mesh will be modified to better match submitted photo

curved_bottom : boolean

Make the bottom of model bust slightly curved. See models comparison below

Models comparison

slightly_cartoonish_texture : boolean

Make the model texture look slightly cartoonish. Please note: replaces original avatar texture. See models comparison below

Models comparison

parametric_eyes_texture : boolean

Replace eye texture from submitted photo to generated one with sclera and iris colors match the photo version. Please note: always set for the indie/legacy_styled subtype of the animated_face pipeline. See models comparison below

Models comparison

add_glare : boolean

Add a glare directly into parametric eye texture. Works only when parametric_eyes_texture is set. Enabled by default. See textures comparison below

Textures comparison

add_eyelid_shadow : boolean

Add an eyelid shadow on top of eye texture. Works only when parametric_eyes_texture is set. See textures comparison below

Textures comparison

eye_iris_color : color [1]

Recolor eye iris directly on a model texture. Works only when parametric_eyes_texture is set. See textures comparison below for {"red": 0, "green": 255, "blue": 0} color

Textures comparison

eye_sclera_color : color [1]

Recolor eye sclera directly on a model texture. Works only when parametric_eyes_texture is set. See textures comparison below for {"red": 0, "green": 255, "blue": 0} color

Textures comparison

caricature_amount : float

Factor to strengthen differences between average model and a particular avatar. Valid values range is [0, +∞). Usable values range is model dependent and usually should be lower than 5.

Models comparison

lips_color : color [1]

Recolor lips directly on a model texture. See textures comparison below for {"red": 0, "green": 255, "blue": 0} color

Textures comparison

Parameters availability

1.6.5   Shape Modifications

Similar to avatar modification parameters, see description for that parameters category.

cartoonish_v0.3 : float

Factor to modify avatar mesh to look more cartoon-like. Valid values range is [0, +∞). Usable values range is model dependent and usually should be lower than 1.

Models comparison

Parameters availability

1.6.6   Additional Textures

You could request to compute additional textures along with default one, which is always computed. See avatar textures to find out how to retrieve additional textures.

slightly_cartoonish_texture

Slightly smoother than the original texture.

Textures comparison

cartoonish_texture

Uniformly colored texture.

Textures comparison

smooth_eyelashes_texture

Original texture with smoothen area of eyelashes.

Textures comparison

lips_mask

Mask in PNG format.

Textures comparison

Parameters availability

3.1.1   list

Method

GET

URL

/players/

Description

Retrieve paginated list of registered players available for your developer account. Available in developer access mode only. See pagination section for paginated responses details. See 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

3.1.2   retrieve

Method

GET

URL

/players/{code}/

Description

Retrieve particular instance of Player identified by code URL part. See player DTO for response format description. Available in developer and client access modes.

3.1.3   create

Method

POST

URL

/players/

Description

Register new Player. See player DTO for response format description. Available in developer and client access modes.

Request parameters

No request parameters are required.

3.2.1   list

Method

GET

URL

/avatars/

Description

Retrieve paginated list of available Avatar models for your account. Available in developer and client access modes. In client access mode list of avatars is restricted to models created by specified PlayerUID. See pagination section for paginated responses details. See 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": "static",
    "description":"",
    "created_on":"2017-04-03T04:08:15.589833Z",
    "ctime":null,
    "mesh":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/mesh/",
    "texture":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/texture/",
    "thumbnail":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/thumbnail/",
    "haircuts":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/",
    "blendshapes":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/blendshapes/"
  },
  ...
]

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

3.2.2   retrieve

Method

GET

URL

/avatars/{code}/

Description

Retrieve particular instance of Avatar identified by code URL part. See avatar DTO for response format description. Available in developer and client access modes.

3.2.3   create

Method

POST

URL

/avatars/

Description

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

In some cases calculation task may be Failed due to bad (blurry/dark/etc.) photo was 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 Avatar calculation task for progress (status and progress fields of avatar DTO). Access to the URL fields of 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
• preserve_original_texture - boolean flag, indicates whether to preserve original texture size, or not. By default texture is padded with black fields so that its size is multiple of power-of-two (for compatibility reasons). If you do not need this - set this flag to True. Affects only static pipeline
• pipeline - optional field to specify which pipeline to use for new Avatar generation. Assumed value is static if form field is not provided. Available choices are:
  • static - static bald head with separate haircuts
  • animated_face - static bald head with set of blendshapes for animations and separate haircuts
  • head_1.0 - predicted head, haircut and bust
  • head_1.1 - predicted head, haircut and bust. Improved texture and mesh quality
  • head_1.2 - predicted head, haircut and bust. Even more improved texture and mesh quality than in head_1.1
• pipeline_subtype - modification of pipeline. Publicly available variants are:
  • for static pipeline:
    • base/legacy - static bald head with separate haircuts. Default if no subtype specified
  • for animated_face pipeline:
    • base/legacy - static bald head with set of blendshapes (45 facial, 17 visemes) for animations and separate haircuts. Default if no subtype specified
  • for head_1.0, head_1.1 and head_1.2 pipelines:
    • base/static - static predicted head, haircut and bust. Default if no subtype specified
    • base/legacy - predicted head, haircut and bust with set of blendshapes (45 facial, 17 visemes) for animations
    • base/mobile - predicted head, haircut and bust with set of blendshapes (51 facial) for animations
• paramerters - specific parameters to compute for submitted avatar. See parameters DTO for this field format. If no value submitted - replaced with default parameters for specified pipeline and (optionally) pipeline subtype. See parameters retrieval request to find out default/available parameters for pipeline type/subtype pairs. If no parameters required to compute avatar - submit empty JSON object: {}

3.2.4   update

Method

PATCH, PUT

URL

/avatars/{code}/

Description

Update name/description of the particular Avatar model identified by the code URL part. 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

3.2.5   delete

Method

DELETE

URL

/avatars/{code}/

Description

Delete particular Avatar model identified by code URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID.

3.3.1   list

Method

GET

URL

/avatars/{code}/haircuts/

Description

Retrieve list of per-avatar haircuts. Particular Avatar is identified by code URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID. Please see avatar haircut DTO for response format description. Please see example response below:

[
  {
    "identity":"female_NewSea_J086f",
    "gender":"female",
    "preview":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/preview/",
    "url":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/",
    "texture":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/texture/",
    "model":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/",
    "pointcloud":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/pointcloud/",
    "mesh":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/mesh/"
  },
  ...
]

Filters

• gender - filter by haircut gender

3.3.2   retrieve

Method

GET

URL

/avatars/{code}/haircuts/{identity}/

Description

Retrieve particular instance of per-avatar haircut. Avatar is identified by code URL part, haircut - by identity URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID. Please see avatar haircut DTO for response object description.

3.4.1   retrieve

Method

GET

URL

/avatars/{code}/mesh/

Description

Retrieve zip archive with Avatar mesh.

Avatars computed with animated_face, head_1.0, head_1.1 and head_1.2 pipelines support 8 different level of mesh details (LOD) varying from 42k polygons (LOD=0) down to just 5k (LOD=7). Specify desired LOD on mesh retrieval as a request parameter.

Request Parameters

• lod - level of details, integer in range [0, 7]

3.5.1   list

Method

GET

URL

/avatars/{code}/textures/

Description

Additional textures (along with default one) may be requested to compute for particular avatar. See additional textures parameters to find out which textures may be requested.

Use this request to retrieve list of available textures for particular avatar. Particular Avatar is identified by code URL part.

Please see example response below:

[
    {
        "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/slightly_cartoonish_texture/file/",
        "identity": "slightly_cartoonish_texture"
    },
    {
        "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/model_cartoonish/file/",
        "identity": "model_cartoonish"
    },
    {
        "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/model/file/",
        "identity": "model"
    }
]

3.5.2   retrieve

Method

GET

URL

/avatars/{code}/textures/{identity}/file/

Description

Retrieve particular texture file identified by its identity for particular avatar identified by code. Texture format may vary (i.e. JPEG, PNG, etc.), thus consult Content-Type HTTP Response Header for particular texture format.

3.6.1   retrieve

Method

GET

URL

/avatars/{code}/blendshapes/

Description

Retrieve zip archive with all available blendshapes for specific Avatar. If no blendhapes available - request will end with HTTP 204 NO CONTENT response.

By default blendshapes are delivered in ply files packed into zip archive. Blendshapes format may be changed to one fbx file also packed into zip archive.

Avatars computed with animated_face, head_1.0, head_1.1 and head_1.2 pipelines support 8 different level of blendshapes details (LOD) varying from 42k polygons (LOD=0) down to just 5k (LOD=7). Specify desired LOD on blendshapes retrieval as a request parameter.

Request Parameters

• fmt - blendshapes format. Available choices are: ply and fbx
• lod - level of details, integer in range [0, 7]

3.7.1   retrieve

Method

GET

URL

/avatars/{code}/thumbnail/

Description

Retrieve thumbnail of 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]

3.8.1   retrieve

Method

GET

URL

/parameters/(available | default)/{pipeline}/

Description

Retrieve all available or default parameters for specified pipeline and default pipeline sub-type. Use filters to retrieve parameters for non-default pipeline sub-type. Response is an one key-value pair with pipeline_subtype as a key and parameters as a value.

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

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

{
  "base/legacy": {
    "blendshapes": {
      "base": [
        "legacy_45",
        "visemes_17"
      ]
    },
    "haircuts": {
      "base": [
        "female_NewSea_J086f",
        "female_NewSea_J096f",
        "female_NewSea_J123f",
        "male_NewSea_J003m",
        "male_NewSea_J082m",
        "male_makehuman_short02"
      ],
      "facegen": [
        "facegen_afro",
        "facegen_balding",
        ...
        "facegen_wavy_shag"
      ]
    }
  }
}

Filters

• pipeline_subtype - filter by non-default pipeline sub-type. See create avatar request parameters for details about available pipeline sub-types.