Avatar WEB API

Contents

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.

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:

application authorization URL: https://api.avatarsdk.com/o/authorize/
token retrieving URL: https://api.avatarsdk.com/o/token/
default application redirect URL: https://api.avatarsdk.com/o/default_callback/

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

Pagination

All requests that return lists are paginated: each particular request return list of requested objects (up to 100 objects per page) and links to first, previous, next and last pages in Link HTTP header. If there are no other pages - Link header will not be present.

Link header may contain up to 4 entries separated by comma ,. Each entry contains URL itself and its relation name (rel) separated by semicolon ;. See example below:

$ curl -v -X GET -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -H "Accept: application/json" "https://api.avatarsdk.com/avatars/?page=3"
> GET /avatars/?page=3 HTTP/1.1
> User-Agent: curl/7.35.0
> Host: api.avatarsdk.com
> Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu
> Accept: application/json
>
< HTTP/1.0 200 OK
< Date: Mon, 03 Apr 2017 04:08:15 GMT
< Link: <https://api.avatarsdk.com/avatars/>; rel="first", <https://api.avatarsdk.com/avatars/?page=2>; rel="prev", <https://api.avatarsdk.com/avatars/?page=4>; rel="next", <https://api.avatarsdk.com/avatars/?page=5>; rel="last"
< Content-Type: application/json
< Allow: GET, POST, HEAD, OPTIONS
<
[...]

For more information about Link header see Web Linking RFC document.

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.

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
<
[...]

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."}

Usage Examples

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

More API usage examples are coming.

Methods

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

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

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.

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.

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

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

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.

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.
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 - predicted head, haircut and bust
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 visems) for animations and separate haircuts. Default if no subtype specified
- for head pipeline:
  - 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 visems) for animations
  - base/mobile - predicted head, haircut and bust with set of blendshapes (51 facial) for animations
resources - specific resources to compute for submitted avatar. See resources DTO for this field format. If no value submitted - replaced with default resources for specified pipeline and (optionally) pipeline subtype. See resources retrieval request to find out default/available resources for pipeline type/subtype pairs. If no resources should be computed - submit empty JSON object: {}

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

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.

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
}

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

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.

Avatar Blendshapes

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.

Request Parameters

fmt - blendshapes format. Available choices are: ply and fbx

Avatar Thumbnail

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]

Resources

Resources DTO:

{
  // category of resource. E.g. 'haircuts', or 'blendshapes'
  "category": {
    // group of resource. Pricing plan or customer-specific
    "group": [
      // list of resource names
      "name",
      ...
    ]
  },
  ...
}

retrieve

Method: GET
URL: /resources/(available | default)/{pipeline}/
Description: Retrieve all available or default resources for specified pipeline and default pipeline sub-type. Use filters to retrieve resources for non-default pipeline sub-type. Response is an one key-value pair with pipeline_subtype as a key and resources as a value. Resources may be just copy-pasted as-is (or only part of it) into resources field of create avatar request parameters. Please see example response below (a little bit shortened for sake of compact example):

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

Filters

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