Avatar WEB API

Table of contents:

1   API basics

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

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

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

All mesh/pointcloud retrieval endpoints produces zip archive with mesh/pointcloud in binary PLY format unless stated otherwise.

1.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 OAuth site (recommended) or any other on your taste to add OAuth 2.0 support in your app.

In order to get your client_id and client_secret please sign up for AvatarSDK developer account.

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

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

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

1.4   Developer/Client access

API have two different access modes: developer and client access. 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 it's 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 OAuth access token. To do this you need to register PlayerUID once per unique application (e.g. on 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
<
[...]

1.5   Throttling

In order 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 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. In order 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 application exceeds limits it will receive HTTP 429 TOO MANY REQUESTS response code and Retry-After HTTP Response Header will be set to number of seconds application will need to wait to perform 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."}

1.6   Avatar Computation Parameters

Avatar computation parameters contain a set of flags and parameters to fine-tune resulting avatar and meta-information about it. 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 its description in the sections below.
  2. 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.
  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. Value type is parameter dependent. Please see 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 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.

1.6.1   Haircuts

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

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

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

Parameters availability

Haircuts Set Pipeline / Pipeline Subtype
animated_face
base/legacy indie/legacy_styled
base set Free Indie
facegen set Plus Plus

1.6.2   Blendshapes

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

legacy_45
The basic set of 45 facial blendshapes.
visems_17

Set of 15 visemes (aa, ch, ee, ih, oh, ou, th, dd, ff, kk, nn, pp, rr, sil, ss) and two additional blendshapes: frown and smile. This set is compatible with Oculus Lipsync that required these 15 visemes. You can find more details here: https://developer.oculus.com/documentation/audiosdk/latest/concepts/book-audio-ovrlipsync/

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

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

Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.0 head_1.1/head_1.2
base/legacy indie/legacy_styled base/legacy base/mobile base/legacy base/mobile
legacy_45 Free Indie Free   Free  
visems_17 Free Indie Free   Free  
mobile_51       Free   Free

1.6.3   Model Info

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

hair_color
Compute average haircut color [1] from a submitted photo.
predict_haircut
Predict which haircut from the base and the facegen sets matches best to the submitted photo. haircut_name will contain corresponding haircut identifier. May contain special value absolutely_bald which represents the absence of haircut. Please note: predicted haircut is independent on which haircuts were requested to compute with a particular avatar.
skin_color
Compute average skin color [1] from a submitted photo
gender
Predict person's gender from a submitted photo. Possible values are male and female. gender_confidence also will be present in model_info to represent the confidence of gender prediction with value in the range [0.5, 1] inclusive
age
Classify a person's age from a submitted photo. Currently possible values are child and not_child. age_confidence also will be present in model_info to represent the confidence of age classification with value in the range [0.5, 1] inclusive
facial_landmarks_68
Compute facial landmarks. Landmark coordinates are represented as flat JSON Array with X, Y, Z float components sequence for each landmark, or NaN (for each component) if no landmark detected
eye_sclera_color
Compute average eye sclera color [1] from a submitted photo
eye_iris_color
Compute average eye iris color [1] from a submitted photo
lips_color
Compute average lips color [1] from a submitted photo
Colors correspondance

Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.1/head_1.2
base/legacy indie/legacy_styled base/static base/legacy base/mobile
hair_color Free Indie      
skin_color Plus Plus Plus Plus Plus
gender Plus Plus Plus Plus Plus
age Plus Plus Plus Plus Plus
facial_landmarks_68 Plus Plus Plus Plus Plus
eye_sclera_color Plus Plus Plus Plus Plus
eye_iris_color Plus Plus Plus Plus Plus
lips_color Plus Plus Plus Plus Plus
predict_haircut Plus Plus      

1.6.4   Avatar Modifications

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

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

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

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

Models comparison
slightly_cartoonish_texture : boolean

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

Models comparison
parametric_eyes_texture : boolean

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

Models comparison
add_glare : boolean

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

Textures comparison
add_eyelid_shadow : boolean

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

Textures comparison
eye_iris_color : color [1]

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

Textures comparison
eye_sclera_color : color [1]

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

Textures comparison
caricature_amount : float

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

Models comparison
lips_color : color [1]

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

Textures comparison

Parameters availability

Parameter Name Pipeline / Pipeline Subtype
animated_face head_1.1/head_1.2
base/legacy indie/legacy_styled base/static base/legacy base/mobile
allow_modify_neck Indie Indie      
curved_bottom     Plus Plus Plus
slightly_cartoonish_texture     Plus Plus Plus
parametric_eyes_texture   always set     Plus
add_glare   Plus     Plus
add_eyelid_shadow   Plus     Plus
eye_iris_color   Plus     Plus
eye_sclera_color   Plus     Plus
lips_color Plus Plus Plus   Plus
caricature_amount Plus Plus      

1.6.5   Shape Modifications

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

cartoonish_v0.3 : float

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

Models comparison

Parameters availability

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

1.6.6   Additional Textures

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

slightly_cartoonish_texture

Slightly smoother than the original texture.

Textures comparison
cartoonish_texture

Uniformly colored texture.

Textures comparison
smooth_eyelashes_texture

Original texture with smoothen area of eyelashes.

Textures comparison
lips_mask

Mask in PNG format.

Textures comparison

Parameters availability

Prameter Name Pipeline / Pipeline Subtype
animated_face head_1.1/head_1.2
base/legacy indie/legacy_styled base/static base/mobile
slightly_cartoonish_texture Free Indie    
cartoonish_texture   Plus    
smooth_eyelashes_texture Plus Plus    
lips_mask Plus Plus Plus Plus

[1](1, 2, 3, 4, 5, 6, 7, 8) 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   Usage Examples

We have developed several samples where you could see this API in action:

More API usage examples are coming.

3   Methods

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

3.1.1   list

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

3.1.2   retrieve

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

3.1.3   create

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

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

See avatar blendshapes for more information about blendshapes retrieval

3.2.1   list

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

3.2.2   retrieve

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

3.2.3   create

Method
POST
URL
/avatars/
Description

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

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

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

Request parameters

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

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

3.2.4   update

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

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

  • name - new Avatar name
  • description - new Avatar description

3.2.5   delete

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

3.3   Avatar Haircuts

Represents per-Avatar haircuts morphed to fit particular Avatar model geometry.

The same haircuts meshes are interchangeable between different Avatars if 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
}

3.3.1   list

Method
GET
URL
/avatars/{code}/haircuts/
Description
Retrieve list of per-avatar haircuts. Particular Avatar is identified by code URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID. Please see avatar haircut DTO for response format description. Please see example response below:
[
  {
    "identity":"female_NewSea_J086f",
    "gender":"female",
    "preview":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/preview/",
    "url":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/",
    "texture":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/texture/",
    "model":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/",
    "pointcloud":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/pointcloud/",
    "mesh":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/mesh/"
  },
  ...
]
Filters
  • gender - filter by haircut gender

3.3.2   retrieve

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

3.4   Avatar Mesh

3.4.1   retrieve

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

Retrieve zip archive with Avatar mesh.

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

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

3.5   Avatar Textures

Avatar texture DTO:

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

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

3.5.1   list

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

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

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

Please see example response below:

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

3.5.2   retrieve

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

3.6   Avatar Blendshapes

3.6.1   retrieve

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

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

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

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

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

3.7   Avatar Thumbnail

3.7.1   retrieve

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

3.8   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",
      ...
    ]
  },
  ...
}

3.8.1   retrieve

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

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

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

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

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