3.1.1   animated_face

deprecated

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

Available subtypes:

• base/legacy - static bald head with a set of blendshapes (45 facial, 17 visemes) for animations and separate haircuts. Default if no subtype is specified
• indie/legacy_styled subtype have different model topology to make available optional mesh modifications (see computation parameters section below)

Model sample

Available LODs:

Note: The structure of the head in LOD8 is the same as in LOD7 but without teeth.

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).

Available subtypes:

• base/static - static predicted head, haircut, and bust
• base/legacy - predicted head, haircut, and bust with a set of blendshapes (45 facial, 17 visemes) for animations
• base/mobile - predicted head, haircut, and bust with a set of blendshapes (51 facial) for animations

Model samples

Available LODs:

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).

Please note: available on the Pro subscription plan only.

Available subtypes:

• bust/mobile - predicted bust with a detachable haircut and set of 51 facial blendshapes
• bust/static - static predicted bust and haircut
• head/mobile - predicted head with a detachable haircut and set of 51 facial blendshapes. The mesh topology of a head is always the same

Model samples

Rotated person samples

Available LODs:

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).

Please note: available on the Pro subscription plan only.

Please note: this pipeline utilizes export parameters

Available subtypes:

• mobile (FitPerson) - full body model based on the SMPL model that is created by the Max-Planck Institute with a set of 51 facial blendshapes and 15 visemes. Have an additional head export template, which is effectively head/mobile subtype of head_2.0 pipeline.
• female, male (MetaPerson) - a set of bodies created by 3D artists with a head automatically generated from selfies. The animation rig for the bodies is compatible with Adobe's Mixamo, which makes them compatible with a large existing set of animations. Fixed body shape allows 3D artists to apply custom-designed outfits easier than before. The head is based on the head_2.0 pipeline.

Model samples

Available LODs:

• FitPerson

  	default template		head template
  LOD#	vertices	faces	vertices	faces
  0	18689	34578	12367	23404
  1	15633	28102	10374	19054
  2	13850	24880	9116	16860
  3	9285	16173	6059	11007
  4	8096	13905	5287	9497
  5	6987	11565	4587	7889
  6	6271	10151	4106	6937
  7	4267	7140	2102	3926

• MetaPerson

  	female/male subtype
  LOD#	vertices	faces
  0	19538	36196
  1	15633	28102
  2	13854	24880
  3	9291	16173
  4	8102	13905
  5	6993	11565
  6	6277	10151
  7	4273	7140

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.3.1   Haircuts

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

base set

3 male and 3 female haircuts

Haircuts samples

facegen set

39 haircuts in total, some of them are unisex

Haircuts samples

metaperson set

A set of haircuts for metaperson_2.0 pipeline

Haircuts samples

plus set

50 haircuts in total, some of them are unisex

Haircuts samples

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: for the metaperson_2.0 pipeline, 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.

Availability of these sets depends on your current pricing plan.

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

3.3.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.

base set

Set of business, business casual, and casual outfits

Outfits samples

base_lowpoly set

The same set as the base but with a lowered polygon count. Outfit name ends with _lowpoly suffix (e.g. outfit_0_lowpoly). Please see the outfit mesh polygons comparison table below for more details about 3D mesh.

meta set

The same set as the base but adapted and available only for MetaPerson avatars. Outfit name contains _meta_ suffix (e.g. outfit_meta_0). Please see the outfit mesh polygons comparison table below for more details about 3D mesh.

meta_lowpoly set

The same set as the meta but with a lowered polygon count. Outfit name ends with _lowpoly suffix (e.g. outfit_meta_0_lowpoly). Please see the outfit mesh polygons comparison table below for more details about 3D mesh.

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

Available outfits 3D mesh details for base sets:

Available outfits 3D mesh details for meta sets:

Please see the parameters retrieval request (or enumerable export parameters retrieval request for body_0.3 and metaperson_2.0 pipelines) to retrieve a list of available outfits.

3.3.3   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

3.3.4   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.

body_shape

Set of 8 pairs of blendshapes to modify body shape

blendshapes names

Chest-, Chest+, Forearms-, Forearms+, General-, General+, Hips-, Hips+, Legs-, Legs+, Neck-, Neck+, Shoulders-, Shoulders+, Waist-, Waist+,

emotions

Facial emotions blendshapes (smile)

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, 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, Head_Height_Dn, Head_Thin, Head_Vol_Dn, Head_Width_Dn, JawLine_Narrow, Jaw_Narrow, 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

face_modifications_2

Set of 2 blendshapes (face_shape and jaw_shape) to modify the facial shape. Please see the renders below:

face_modifications_2 samples

legacy_45

deprecated

The basic set of 45 facial blendshapes

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/

visemes_17

Set of 15 visemes (AA, CH, EE, IH, OH, OU, TH, dd, ff, kk, nn, pp, rr, sil) and two additional blendshapes: frown and smile. This set is compatible with Oculus Lipsync which requires 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 visemes for lipsync here: https://docs.avatarsdk.com/unity-plugin/3.0.1/additional_samples.html

3.3.5   Model info

Avatar SDK is capable of providing some meta-information about computed avatars from source photos like a haircut, skin, eye color, etc. Please find the list of available meta-information parameters below:

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

body_shape_coeffs_10

As FitPerson avatars are based on the SMPL model that is created by the Max-Planck Institute, SMPL model coefficients applied to the resulting avatar may be included in model info.

Please note: to use these coefficients you will need an active SMPL license. Please find more information on the Meshcapade site.

eye_iris_color

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

eye_sclera_color

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

facial_landmarks_68

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

Please note: for base/legacy and indie/legacy_styled subtypes of animated_face pipeline, landmarks in the range [0-7] and [9-16] are not present (i.e. they are set to NaN).

Landmarks correspondence

(click on image to magnify)

gender

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

hair_color

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

lips_color

Compute average lip color [1] from a submitted photo

predict_haircut

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

The head_2.0 additionally estimates haircut correspondence and puts weights under the haircut_full_info key. Please see the sample model info below:

{
   "haircut_full_info" : {
      "absolutely_bald" : 2.936517375928815e-06,
      "afro_short" : 0.0112605718895793,
      "balding" : 0.002860783133655787,
      "bob" : 0.02034652791917324,
      "bob_parted" : 0.03573336824774742,
      "burr_cut" : 0.009195085614919662,
      "classic_side_part" : 0.0149933909997344,
      "classic_tapper" : 0.009302150458097458,
      "cowlick" : 0.005376111250370741,
      "cowlick2" : 0.012983413413167,
      "crew_cut" : 0.01081948075443506,
      "crew_cut2" : 0.01268314570188522,
      "crew_cut3" : 0.01463177613914013,
      "curtained_hair" : 0.03242894262075424,
      "flattop" : 0.01193561963737011,
      "high_volume_brushed_up" : 0.01360709313303232,
      "long_afro" : 0.02262603491544724,
      "long_bob" : 0.04952326044440269,
      "long_crimped" : 0.05819306150078773,
      "long_disheveled" : 0.06030699983239174,
      "long_hair" : 0.06073638796806335,
      "long_hair2" : 0.075968898832798,
      "long_wavy" : 0.06359551101922989,
      "mid_length_ruffled" : 0.02399636991322041,
      "mid_length_straight" : 0.04574619233608246,
      "mid_length_wispy" : 0.03018877282738686,
      "ponytail_with_bangs" : 0.03226388990879059,
      "short_bob_asymmetrical_bangs" : 0.02550809271633625,
      "short_curls2" : 0.02223772928118706,
      "short_disheveled" : 0.01950234733521938,
      "short_simple" : 0.01544607523828745,
      "side_french_braid" : 0.04054473340511322,
      "straight_bob_bangs" : 0.03596006706357002,
      "very_long" : 0.06915491819381714,
      "wavy_shag" : 0.02055038698017597
   },
   "haircut_name" : "long_hair2",
   "pipeline" : "head_2.0",
   "pipeline_subtype" : "bust/mobile",
   "race" : "white",
   "race_confidence" : 0.9999996423721313,
   "races" : {
      "asian" : 2.615514413124159e-13,
      "black" : 4.136433915391535e-07,
      "white" : 0.9999996423721313
   }
}

race

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:

{
   "pipeline" : "head_2.0",
   "pipeline_subtype" : "bust/mobile",
   "race" : "white",
   "race_confidence" : 0.9999996423721313,
   "races" : {
      "asian" : 2.615514413124159e-13,
      "black" : 4.136433915391535e-07,
      "white" : 0.9999996423721313
   }
}

skin_color

Compute average skin color [1] from a submitted photo

Colors correspondence

3.3.6   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.

add_eyelid_shadow : boolean

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

Models comparison

add_glare : boolean

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

Models comparison

allow_modify_neck : boolean

By default, all avatars have the same neck mesh across all models. If the flag is set to true, the neck mesh will be modified to better match the submitted photo. Please note: x-axis rotation is also applied to match a head pose from the submitted photo

Models comparison

caricature_amount : float

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

Models comparison

curved_bottom : boolean

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

Models comparison

enhance_lighting : boolean

Attempt to make lighting more uniform. See the models comparison below

Models comparison

eye_iris_color : color [1]

Recolor the 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

Models 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

Models comparison

generated_haircut_faces_count : integer

Resample generated haircut mesh to have specified face count. See the models comparison below for default and 256 faces count haircut (rendered without texture)

Models comparison

generated_haircut_texture_size : size [2]

Resize the generated haircut texture to the specified size. The original haircut texture size is 1024x1024 px, thus setting a size greater than this value will not result in improved texture quality.

hair_color : color [1]

Recolor the generated haircut directly on a haircut texture. See models comparison below for {"red": 0, "green": 255, "blue": 0} color

Models comparison

lips_color : color [1]

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

Models comparison

parametric_eyes_texture : boolean

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

Models comparison

parametric_eyes_texture_v2 : boolean

Replace the eye texture from the submitted photo with generated one with sclera and iris colors to match the photo version. See the models comparison below.

Please note: add_glare and add_eyelid_shadow flags are ignored when this flag is set to true.

Please note: If both parametric_eyes_texture and parametric_eyes_texture_v2 are set to true, then parametric_eyes_texture_v2 is ignored.

Models comparison

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.

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

repack_texture : boolean

Optimize texture layout to occupy less space. See the textures comparison below

Textures comparison

slightly_cartoonish_texture : boolean

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

Models comparison

teeth_color : color [1]

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

Models comparison

texture_size : size [2]

Resize model texture to the specified size. The original texture size is 2048x2048 px, thus setting a size greater than this value will not result in improved texture quality.

3.3.7   Shape modifications

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

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

cartoonish_v0.3 : float

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

Models comparison

cartoonish_v1.0 : float

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

Models comparison

3.3.8   Body shape

Avatar SDK algorithms predict full body shape by analyzing an input photo and producing an average body for detected parameters. You can optionally specify additional parameters, such as gender, weight, height, etc. Parameters that were not specified will be predicted from an input photo. However, it is recommended to specify as many parameters as possible in order to get a specific body shape.

Please note: the output model may not necessarily have exactly the same measurements as provided by the avatar request. The output measurements are expected to be close to the input body shape parameters that are within the intervals specified by the tables below. Values outside of these intervals may result in significantly different output measurements. We are working to expand these intervals, specifically the one corresponding to the height parameter.

For body_0.3 pipeline (FitPerson only):

Parameter name	Gender
	female	male	non_binary
height	[150; 174]	[160; 187]	[150; 187]
weight	[54; 86]	[70; 112]	[54; 112]
chest	[90; 115]	[96; 125]	[90; 125]
waist	[73; 98]	[81; 118]	[73; 118]
hips	[90; 116]	[93; 119]	[90; 119]

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

gender : string

Expected model's gender. Available values are female, male, and non_binary. If not specified, gender is autodetected. It is highly recommended to specify this parameter to avoid incorrectly autodetected values.

height : float

Expected model's height is in centimeters, is greater than zero. If not specified, height is predicted. It is highly recommended to specify this parameter to avoid incorrectly autodetected values.

weight : float

Expected model's weight in kilograms, greater than zero. If not specified, weight is predicted. It is highly recommended to specify this parameter to avoid incorrectly autodetected value.

chest : float

Expected model's chest girth is in centimeters, greater than zero. If not specified, chest girth is predicted.

waist : float

Expected model's waist girth is in centimeters, greater than zero. If not specified, waist girth is predicted.

hips : float

Expected model's hip girth in centimeters, greater than zero. If not specified, hip girth is predicted.

3.3.9   Additional textures

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

cartoonish_texture

Uniformly colored texture

Textures comparison

lips_mask

Mask in PNG format

Textures comparison

metallic_map

Metalness map in JPG format

Textures comparison

roughness_map

Roughness map in JPG format

Textures comparison

slightly_cartoonish_texture

Slightly smoother than the original texture

Textures comparison

smooth_eyelashes_texture

Original texture with a smoothed area of eyelashes

Textures comparison

3.4.1   Available flags

additional_textures : list

List of textures to export besides the default diffuse model texture. Available values are:

• for head_1.2 and head_2.0 pipelines: roughness_map, metallic_map, lips_mask
• for body_0.3 pipeline: normal_map, roughness_map, metallic_map

For the outfits section body_visibility_mask is also available (see outfits section for visibility mask information).

color : color [1]

If texture supports recoloring, this flag specifies the base color for the recoloring process

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

embed_textures : boolean

If the format supports texture embedding (i.e. fbx or glb), this flag indicates whether to embed textures or store them as separate files. If avatar format does not support texture embedding - the flag is set to false and textures are saved as separate files

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 mesh faces are removed (i.e. specified outfit body_visibility_mask is applied to the mesh)
• 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 etc.)
• avatar texture parts recoloring applied
• blendshape deformations factors are applied (see values flag of blendshapes category)

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 : integer (head_1.2, head_2.0, body_0.3), string (metaperson_2.0)

Level of details for exported mesh. Please find more information on mesh properties in the LOD table for each particular pipeline description in the available pipelines section.

pointclouds : boolean

If set to true, then the resulting model file will not contain mesh faces and UV mapping (i.e. it will contain only mesh vertices).

For meshes with regular topology (i.e. models where a number of vertices, edges, and how these vertices connected are the same, only vertices positions are different), it may be convenient to download full mesh only once and then download and replace only pointclouds (only vertices) for all future models to reduce the download data size

profile : string

Each avatar part (head, body, outfit, etc.) has its own set of textures at the original resolution (SOURCE.png profile). A number of 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 the 4K 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

split_vertices : boolean

Add vertices such that each vertice has exactly one UV-map coordinate

template : string

Apply particular avatar export template. Currently, only one additional template is supported: the head for body_0.3 pipeline, which is effectively the head/mobile subtype of the head_2.0 pipeline.

texture_size : size [2]

Resize texture to the specified size. The avatar texture size is 4096x2048 px. Most asset textures are 4096x4096 px for outfits and 2048x2048 px for haircuts, but size varies between assets. Please check the original texture size before setting a custom value as setting it greater than the original one will not result in improved texture quality.

Please note: if texture size is also set in avatar modification parameters - then texture is resized according to avatar modifications first, and then according to export parameters.

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.4.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.4.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.

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.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):

{
  "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 subtype. See available pipelines for details about available pipeline subtypes

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 for head_1.2, head_2.0, and body_0.3 pipelines (a little bit shortened for the sake of simplicity):

{
    "blendshapes": [
        "mobile_51",
        "visemes_15"
    ],
    "haircuts": [
        "generated",
        ...
        "wavy_bob"
    ]
}

Please see the example response below for the metaperson_2.0 pipeline (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.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.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": "animated_face",
    "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

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 for head_1.2 and head_2.0 pipelines - no avatar exports will be created.

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.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.1   List

Method

GET

URL

/avatars/{code}/haircuts/

Description

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

Please note: you should not use this method to retrieve a list of avatar haircuts for avatars created with export parameters: avatar exports list request should be used instead.

Please see the 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

4.7.2   Retrieve

Method

GET

URL

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

Description

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

Please note: you should not use this method to retrieve avatar haircuts for avatars created with export parameters: the avatar export retrieval request should be used instead.

4.8.1   Retrieve

Method

GET

URL

/avatars/{code}/mesh/

Description

Retrieve the zip archive with avatar mesh.

Please note: you should not use this method to retrieve avatar mesh for avatars created with export parameters: the avatar export retrieval request should be used instead.

Avatars computed with animated_face, head_1.2, and head_2.0 (head/mobile and bust/mobile subtypes only) pipelines support different levels of mesh details (LOD). Specify the desired LOD on mesh retrieval as a request parameter. Please find more information on mesh properties in the LOD table for each particular pipeline description in the available pipelines section.

Request Parameters

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

4.9.1   List

Method

GET

URL

/avatars/{code}/textures/

Description

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

Use this request to retrieve a list of available textures for the particular avatar. The particular avatar is identified by the code URL part.

Please note: you should not use this method to retrieve a list of avatar textures for avatars created with export parameters: avatar exports list request should be used instead.

Please see the 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"
    }
]

4.9.2   Retrieve

Method

GET

URL

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

Description

Retrieve a particular texture file identified by its identity for a 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.

Please note: you should not use this method to retrieve an avatar texture for avatars created with export parameters: avatar exports list request should be used instead.

4.10.1   Retrieve

Method

GET

URL

/avatars/{code}/blendshapes/

Description

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

Please note: you should not use this method to retrieve avatar blendshapes for avatars created with export parameters: the avatar export retrieval request should be used instead.

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

Avatars computed with animated_face, head_1.2, and head_2.0 (head/mobile subtype only) pipelines support different levels of blendshapes details (LOD). For more information on LOD details see avatar mesh retrieve request. Specify the 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, 8]

4.11.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.12.1   Retrieve

Method

GET

URL

/avatars/{code}/model_info/

Description

Retrieve JSON object with avatar model meta-information requested on avatar creation. Please see the model info parameters section for available parameters.

Please see the example response below:

{
    "age": "not_child",
    "age_confidence": 1,
    "gender": "male",
    "gender_confidence": 0.9999961853027344,
    "hair_color": {
        "blue": 114,
        "green": 145,
        "red": 199
    },
    "pipeline": "animated_face",
    "pipeline_subtype": "base/legacy",
    "skin_color": {
        "blue": 151,
        "green": 181,
        "red": 235
    }
}

4.13.1   Create

Method

POST

URL

/selfies/

Description

Create a new selfie upload page. Please see the selfie DTO for the response format.

4.13.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.13.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.14.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": "haircuts",
                "file": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/generated/file/",
                "identity": "generated",
                "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/afro/file/",
                "identity": "afro",
                "static_files": [
                    "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/files/afro/static_files/texture.png"
                ]
            }
        ],
        "status": "Completed",
        "url": "https://api.avatarsdk.com/avatars/e56d6044-fdbf-4cbf-86df-793bf21494f4/exports/c0fc0ece-e291-4bbe-bdf2-ece270e0e065/"
    }
]

4.14.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.

Please see also note on static export files. Static file cache key may be constructed by concatenating Avatar export file category, identity, and static filename. E.g., for the texture of the afro haircut from the example above, the cache key may be: haircuts/afro/texture.png

Please note: for the metaperson_2.0 pipeline, static export files are static resources essentially, thus cache key construction rules are not applicable. Use the full URL as a cache key instead.