Avatar WEB API

Contents

1   Usage examples

If you want to try out Avatar WEB API in action right now, please check out the following samples:

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 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 in 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 application authorization grant type) you will need the following settings:

For more information on grant types, see section 4 of 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 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 detailed description for each particular method to find more information about available access modes and its 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 to sign each request with 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 which 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 a 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 application will need to wait to perform the next request. See example below:

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

3   Avatars

3.1   Available pipelines

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

Source photo
static : deprecated
Static bald head with separate haircuts.
animated_face

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 specified
  • indie/legacy_styled subtype have different model topology to make available optional mesh modifications (see computation parameters section below)
Model sample
head_1.0 : deprecated
Predicted head, haircut, and bust. All-in-one model with unique topology.
head_1.1 : deprecated
Predicted head, haircut, and bust. All-in-one model with unique topology. Improved texture and mesh quality (compared to head_1.0).
head_1.2

Predicted head, haircut, and bust. All-in-one model with unique topology. Fixed shape and texture artifacts in long hair and busts that are present in head_1.1. 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
head_2.0

Takes the best of head_1.1 and animated_face avatars. Looks exactly like head_1.1, but a 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).

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
body_0.1 : deprecated

Please note: this pipeline is deprecated, please use body_0.2 or body_0.3 instead.

Predicted bald head and full body model with fixed topology and detachable predicted haircut. Predictions may be improved by specifying the height, weight, and gender of the model.

Please note: the pipeline supports adult bodies only. If you specify parameters as for a child (small height and small weight) then the pipeline will return a body following these parameters, but it will be the body of a small adult, not a child.

Please note: available on the Pro subscription plan only.

Available subtypes:

  • body/mobile - full body model with a set of 51 facial blendshapes and 15 visemes.
Model samples
body_0.2

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. Model skeleton is also available for use with animations.

Please note: the pipeline supports adult bodies only. If you specify parameters as for a child (small height and small weight) then the pipeline will return a body following these parameters, but it will be the body of a small adult, not a child.

Please note: available on the Pro subscription plan only.

Available subtypes:

  • body/mobile - full body model with a set of 51 facial blendshapes and 15 visemes.
Model samples
body_0.3

Evolution of body_0.2 pipeline: improved prediction of the body shape and support of 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 - full body model with a set of 51 facial blendshapes and 15 visemes.
Model samples

3.1.1   Pipelines availability on subscription plans

  Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0 body_0.1, body_0.2 body_0.3
base/legacy base/legacy, base/mobile, base/static bust/mobile, bust/static, head/mobile body/mobile mobile
Available starting Plus Plus Pro Pro Pro

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

  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 indie, plus and pro in the order of priority, starting with least priority. Each next group includes all previous. The facegen group is available starting from the Plus plan.

    Please note: group level is omitted for body_0.3 pipeline

  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 array, key-value parameters are specified as JSON object. 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 find parameters availability upon your subscription plan for each avatar pipeline in the tables at the end of each category section below. Each cell represents a lower pricing plan. If a cell is empty - it is not available at all.

Please see 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 three sets of artificial haircuts which are modified during 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
plus set

50 haircuts in total, some of them are unisex

Haircuts samples

Availability of these sets depends on your current pricing plan.

Also we have additionally generated haircut. This haircut is unique and generated for each particular avatar to match the haircut from the source photo. Please note: if there 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.

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

3.2.1.1   Parameters availability

Haircuts Set Pipeline / Pipeline Subtype
animated_face head_2.0 body_0.1, body_0.2 body_0.3
base/legacy, indie/legacy_styled bust/mobile, head/mobile body/mobile mobile
base set Plus Pro Pro Pro
facegen set Plus      
generated   Pro Pro Pro
plus set   Pro Pro Pro

Please see parameters retrieval request to retrieve a list of available haircuts for particular pipeline type and pipeline subtype for your account. Please note: each particular haircut name must be specified in avatar creation request to be computed for particular avatar (except for those pipelines, which utilizes export parameters, like head_1.2, head_2.0 or body_0.3).

3.2.1.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=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
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'base/legacy',
    'name': 'haircuts test',
    'parameters': json.dumps({
        'haircuts': {
            'base': [
                'female_NewSea_J086f',
                'male_NewSea_J003m',
            ],
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()
avatar = requests.get(avatar['url'], headers=headers).json()

haircuts_url = avatar['haircuts']
haircuts = requests.get(haircuts_url, headers=headers).json()

for haircut in haircuts:
    identity = haircut['identity']

    mesh_url = haircut['mesh']
    mesh = requests.get(mesh_url, headers=headers)
    with io.BytesIO(mesh.content) as zipmemory:
        with zipfile.ZipFile(zipmemory) as archive:
            archive.extractall()

    texture_url = haircut['texture']
    texture = requests.get(texture_url, headers=headers)
    with open(identity + '.jpg', 'wb') as texture_file:
        texture_file.write(texture.content)

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

Please see parameters retrieval request (or enumerable export parameters retrieval request for body_0.3 pipeline) to retrieve a list of available outfits.

3.2.2.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
body_0.2 body_0.3
body/mobile mobile
base set Pro Pro

3.2.2.2   Usage examples

For body_0.2 pipeline, outfits are embedded into avatar mesh for both fbx and gltf formats. Outfit textures are also included in the avatar mesh archive. Thus requesting only the avatar mesh is sufficient to retrieve the avatar and all requested to compute outfits.

For body_0.3 pipeline, outfits should be exported with separate export parameters (see export parameters section) and may be embedded into the main avatar mesh or downloaded separately. Please see the sample for exports API.

curl
$ curl -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" \
       -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" \
       -X POST \
       "https://api.avatarsdk.com/avatars/" \
       -F "pipeline=body_0.2" \
       -F "pipeline_subtype=body/mobile" \
       -F "name=haircuts test" \
       -F "parameters={\"outfits\": {\"base\": [\"outfit_0\", \"outfit_1\"]}}" \
       -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/mesh/?fmt=fbx" > avatar.zip
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'body_0.2',
    'pipeline_subtype': 'body/mobile',
    'name': 'haircuts test',
    'parameters': json.dumps({
        'outfits': {
            'base': [
                'outfit_0',
                'outfit_1',
            ],
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()
avatar = requests.get(avatar['url'], headers=headers).json()

model_url = avatar['mesh']
model_format = {'fmt': 'fbx'}
model = requests.get(model_url, headers=headers, params=model_format)
with open('model.zip', 'wb') as model_file:
    texture_file.write(texture.content)

3.2.3   Blendshapes

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

legacy_45
The basic set of 45 facial blendshapes
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
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 that required these 15 visemes. You can find more details here: https://developer.oculus.com/documentation/audiosdk/latest/concepts/book-audio-ovrlipsync/

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

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/

3.2.3.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0 body_0.1, body_0.2 body_0.3
base/legacy, indie/legacy_styled base/legacy base/mobile bust/mobile, head/mobile body/mobile mobile
legacy_45 Plus Plus        
mobile_51     Plus Pro Pro Pro
visemes_15     Plus Pro Pro Pro
visemes_17 Plus Plus        

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

3.2.3.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=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
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'base/legacy',
    'name': 'blendshapes test',
    'parameters': json.dumps({
        'blendshapes': {
            'base': [
                'legacy_45',
                'visemes_17',
            ],
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()
avatar = requests.get(avatar['url'], headers=headers).json()

blendshapes_url = avatar['blendshapes']
parameters = {'fmt': 'fbx', 'lod': 5}
blendshapes = requests.get(blendshapes_url, params=parameters, headers=headers)
with io.BytesIO(blendshapes.content) as zipmemory:
    with zipfile.ZipFile(zipmemory) as archive:
        archive.extractall()

3.2.4   Model info

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

age
Classify a person's age from a submitted photo. Currently possible values are child and not_child. age_confidence also will be present in model_info to represent the confidence of age classification with value in the range [0.5, 1] inclusive
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 flat JSON array with X, Y, Z float components sequence for each landmark, or NaN (for each component) if no landmark detected

Please note: for base/legacy and indie/legacy_styled subtypes of animated_face pipeline, landmarks in range [0-7] and [9-16] are not present (i.e. they 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 value in the range [0.5, 1] inclusive
hair_color
Compute average haircut color [1] from a submitted photo
lips_color
Compute average lips 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 special value absolutely_bald which represents the absence of haircut. Please note: predicted haircut is independent on which haircuts were requested to compute with a particular avatar

For head_2.0 additionally estimates haircuts correspondence and put 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 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 its 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.2.4.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0 body_0.1, body_0.2 body_0.3
base/legacy, indie/legacy_styled base/legacy, base/mobile, base/static bust/mobile bust/static head/mobile body/mobile mobile
age Plus Plus Pro Pro Pro Pro Pro
eye_iris_color Plus Plus Pro Pro Pro Pro Pro
eye_sclera_color Plus Plus Pro Pro Pro Pro Pro
facial_landmarks_68 Plus Plus     Pro Pro Pro
gender Plus Plus Pro Pro Pro Pro Pro
hair_color Plus   Pro Pro Pro Pro Pro
lips_color Plus Plus          
predict_haircut Plus   Pro   Pro    
race Plus Plus Pro Pro Pro Pro Pro
skin_color Plus Plus Pro Pro Pro Pro Pro

Please see parameters retrieval request to retrieve a list of available model info flags for 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=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"
}
Python
import json, requests

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'base/legacy',
    'name': 'info test',
    'parameters': json.dumps({
        'model_info': {
            'base': [
                'hair_color',
            ],
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()
avatar = requests.get(avatar['url'], headers=headers).json()

avatar_info = requests.get(avatar['model_info'], headers=headers).json()
print(avatar_info)

3.2.5   Avatar modifications

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

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

add_eyelid_shadow : boolean

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

Models comparison
add_glare : boolean

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

Models comparison
allow_modify_neck : boolean

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

Models comparison
caricature_amount : float

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

Models comparison
curved_bottom : boolean

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

Models comparison
enhance_lighting : boolean

Attempt to make lighting more uniform. See models comparison below

Models comparison
eye_iris_color : color [1]

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

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
gender : deprecated

Please note: this parameter is deprecated, please use the gender parameter in the body shape parameters section for body_0.2 pipeline.

Expected model gender. Avalable values are male and female. If not specified, gender is autodetected.

Models comparison
generated_haircut_faces_count : integer

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

Models comparison
generated_haircut_texture_size : size [2]
Resize generated haircut texture to the specified size. Original haircut texture size is 1024x1024 px, thus setting size greater than this value will not result in improved texture quality.
hair_color : color [1]

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

Models comparison
height : deprecated

Please note: this parameter is deprecated, please use the height parameter in the body shape parameters section for body_0.2 pipeline.

Expected model height in meters, greater than zero. Please note: does not take effect without weight specified.

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 eye texture from the submitted photo with 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 models comparison below

Models comparison
parametric_eyes_texture_v2 : boolean

Replace eye texture from the submitted photo with generated one with sclera and iris colors to match the photo version. See 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 start. Currently detects and removes mostly open smiles (e.g. smiles with mouth open). Status of smile removal may be obtained later from model information JSON Object by remove_smile key (see avatar model information retrieval request). Please find the model comparison below

Models comparison
remove_glasses : boolean

Attempt to remove glasses on the submitted photo before the actual avatar computation start. Status of glasses removal may be obtained later from 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 textures comparison below

Textures comparison
slightly_cartoonish_texture : boolean

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

Models comparison
teeth_color : color [1]

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

Models comparison
texture_size : size [2]
Resize model texture to the specified size. Original texture size is 2048x2048 px, thus setting size greater than this value will not result in improved texture quality.
weight : deprecated

Please note: this parameter is deprecated, please use the weight parameter in the body shape parameters section for body_0.2 pipeline.

Expected model weight in kilograms, greater than zero. Please note: does not take effect without height specified.

Models comparison

3.2.5.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0 body_0.1 body_0.2 body_0.3
base/legacy indie/legacy_styled base/legacy base/mobile base/static bust/mobile bust/static head/mobile body/mobile body/mobile mobile
add_eyelid_shadow   Plus   Plus   Pro   Pro Pro Pro Pro
add_glare   Plus   Plus   Pro   Pro Pro Pro Pro
allow_modify_neck Plus Plus           Pro      
caricature_amount Plus Plus                  
curved_bottom     Plus Plus Plus Pro Pro        
enhance_lighting     Plus Plus Plus Pro Pro Pro Pro Pro Pro
eye_iris_color   Plus   Plus   Pro   Pro Pro Pro Pro
eye_sclera_color   Plus   Plus   Pro   Pro Pro Pro Pro
gender                 Pro    
generated_haircut_faces_count           Pro   Pro Pro Pro Pro
generated_haircut_texture_size           Pro   Pro Pro Pro Pro
hair_color           Pro Pro Pro Pro Pro  
height                 Pro    
lips_color Plus Plus   Plus Plus            
parametric_eyes_texture   always set   Plus   Pro   Pro Pro Pro Pro
parametric_eyes_texture_v2           Pro   Pro      
remove_glasses     Plus Plus Plus Pro Pro Pro Pro Pro Pro
remove_smile     Plus Plus Plus Pro Pro Pro Pro Pro Pro
repack_texture     Plus Plus   always set          
slightly_cartoonish_texture     Plus Plus Plus Pro Pro Pro      
teeth_color Plus Plus Plus Plus   Pro   Pro Pro Pro Pro
texture_size           Pro Pro Pro Pro Pro  
weight                 Pro    

Please see parameters retrieval request to retrieve a list of available avatar modification parameters for 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=base/legacy" \
       -F "name=modifications test" \
       -F "parameters={\"avatar_modifications\": {\"plus\": {\"lips_color\": {\"red\": 222, \"green\": 173, \"blue\": 190}}}}" \
       -F "photo=@photo.jpg"
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'base/legacy',
    'name': 'modifications test',
    'parameters': json.dumps({
        'avatar_modifications': {
            'plus': {
                'lips_color': {
                    'red': 222,
                    'green': 173,
                    'blue': 190,
                },
            },
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()

3.2.6   Shape modifications

Similar to avatar modification parameters, see 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. Valid values range is [0, +∞). 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. Valid values range is [0, +∞). Usable values range is model dependent and usually should be lower than 1

Models comparison

3.2.6.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0
indie/legacy_styled base/mobile head/mobile
cartoonish_v0.3 Plus    
cartoonish_v1.0   Plus Pro

Please see parameters retrieval request to retrieve a list of available shape modifications parameters for 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=indie/legacy_styled" \
       -F "name=modifications test" \
       -F "parameters={\"shape_modifications\": {\"indie\": {\"cartoonish_v0.3\": 0.5}}}" \
       -F "photo=@photo.jpg"
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'indie/legacy_styled',
    'name': 'modifications test',
    'parameters': json.dumps({
        'shape_modifications': {
            'indie': {
                'cartoonish_v0.3': 0.5,
            },
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()

3.2.7   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.2 pipeline:
Parameter name Gender
female male non_binary
height [150; 171] [160; 187] [150; 187]
weight [53; 76] [68; 90] [53; 90]
chest [90; 116] [96; 123] [90; 123]
waist [73; 99] [80; 115] [73; 115]
hips [92; 119] [96; 118] [92; 119]
For body_0.3 pipeline:
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 value.
height : float
Expected model's height in centimeters, greater than zero. If not specified, height is predicted. It is highly recommended to specify this parameter to avoid incorrectly autodetected value.
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 in centimeters, greater than zero. If not specified, chest girth is predicted.
waist : float
Expected model's waist girth in centimeters, greater than zero. If not specified, waist girth is predicted.
hips : float
Expected model's hips girth in centimeters, greater than zero. If not specified, hips girth is predicted.

3.2.7.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
body_0.2 body_0.3
body/mobile mobile
chest Pro Pro
gender Pro Pro
height Pro Pro
hips Pro Pro
waist Pro Pro
weight Pro Pro

3.2.7.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=body_0.2" \
       -F "pipeline_subtype=body/mobile" \
       -F "name=modifications test" \
       -F "parameters={\"body_shape\": {\"plus\": {\"gender\": \"male\", \"height\": 180, \"weight\": 85}}}" \
       -F "photo=@photo.jpg"
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'body_0.2',
    'pipeline_subtype': 'body/mobile',
    'name': 'modifications test',
    'parameters': json.dumps({
        'body_shape': {
            'plus': {
                'gender': 'male',
                'height': 180,
                'weight': 85,
            },
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()

3.2.8   Additional textures

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

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.2.8.1   Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.2 head_2.0
base/legacy indie/legacy_styled base/mobile, base/static bust/mobile, head/mobile
cartoonish_texture   Plus    
lips_mask Plus Plus Plus Pro
metallic_map     Plus Pro
roughness_map     Plus Pro
slightly_cartoonish_texture Plus Plus    
smooth_eyelashes_texture Plus Plus    

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

3.2.8.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
Python
import json, requests, io, zipfile

headers = {
    'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu',
    'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596',
}

data = {
    'pipeline': 'animated_face',
    'pipeline_subtype': 'base/legacy',
    'name': 'textures test',
    'parameters': json.dumps({
        'additional_textures': {
            'base': [
                'slightly_cartoonish_texture',
            ],
        },
    }),
}

files = {
    'photo': open('photo.jpg', 'rb'),
}

avatar = requests.post(
     'https://api.avatarsdk.com/avatars/',
     headers=headers, data=data, files=files,
).json()

textures_url = requests.compat.urljoin(avatar['url'], 'textures/')
textures = requests.get(textures_url, headers=headers).json()

for texture in textures:
    identity = texture['identity']

    texture_url = texture['file']
    texture_rsp = requests.get(texture_url, headers=headers)
    with open(identity + '.jpg', 'wb') as texture_file:
        texture_file.write(texture_rsp.content)

3.3   Export parameters

Avatar's export parameters contain a set of flags and 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 note: export parameters are currently available for head_1.2, head_2.0 and body_0.3 pipelines.

The general format for export parameters is the following:

{
  "flag": value,

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

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

The category may contain enumerable values (like haircuts). These values must be specified within the list key of this particular category. Please look at the enumerable export parameters retrieval request to retrieve a list of available export parameters for each particular category for pipeline and pipeline's subtype for your account. Please note: to avoid ambiguity in specifying different computation and enumerable export parameters (i.e., haircuts and blendshapes), export parameters take precedence.

All flags and values are optional and replaced by default values if not specified explicitly. Default export parameters are the following:

{
  "format": "gltf",
  "embed" : true,
  "pointclouds" : false,
  "additional_textures" : [],
  "embed_textures": false,
  "texture_size" : null,         // i.e. maximum available

  "haircuts": {
    "list": [],
    "format": null,              // i.e. top-level format
    "embed": null,               // i.e. top-level value
    "pointclouds": null,         // i.e. top-level value
    "color": null,
    "texture_size" : null,       // i.e. top-level size
    "embed_textures": null       // i.e. top-level value
  },

  "outfits": {
    "list": [],
    "format": null,              // i.e. top-level format
    "embed": null,               // i.e. top-level value
    "pointclouds": null,         // i.e. top-level value
    "additional_textures" : [],
    "texture_size" : null,       // i.e. top-level size
    "embed_textures": null       // i.e. top-level value
  }

  "blendshapes": {
    "list": [],
    "format": null,              // i.e. top-level format
    "embed": null,               // i.e. top-level value
    "pointclouds": null          // i.e. top-level value
  }
}

3.3.1   Available flags

additional_textures : list

List of textures to export besides default diffuse model texture. Available values are normal_map, roughness_map, metallic_map.

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

For head_1.2 and head_2.0 pipelines lips_mask is also available for top-level additional_textures

color : color [1]
If texture support recoloring, this flag specifies the base color for the recoloring process
embed : boolean
If avatar format (i.e. top-level format) supports sub-meshes (i.e. fbx, gltf, glb) this flag indicates whether to embed this particular category meshes into the avatar or store these meshes as separate files. If avatar format does not support sub-meshes - flag is set to false and category meshes are saved as separate files
embed_textures : boolean
If format supports textures embedding (i.e. fbx or glb), this flag indicates whether to embed textures or store them as separate files. If avatar format does not supports textures embedding - flag is set to false and textures are saved as separate files
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
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

texture_size : size [2]

Resize texture to the specified size. 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 resized according to avatar modifications first, and then according export parameters.

3.3.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.3.3   Static export files

Some export files may contain files, which 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 avatar exports list request description to find information about static files' retrieval.


[1](1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11) Color is represented as 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}
[2](1, 2, 3) Size is represented as JSON object with width and height keys and positive integer values. E.g. {"width": 256, "height": 256}

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 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 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 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 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 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   Enumerable export parameters

Enumerable export parameters DTO:

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

4.3.1   Retrieve

Method
GET
URL

/export_parameters/available/{pipeline}/

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

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

{
    "blendshapes": [
        "mobile_51",
        "visemes_15"
    ],
    "haircuts": [
        "generated",
        ...
        "wavy_bob"
    ]
}
Filters
  • pipeline_subtype - filter by subtype. See available pipelines for details about available pipeline subtypes

4.4   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 haven't changed yet since creation
  "ctime": string,

  // Absolute URL to retrieve zip with mesh of avatar
  "mesh": string,

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

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

  // Absolute URL to retrieve 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,

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

See avatar blendshapes for more information about blendshapes retrieval

4.4.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 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.4.2   Retrieve

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

4.4.3   Create

Method
POST
URL
/avatars/
Description

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

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

It is your responsibility to poll 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 photo or selfie must be provided. Error is returned if none or both are provided
  • selfie - selfie code. Please see selfies section to learn more about selfies. Either selfie or photo must be provided. Error is returned if none or both are provided. Error is returned if selfie file was not uploaded yet by end-user
  • pipeline - an optional field to specify which pipeline to use for new avatar generation. Please see available pipelines for the list of possible field values. Assumed value is animated_face if 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 submitted - replaced with default parameters for specified pipeline and (optionally) pipeline subtype. See parameters retrieval request to find out default/available parameters for pipeline type/subtype pairs. If no parameters required to compute avatar - submit empty JSON object: {}
  • 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 or head_2.0 pipelines - no avatar exports will be created.

4.4.4   Update

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

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

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

4.4.5   Delete

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

4.5   Avatars count

4.5.1   Retrieve

Method
GET
URL
/avatars/count/
Description
Retrieve number of avatars created (created field), number of free avatars left (i.e. included into your billing plan, prepaid field) and number of avatars to be paid (to_pay field) in the current billing period. Please see the example response below:
{
  "created": 8192,
  "prepaid": 0,
  "to_pay": 2192
}

4.6   Avatar haircuts

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

The same haircuts 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 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 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.6.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 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.6.2   Retrieve

Method
GET
URL
/avatars/{code}/haircuts/{identity}/
Description

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

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

4.7   Avatar mesh

4.7.1   Retrieve

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

Retrieve zip archive with avatar mesh.

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

Avatars computed with animated_face, head_1.2 and head_2.0 (head/mobile subtype only) pipelines support different levels of mesh details (LOD). Specify desired LOD on mesh retrieval as a request parameter. Please find more information on mesh properties in the table below:

  animated_face head_1.2 head_2.0
LOD# vertices faces vertices faces vertices faces
0 13043 24479 28651 53171 11894 23404
1 9898 18674 16481 30000 9969 19054
2 8122 15122 8677 15000 8732 16860
3 6107 11128 6012 10000 5713 11007
4 5363 9772 4921 8000 4953 9497
5 3859 6844 4333 7000 4259 7889
6 3062 5430 3742 6000 3789 6937
7 2342 3996 3191 5000 2034 3926
8 1425 2680 N/A N/A N/A N/A

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

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

4.8   Avatar textures

Base texture sizes:

animated_face head_1.2 head_2.0 body_0.1, body_0.2, body_0.3
base/static base/legacy, base/mobile
2048x2048 1024x1024 4096x2048 [3] 2048x2048 [4] 4096x2048 [4]

[3]Texture size is 2048x2048 if repack_texture flag set. Please see avatar modification parameters.
[4](1, 2) Texture size can be changed by specifying the texture_size flag. Please see avatar modification parameters (or export parameters flags for body_0.3 pipeline).

Avatar texture DTO:

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

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

4.8.1   List

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

Additional textures (along with default one) can be requested to compute for a particular avatar. See 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 articular 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.8.2   Retrieve

Method
GET
URL
/avatars/{code}/textures/{identity}/file/
Description
Retrieve a particular texture file identified by its identity for particular avatar identified by code. Texture format may vary (i.e. JPEG, PNG, etc.), thus consult Content-Type HTTP Response Header for particular texture format.

4.9   Avatar blendshapes

4.9.1   Retrieve

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

Retrieve zip archive with all available blendshapes for the specific avatar. If no blendshapes 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: 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 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.10   Avatar thumbnail

4.10.1   Retrieve

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

4.11   Avatar model information

4.11.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.12   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 new or existing selfie photo. For end-user convenience, the QR code with 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, 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 upload page visited
  "upload_page_visited": boolean,

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

4.12.1   Create

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

4.12.2   retrieve QR code

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

4.12.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 HEAD request first and download it with GET request once HTTP 200 response code returned.

4.13   Avatar exports

Avatar export DTO:

{
  // Avatar identifier
  "avatar_code": string,

  // Avatar export identifier
  "code": string,

  // ISO 8601 datetime
  "created_on": string,

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

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

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

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

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

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

    ...
  ],

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

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

4.13.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.13.2   Retrieve

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

Retrieve particular Avatar export file. Avatar is identified by code URL part, Avatar export is identified by export_code URL part and export file is identified by export_file URL part. Please see 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 afro haircut from the example above, cache key may be: haircuts/afro/texture.png