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

Samples
  • curl sample - create a selfie upload page and avatar once the selfie is uploaded using the curl utility
Other samples
  • selfie code sample - create a selfie upload page and avatar once the selfie is uploaded using the curl utility
  • 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.

All mesh/pointcloud retrieval endpoints produce a zip archive with mesh/pointcloud in binary PLY format 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

Please note: this document describes only animated_face pipeline. There are more pipelines available. Please visit main document to find currently available pipelines.

Source photo

3.1.1   animated_face

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

Available starting Plus plan subscription.

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:

  base/legacy
LOD# vertices faces
0 13043 24479
1 9898 18674
2 8122 15122
3 6107 11128
4 5363 9772
5 3859 6844
6 3062 5430
7 2342 3996
8 1425 2680

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

3.2   Computation parameters

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

  1. The first level is the parameter categories. E.g. set of blendshapes, haircuts, avatar modifications, etc. Please find all available categories with their description in the sections below.
  2. The next level is availability groups. Availability groups may be auto-assigned (e.g. base/common groups or pricing plan dependent groups) and custom (e.g. for custom work). base and public groups are assigned to everyone. Pricing plan dependent groups are plus and pro in the order of priority, starting with least priority. Each next group includes all previous ones. The facegen group is available starting from the Plus plan.
  3. The last 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.2.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

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

Please see the parameters retrieval request to retrieve a list of available haircuts for a particular pipeline type and pipeline subtype for your account. Please note: each particular haircut name must be specified in the avatar creation request to be computed for a particular avatar.

3.2.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=animated_face" \
       -F "pipeline_subtype=base/legacy" \
       -F "name=haircuts test" \
       -F "parameters={\"haircuts\": {\"base\": [\"female_NewSea_J086f\", \"male_NewSea_J003m\"]}}" \
       -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/haircuts/"

[
    {
        "gender": "female",
        "identity": "female_NewSea_J086f",
        "mesh": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/female_NewSea_J086f/mesh/",
        "model": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/",
        "pointcloud": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/female_NewSea_J086f/pointcloud/",
        "preview": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/female_NewSea_J086f/preview/",
        "texture": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/female_NewSea_J086f/texture/",
        "url": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/female_NewSea_J086f/"
    },
    {
        "gender": "male",
        "identity": "male_NewSea_J003m",
        "mesh": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/male_NewSea_J003m/mesh/",
        "model": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/",
        "pointcloud": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/male_NewSea_J003m/pointcloud/",
        "preview": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/male_NewSea_J003m/preview/",
        "texture": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/male_NewSea_J003m/texture/",
        "url": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/haircuts/male_NewSea_J003m/"
    }
]

$ 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/haircuts/female_NewSea_J086f/mesh/" > female_NewSea_J086f.zip

$ 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/haircuts/female_NewSea_J086f/texture/" > female_NewSea_J086f.jpg

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

legacy_45

deprecated

The basic set of 45 facial blendshapes

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

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

3.2.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=animated_face" \
       -F "pipeline_subtype=base/legacy" \
       -F "name=blendshapes test" \
       -F "parameters={\"blendshapes\": {\"base\": [\"legacy_45\", \"visemes_17\"]}}" \
       -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/blendshapes/?fmt=fbx&lod=5" > blendshapes_fbx_5.zip

3.2.3   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
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 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
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

Please see the parameters retrieval request to retrieve a list of available model info flags for a particular pipeline type and pipeline subtype for your account.

3.2.3.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=animated_face" \
       -F "pipeline_subtype=base/legacy" \
       -F "name=info test" \
       -F "parameters={\"model_info\": {\"base\": [\"hair_color\"]}}" \
       -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/"

{
    "hair_color": {
        "blue": 109,
        "green": 131,
        "red": 172
    },
    "pipeline": "animated_face",
    "pipeline_subtype": "base/legacy"
}

3.2.4   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
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
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
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

3.2.4.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face
base/legacy indie/legacy_styled
add_eyelid_shadow   ✓
add_glare   ✓
allow_modify_neck ✓ ✓
caricature_amount ✓ ✓
eye_iris_color   ✓
eye_sclera_color   ✓
lips_color ✓ ✓
parametric_eyes_texture   always set
teeth_color ✓ ✓

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

3.2.4.2   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=animated_face" \
       -F "pipeline_subtype=base/legacy" \
       -F "name=modifications test" \
       -F "parameters={\"avatar_modifications\": {\"plus\": {\"lips_color\": {\"red\": 222, \"green\": 173, \"blue\": 190}}}}" \
       -F "photo=@photo.jpg"

3.2.5   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

3.2.5.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face
indie/legacy_styled
cartoonish_v0.3 ✓

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

3.2.5.2   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=animated_face" \
       -F "pipeline_subtype=indie/legacy_styled" \
       -F "name=modifications test" \
       -F "parameters={\"shape_modifications\": {\"indie\": {\"cartoonish_v0.3\": 0.5}}}" \
       -F "photo=@photo.jpg"

3.2.6   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
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.2.6.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face
base/legacy indie/legacy_styled
cartoonish_texture   ✓
lips_mask ✓ ✓
slightly_cartoonish_texture ✓ ✓
smooth_eyelashes_texture ✓ ✓

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

3.2.6.2   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=animated_face" \
       -F "pipeline_subtype=base/legacy" \
       -F "name=textures test" \
       -F "parameters={\"additional_textures\": {\"base\": [\"slightly_cartoonish_texture\"]}}" \
       -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/textures/"

[
    {
        "file": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/textures/model/file/",
        "identity": "model"
    },
    {
        "file": "https://api.avatarsdk.com/avatars/d4a31ac7-4aab-4cdc-b70b-75e75fc6bd91/textures/slightly_cartoonish_texture/file/",
        "identity": "slightly_cartoonish_texture"
    }
]

$ 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/textures/slightly_cartoonish_texture/file/" > slightly_cartoonish_texture.jpg
[1](1, 2, 3, 4, 5, 6, 7, 8, 9) 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. 'haircuts', 'blendshapes', etc.
  "category": {
    // Group of parameters. E.g. pricing plan or customer-specific group
    "group": [
      // 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):

{
  "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   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,

  // 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 zip with a mesh of avatar
  "mesh": string,

  // Absolute URL to retrieve the jpeg texture of the avatar
  "texture": string,

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

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

  // Absolute URL to retrieve zip archive of available blendshapes
  // for this avatar model
  "blendshapes": string,

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

See the avatar blendshapes for more information about blendshapes retrieval

4.3.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.3.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.3.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: {}

4.3.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.3.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.4   Avatars count

4.4.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.5   Avatar haircuts

Represents per-avatar haircuts morphed to fit the particular avatar model geometry.

The same haircut meshes are interchangeable between different avatars if the corresponding pointcloud is applied. E.g. you could store mesh from haircut1 of avatar1, then download only pointclouds for haircut1 of avatar2, avatar3, etc. and replace pointcloud in the previously-stored mesh. This way you could save customer's network traffic.

Per-Avatar haircut DTO:

{
  // Identifier of haircut
  "identity": string,

  // Haircut formal gender. One of [male, female, unisex]
  "gender": string,

  // Absolute URL to a preview of specified haircut
  "preview": string,

  // Absolute URL to this haircut
  "url": string,

  // Absolute URL to haircut png texture
  "texture": string,

  // Absolute URL to avatar model
  "model": string,

  // Absolute URL to per-avatar haircut point cloud zip
  "pointcloud": string,

  // Absolute URL to per-avatar haircut mesh zip
  "mesh": string
}

4.5.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 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.5.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.

4.6   Avatar mesh

4.6.1   Retrieve

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

Retrieve the zip archive with avatar mesh.

Avatars 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.7   Avatar textures

Avatar texture DTO:

{
  // Identifier of avatar texture
  "identity": string,

  // Absolute URL to this texture file
  "file": string,
}

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

4.8   Avatar blendshapes

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

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 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.9   Avatar thumbnail

4.9.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.10   Avatar model information

4.10.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.11   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.11.1   Create

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

4.11.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.11.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.