Contents
If you want to try out Avatar WEB API in action right now, please see the samples below.
Before you begin, please check our recommendations for improving the resulting model (in the order of significance):
More API usage examples are coming.
Root API URL: https://api.avatarsdk.com/
API endpoints produce JSON responses unless stated otherwise. Please see the Content-Type HTTP Header for a particular response format.
All POST requests accept multipart/form-data unless stated otherwise.
All mesh/pointcloud retrieval endpoints produce a zip archive with mesh/pointcloud in binary PLY format unless stated otherwise.
Before any of the API methods can be used, you should generate an application identifier (referenced later as client_id) for your app. This identifier is used to obtain the access token which is then used to sign actual API requests. You could use one of the official libraries listed on the OAuth site (recommended) or any other on your taste to add OAuth 2.0 support to your app.
To get your client_id and client_secret, please sign up for the AvatarSDK developer account.
Besides client_id and client_secret (depending on the application authorization grant type) you will need the following settings:
For more information on grant types, see section 4 of the OAuth 2.0 RFC document.
All requests that return lists are paginated: each particular request returns a list of requested objects (up to 100 objects per page) and links to the first, previous, next, and last pages in the Link HTTP header. If there are no other pages - the Link header will not be present.
The Link header may contain up to 4 entries separated by a comma ,. Each entry contains the URL itself and its relation name (rel) separated by a 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 the Link header, see the Web Linking RFC document.
Results of list-retrieving requests may be filtered by some fields of requested objects (e.g. creation time, status, etc.) by specifying filters as a query parameter. All filters are case-insensitive unless stated otherwise. Filters may be specified several times. In this case, they all will be joined via logical AND. See example below:
$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -X GET "https://api.avatarsdk.com/avatars/?status=completed&description=fb" > GET /avatars/?status=completed&description=fb HTTP/1.1 > User-Agent: curl/7.35.0 > Host: api.avatarsdk.com > Accept: */* > Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu > < HTTP/1.0 200 OK < Date: Mon, 03 Apr 2017 04:08:15 GMT < Link: <https://api.avatarsdk.com/avatars/?description=fb&status=completed>; rel="first", <https://api.avatarsdk.com/avatars/?description=fb&page=1&status=completed>; rel="last" < Vary: Accept, Cookie < Content-Type: application/json < Allow: GET, POST, HEAD, OPTIONS < [...]
Please see the filters section in particular request documentation to find available filters.
API has two different access modes: developer and client access. The Client access mode is slightly more restricted in terms of access to some methods: e.g. it is restricted to list all avatars created with the same client_id and allowed to list only those created with the same PlayerUID, etc.
Please see the detailed description for each particular method to find more information about available access modes and their restrictions.
It is highly recommended to use Client access in applications released into production: malicious users won't be able to access or delete data of other users even if client_id and client_secret are compromised.
Client access mode requires signing each request with a PlayerUID identifier along with the OAuth access token. To do this you need to register PlayerUID once per unique application (e.g. on the first launch) and then sign each request with this PlayerUID via X-PlayerUID HTTP header. See example below:
$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" -X GET "https://api.avatarsdk.com/avatars/" > GET /avatars/ HTTP/1.1 > User-Agent: curl/7.35.0 > Host: api.avatarsdk.com > Accept: */* > Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu > X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596 > < HTTP/1.0 200 OK < Date: Mon, 03 Apr 2017 04:08:15 GMT < Vary: Accept, Cookie < Link: <https://api.avatarsdk.com/avatars/>; rel="first", <https://api.avatarsdk.com/avatars/?page=1>; rel="last" < Content-Type: application/json < Allow: GET, POST, HEAD, OPTIONS < [...]
To keep our system stable and healthy, we introduced a throttling mechanism that limits how many HTTP requests any particular client is allowed to make. Current limits are set to the following values:
Please note: in the Client access mode there is no limit to the number of requests per SDK account. To avoid throttling, please make sure to follow these guidelines:
If an application exceeds limits it will receive HTTP 429 TOO MANY REQUESTS response code and Retry-After HTTP Response Header will be set to the number of seconds the application will need to wait to perform the next request. See example below:
$ curl -v -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" -X GET "https://api.avatarsdk.com/avatars/" > GET /avatars/ HTTP/1.1 > User-Agent: curl/7.35.0 > Host: api.avatarsdk.com > Accept: */* > Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu > < HTTP/1.0 429 TOO MANY REQUESTS < Date: Mon, 03 Apr 2017 04:08:15 GMT < Retry-After: 10 < Vary: Accept, Cookie < Content-Type: application/json < Allow: GET, POST, HEAD, OPTIONS < {"detail":"Request was throttled. Expected available in 10.0 seconds."}
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 a pipeline subtype - a different set of features available, different model topology, etc. Please find a list of currently available avatar pipelines with their subtypes below (listed in the chronological order):
deprecated
Bald head with the optional set of blendshapes for animations (45 facial, 17 visemes) and separate haircuts.
Available subtypes:
Available LODs:
base/legacy | ||
---|---|---|
LOD# | vertices | faces |
0 | 13043 | 24479 |
1 | 9898 | 18674 |
2 | 8122 | 15122 |
3 | 6107 | 11128 |
4 | 5363 | 9772 |
5 | 3859 | 6844 |
6 | 3062 | 5430 |
7 | 2342 | 3996 |
8 | 1425 | 2680 |
Note: The structure of the head in LOD8 is the same as in LOD7 but without teeth.
Predicted head, haircut, and bust. All-in-one model with unique topology. Supports export parameters (multiple formats, unified or separate meshes, textures, etc).
Available subtypes:
Available LODs:
base/legacy | base/mobile | |||
---|---|---|---|---|
LOD# | vertices | faces | vertices | faces |
0 | 28005 | 52577 | 30818 | 58258 |
1 | 16123 | 29999 | 21439 | 40000 |
2 | 8518 | 14999 | 16373 | 30000 |
3 | 5968 | 9999 | 11293 | 19999 |
4 | 4875 | 7999 | 6043 | 9999 |
5 | 4325 | 7000 | 4973 | 8000 |
6 | 3727 | 6000 | 4439 | 6999 |
7 | 4999 | 3199 | 2471 | 4000 |
deprecated
Predicted head, haircut, and bust with unique topology. Hairstyle is represented with a separate mesh (except for bust/static subtype), and a bust can be removed (head/mobile subtype). Supports export parameters (multiple formats, unified or separate meshes, textures, etc). Tolerates rotated persons on the source photos (see samples below).
Please note: available on the Pro subscription plan only.
Available subtypes:
Available LODs:
bust/mobile | head/mobile | |||
---|---|---|---|---|
LOD# | vertices | faces | vertices | faces |
0 | 30979 | 57796 | 12367 | 23404 |
1 | 21908 | 39999 | 10374 | 19054 |
2 | 16816 | 29999 | 9116 | 16860 |
3 | 11564 | 20000 | 6059 | 11007 |
4 | 6174 | 9999 | 5287 | 9497 |
5 | 5036 | 8000 | 4587 | 7889 |
6 | 4480 | 6999 | 4106 | 6937 |
7 | 2510 | 4000 | 2102 | 3926 |
deprecated
Predicted bald head and full body model with fixed topology, predicted and artificial haircuts, and artificial outfits. Predictions of the body shape may be improved by specifying the height, weight, gender, and body measurements of the model. The model skeleton is also available for use with animations. Support various export options via the export parameters (multiple formats, unified or separate meshes, textures, etc).
Please note: available on the Pro subscription plan only.
Please note: this pipeline utilizes export parameters
Available subtypes:
Available LODs:
FitPerson
default template | head template | |||
---|---|---|---|---|
LOD# | vertices | faces | vertices | faces |
0 | 18689 | 34578 | 12367 | 23404 |
1 | 15633 | 28102 | 10374 | 19054 |
2 | 13850 | 24880 | 9116 | 16860 |
3 | 9285 | 16173 | 6059 | 11007 |
4 | 8096 | 13905 | 5287 | 9497 |
5 | 6987 | 11565 | 4587 | 7889 |
6 | 6271 | 10151 | 4106 | 6937 |
7 | 4267 | 7140 | 2102 | 3926 |
MetaPerson
female/male subtype | ||
---|---|---|
LOD# | vertices | faces |
0 | 19538 | 36196 |
1 | 15633 | 28102 |
2 | 13854 | 24880 |
3 | 9291 | 16173 |
4 | 8102 | 13905 |
5 | 6993 | 11565 |
6 | 6277 | 10151 |
7 | 4273 | 7140 |
Evolution of Metaperson subtype of body_0.3 pipeline. Contains blendshapes to customize the face and body after the creation of an avatar, skeleton, and PBR textures. The facial texture has much better quality. Avatar bodies have fixed topology. Support of various export options via the export parameters (multiple formats, unified or separate meshes, textures, etc).
Please note: access via the REST API is available on the Enterprise subscription plan only.
You also can integrate it into your project using an iframe and JS API on the Pro or Enterprise plans. Please visit https://docs.metaperson.avatarsdk.com/ for more information.
Please note: this pipeline utilizes export parameters and static resources
Available subtypes:
Available LODs:
female male LOD1 LOD2 LOD1 LOD2 avatar part vertices faces vertices faces vertices faces vertices faces AvatarBody 7131 12672 3409 5604 7131 12672 3347 5494 AvatarEyelashes 6300 4900 130 160 6300 4900 130 160 AvatarHead 7419 14404 1760 3314 7419 14404 1760 3314 AvatarLeftCornea 457 830 138 244 457 830 138 244 AvatarLeftEyeball 481 791 148 200 481 791 148 200 AvatarRightCornea 457 830 138 244 457 830 138 244 AvatarRightEyeball 481 791 148 200 481 791 148 200 AvatarTeethLower 2511 3464 253 406 2511 3464 253 406 AvatarTeethUpper 2497 3654 306 394 2497 3654 306 394 Total 27734 42336 6430 10766 27734 42336 6368 10656
Pipeline / Pipeline Subtype | |||||
---|---|---|---|---|---|
animated_face | head_1.2 | head_2.0 | body_0.3 | metaperson_2.0 | |
base/legacy | base/legacy, base/mobile, base/static | bust/mobile, bust/static, head/mobile | female, male, mobile | female, male | |
Available starting | Plus | Plus | Pro | Pro | Enterprise |
Avatar computation parameters contain a set of flags and parameters to fine-tune the avatar computation process. These parameters have three levels of detail:
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.
The next level is availability groups. Availability groups may be auto-assigned (e.g. base/common groups or pricing plan dependent groups) and custom (e.g. for custom work). base and public groups are assigned to everyone. Pricing plan dependent groups are plus and pro in the order of priority, starting with least priority. Each next group includes all previous ones. The facegen group is available starting from the Plus plan.
Please note: group level is omitted for body_0.3 pipeline
The last level is parameter types: enumerable and key-value parameters. Avatar computation parameters affect the computation process only if they are specified explicitly. Enumerable parameters are simply listed as JSON arrays, and key-value parameters are specified as JSON objects. The value type is parameter-dependent. Please see the parameter description in the sections below. Please note: all parameters are considered enumerable by default unless stated otherwise.
Please find the 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 the parameters retrieval request to retrieve a list of available and default parameters for each particular pipeline and pipeline subtype on your account.
We have four sets of artificial haircuts that are modified during the avatar computation process to match each particular avatar head geometry:
3 male and 3 female haircuts
39 haircuts in total, some of them are unisex
A set of haircuts for metaperson_2.0 pipeline
50 haircuts in total, some of them are unisex
This haircut is unique and generated for each particular avatar to match the haircut from the source photo. Please note: if it is detected that the source photo does not have a haircut (i.e. a bald person) - there will be no generated haircut in the list of available haircuts for the computed avatar.
Please note: for the metaperson_2.0 pipeline, the generated haircut is specified as HaircutGenerated in export parameters and present as an avatar head blendshape named Haircut. To demonstrate it you also need to blend its texture with the avatar head texture.
Availability of these sets depends on your current pricing plan.
It is also possible to add your haircut: contact us at support@avatarsdk.com
Haircuts Set | Pipeline / Pipeline Subtype | |||
---|---|---|---|---|
animated_face | head_2.0 | body_0.3 | metaperson_2.0 | |
base/legacy, indie/legacy_styled | bust/mobile, head/mobile | female, male, mobile | female, male | |
base set | Plus | Pro | Pro | |
facegen set | Plus | |||
generated | Pro | Pro | Enterprise | |
metaperson set | Enterprise | |||
plus set | Pro | Pro |
Please see the parameters retrieval request to retrieve a list of available haircuts for a particular pipeline type and pipeline subtype for your account. Please note: each particular haircut name must be specified in the avatar creation request to be computed for a particular avatar (except for those pipelines, that utilizes export parameters, like head_1.2, head_2.0, body_0.3, or metaperson_2.0).
$ 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
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)
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.
Set of business, business casual, and casual outfits
Set of complete outfits adapted for metaperson_2.0 avatar bodies.
Set of outfits, applicable to the upper body (e.g. t-shirt, hoodie, etc.)
Set of outfits, applicable to the lower body (e.g. pants, jeans, etc.)
Set of shoes (e.g. shoes, sneakers, etc.)
Available outfits 3D mesh details for base sets:
outfit # | base set | base_lowpoly set | ||
---|---|---|---|---|
vertices | faces | vertices | faces | |
0 | 29815 | 51616 | 6186 | 8880 |
1 | 21426 | 39312 | 2872 | 4270 |
2 | 32570 | 60102 | 4252 | 6844 |
3 | 24655 | 42832 | 4983 | 6626 |
4 | 17830 | 30383 | 4518 | 6270 |
5 | 27715 | 48362 | 5875 | 9017 |
Available outfits 3D mesh details for meta sets:
outfit # | meta set | meta_lowpoly set | ||
---|---|---|---|---|
vertices | faces | vertices | faces | |
0 | 26840 | 46147 | 6222 | 9006 |
1 | 21576 | 39312 | 2961 | 4432 |
2 | 29341 | 54090 | 4295 | 6885 |
3 | 23427 | 40894 | 5197 | 6995 |
4 | 15345 | 25105 | 4700 | 6548 |
5 | 23123 | 40524 | 5884 | 9019 |
Please see the parameters retrieval request (or enumerable export parameters retrieval request for body_0.3 and metaperson_2.0 pipelines) to retrieve a list of available outfits.
Parameter Name | Pipeline / Pipeline Subtype | ||
---|---|---|---|
body_0.3 | metaperson_2.0 | ||
female, male | mobile | female, male | |
base set | Pro | ||
lowpoly set | Pro | ||
meta set | Pro | ||
metaperson set | Enterprise | ||
outfits_top set | Enterprise | ||
outfits_bottom set | Enterprise | ||
outfvits_shoes set | Enterprise |
For body_0.3 and metaperson_2.0 pipelines, outfits should be exported with separate export parameters (see export parameters section) and can be embedded into the main avatar mesh or downloaded separately. Please see the sample for exports API.
MetaPerson avatars (metaperson_2.0 pipeline) have a set of glasses available via the export parameters
Set of various glasses
Parameter Name | Pipeline / Pipeline Subtype |
---|---|
metaperson_2.0 | |
female, male | |
metaperson set | Enterprise |
Different blendshapes sets are available, depending on your use case: general animation, lip-sync, overall avatar shape modification, etc. Please consult each blendshapes set description for more information.
Set of 8 pairs of blendshapes to modify body shape
Set of blendshapes to modify the facial shape
Set of 2 blendshapes (face_shape and jaw_shape) to modify the facial shape. Please see the renders below:
deprecated
The basic set of 45 facial blendshapes
Set of 51 facial blendshapes. This set is compatible with Apple ARKit: https://developer.apple.com/documentation/arkit/creating_face-based_ar_experiences
Set of 15 visemes (AA, CH, EE, IH, OH, OU, TH, dd, ff, kk, nn, pp, rr, sil) and two additional blendshapes: frown and smile. This set is compatible with Oculus Lipsync which requires these 15 visemes. You can find more details here: https://developer.oculus.com/documentation/audiosdk/latest/concepts/book-audio-ovrlipsync/
Please find our guides on how to use visemes for lipsync here: https://docs.avatarsdk.com/unity-plugin/3.0.1/additional_samples.html
Parameter Name | Pipeline / Pipeline Subtype | |||||
---|---|---|---|---|---|---|
animated_face | head_1.2 | head_2.0 | body_0.3 | metaperson_2.0 | ||
base/legacy, indie/legacy_styled | base/legacy | base/mobile | bust/mobile, head/mobile | female, male, mobile | female, male | |
emotions | Enterprise | |||||
body_shape | Enterprise | |||||
face_modifications | Enterprise | |||||
face_modifications_2 | Pro | |||||
legacy_45 | Plus | Plus | ||||
mobile_51 | Plus | Pro | Pro | Enterprise | ||
visemes_14 | Enterprise | |||||
visemes_15 | Plus | Pro | Pro | Enterprise | ||
visemes_17 | Plus | Plus |
Please see the parameters retrieval request to retrieve a list of available blendshapes for a particular pipeline type and pipeline subtype for your account.
$ 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
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()
Avatar SDK is capable of providing some meta-information about computed avatars from source photos like a haircut, skin, eye color, etc. Please find the list of available meta-information parameters below:
As FitPerson avatars are based on the SMPL model that is created by the Max-Planck Institute, SMPL model coefficients applied to the resulting avatar may be included in model info.
Please note: to use these coefficients you will need an active SMPL license. Please find more information on the Meshcapade site.
Compute facial landmarks. Landmark coordinates are represented as a flat JSON array with X, Y, and Z float components sequence for each landmark, or NaN (for each component) if no landmark is detected
Please note: for base/legacy and indie/legacy_styled subtypes of animated_face pipeline, landmarks in the range [0-7] and [9-16] are not present (i.e. they are set to NaN).
Predict which haircut from the base and the facegen sets (base and plus sets for head_2.0) matches best to the submitted photo. haircut_name will contain the corresponding haircut identifier. May contain the special value absolutely_bald which represents the absence of a haircut. Please note: predicted haircut is independent of which haircuts were requested to compute with a particular avatar
The head_2.0 additionally estimates haircut correspondence and puts weights under the haircut_full_info key. Please see the sample model info below:
{ "haircut_full_info" : { "absolutely_bald" : 2.936517375928815e-06, "afro_short" : 0.0112605718895793, "balding" : 0.002860783133655787, "bob" : 0.02034652791917324, "bob_parted" : 0.03573336824774742, "burr_cut" : 0.009195085614919662, "classic_side_part" : 0.0149933909997344, "classic_tapper" : 0.009302150458097458, "cowlick" : 0.005376111250370741, "cowlick2" : 0.012983413413167, "crew_cut" : 0.01081948075443506, "crew_cut2" : 0.01268314570188522, "crew_cut3" : 0.01463177613914013, "curtained_hair" : 0.03242894262075424, "flattop" : 0.01193561963737011, "high_volume_brushed_up" : 0.01360709313303232, "long_afro" : 0.02262603491544724, "long_bob" : 0.04952326044440269, "long_crimped" : 0.05819306150078773, "long_disheveled" : 0.06030699983239174, "long_hair" : 0.06073638796806335, "long_hair2" : 0.075968898832798, "long_wavy" : 0.06359551101922989, "mid_length_ruffled" : 0.02399636991322041, "mid_length_straight" : 0.04574619233608246, "mid_length_wispy" : 0.03018877282738686, "ponytail_with_bangs" : 0.03226388990879059, "short_bob_asymmetrical_bangs" : 0.02550809271633625, "short_curls2" : 0.02223772928118706, "short_disheveled" : 0.01950234733521938, "short_simple" : 0.01544607523828745, "side_french_braid" : 0.04054473340511322, "straight_bob_bangs" : 0.03596006706357002, "very_long" : 0.06915491819381714, "wavy_shag" : 0.02055038698017597 }, "haircut_name" : "long_hair2", "pipeline" : "head_2.0", "pipeline_subtype" : "bust/mobile", "race" : "white", "race_confidence" : 0.9999996423721313, "races" : { "asian" : 2.615514413124159e-13, "black" : 4.136433915391535e-07, "white" : 0.9999996423721313 } }
Predict the person race from the submitted photo. Currently, three races are predicted (asian, black, and white) with certain confidence for each race in the range [0, 1] inclusive. The resulting information will include the most probable race with its confidence and a JSON Object with all races with their confidences. Please see the sample model info below:
{ "pipeline" : "head_2.0", "pipeline_subtype" : "bust/mobile", "race" : "white", "race_confidence" : 0.9999996423721313, "races" : { "asian" : 2.615514413124159e-13, "black" : 4.136433915391535e-07, "white" : 0.9999996423721313 } }
Parameter Name | Pipeline / Pipeline Subtype | |||||||
---|---|---|---|---|---|---|---|---|
animated_face | head_1.2 | head_2.0 | body_0.3 | metaperson_2.0 | ||||
base/legacy, indie/legacy_styled | base/legacy, base/mobile, base/static | bust/mobile | bust/static | head/mobile | female, male | mobile | female, male | |
age | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
body_shape_coeffs_10 | Pro | |||||||
eye_iris_color | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
eye_sclera_color | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
facial_landmarks_68 | Plus | Plus | Pro | Pro | Pro | |||
gender | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
hair_color | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise | |
lips_color | Plus | Plus | ||||||
predict_haircut | Plus | Pro | Pro | |||||
race | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
skin_color | Plus | Plus | Pro | Pro | Pro | Pro | Pro | Enterprise |
Please see the parameters retrieval request to retrieve a list of available model info flags for a particular pipeline type and pipeline subtype for your account.
$ 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" }
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)
Avatar SDK is aimed at producing recognizable photo-realistic avatars. However, there is demand for avatar modifications, leaving avatars recognizable, though. Please find available avatar modifications below.
Please note: all parameters for this category are key-value, and modify the original avatar respectively its description.
Add an eyelid shadow on top of the eye texture. Works only when parametric_eyes_texture is set. See the textures comparison below
Add a glare directly into the parametric eye texture. Works only when parametric_eyes_texture is set. Enabled by default. See the textures comparison below
By default, all avatars have the same neck mesh across all models. If the flag is set to true, the neck mesh will be modified to better match the submitted photo. Please note: x-axis rotation is also applied to match a head pose from the submitted photo
Factor to strengthen differences between the average model and a particular avatar. The valid values range is [0, +∞). The usable values range is model-dependent and usually should be lower than 5
Make the bottom of the model bust slightly curved. See the models comparison below
Attempt to make lighting more uniform. See the models comparison below
Recolor the eye iris directly on a model texture. Works only when parametric_eyes_texture is set. See textures comparison below for {"red": 0, "green": 255, "blue": 0} color
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
Resample generated haircut mesh to have specified face count. See the models comparison below for default and 256 faces count haircut (rendered without texture)
Recolor the generated haircut directly on a haircut texture. See models comparison below for {"red": 0, "green": 255, "blue": 0} color
Recolor lips directly on a model texture. See models comparison below for {"red": 0, "green": 255, "blue": 0} color
Replace the eye texture from the submitted photo with the generated one with sclera and iris colors to match the photo version. Please note: always set for the indie/legacy_styled subtype of the animated_face pipeline. See the models comparison below
Replace the eye texture from the submitted photo with generated one with sclera and iris colors to match the photo version. See the models comparison below.
Please note: add_glare and add_eyelid_shadow flags are ignored when this flag is set to true.
Please note: If both parametric_eyes_texture and parametric_eyes_texture_v2 are set to true, then parametric_eyes_texture_v2 is ignored.
Attempt to remove a smile on the submitted photo before the actual avatar computation starts. Currently detects and removes mostly open smiles (e.g. smiles with mouth open). The status of a smile removal may be obtained later from the model information JSON Object by the remove_smile key (see avatar model information retrieval request). Please find the model comparison below.
Please note: modifies original photo, thus avatars computed on the same source photo with and without this flag may appear slightly different.
Attempt to remove a stubble on the submitted photo before the actual avatar computation starts. The status of a stubble removal may be obtained later from the model information JSON Object by the remove_stubble key (see avatar model information retrieval request). Please find the model comparison below.
Please note: modifies the original photo, thus avatars computed on the same source photo with and without this flag may appear slightly different.
Attempt to remove glasses on the submitted photo before the actual avatar computation starts. The status of glasses removal may be obtained later from the model information JSON Object by remove_glasses key (see avatar model information retrieval request). Please find the model comparison below
Optimize texture layout to occupy less space. See the textures comparison below
Make the model texture look slightly cartoonish. Please note: replaces original avatar texture. See the models comparison below
Recolor teeth directly on a model texture. See the models comparison below for {"red": 0, "green": 255, "blue": 0} color
Parameter Name | Pipeline / Pipeline Subtype | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
animated_face | head_1.2 | head_2.0 | body_0.3 | metaperson_2.0 | ||||||
base/legacy | indie/legacy_styled | base/legacy | base/mobile | base/static | bust/mobile | bust/static | head/mobile | female, male, mobile | female, male | |
add_eyelid_shadow | Plus | Plus | Pro | Pro | ||||||
add_glare | Plus | Plus | 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 | always set | ||
eye_iris_color | Plus | Plus | Pro | Pro | Pro | |||||
eye_sclera_color | Plus | Plus | Pro | Pro | Pro | |||||
generated_haircut_faces_count | Pro | Pro | Pro | |||||||
generated_haircut_texture_size | Pro | Pro | Pro | |||||||
hair_color | Pro | Pro | Pro | |||||||
lips_color | Plus | Plus | Plus | Plus | ||||||
parametric_eyes_texture | always set | Plus | Pro | Pro | Pro | |||||
parametric_eyes_texture_v2 | Pro | Pro | ||||||||
remove_glasses | Plus | Plus | Plus | Pro | Pro | Pro | Pro | Enterprise | ||
remove_smile | Plus | Plus | Plus | Pro | Pro | Pro | Pro | Enterprise | ||
remove_stubble | Plus | Plus | Plus | Pro | Pro | Pro | Pro | Enterprise | ||
repack_texture | Plus | Plus | always set | |||||||
slightly_cartoonish_texture | Plus | Plus | Plus | Pro | Pro | Pro | Pro | |||
teeth_color | Plus | Plus | Plus | Plus | Pro | Pro | Pro | |||
texture_size | Pro | Pro | Pro |
Please see the parameters retrieval request to retrieve a list of available avatar modification parameters for a particular pipeline type and pipeline subtype for your account.
$ 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"
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()
Similar to avatar modification parameters, see the description for that parameters category.
Please note: all parameters for this category are key-value, and modify the original avatar respectively its description.
Factor to modify avatar mesh to look more cartoon-like. The valid values range is [0, +∞). The usable values range is model-dependent and usually should be lower than 1
Factor to modify avatar mesh to look more cartoon-like. The valid values range is [0, +∞). The usable values range is model-dependent and usually should be lower than 1
Parameter Name | Pipeline / Pipeline Subtype | |||
---|---|---|---|---|
animated_face | head_1.2 | head_2.0 | body_0.3 | |
indie/legacy_styled | base/mobile | head/mobile | female, male, mobile | |
cartoonish_v0.3 | Plus | |||
cartoonish_v1.0 | Plus | Pro | Pro |
Please see the parameters retrieval request to retrieve a list of available shape modifications parameters for a particular pipeline type and pipeline subtype for your account.
$ 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"
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()
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.
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.
Parameter Name | Pipeline / Pipeline Subtype |
---|---|
body_0.3 | |
mobile | |
chest | Pro |
gender | Pro |
height | Pro |
hips | Pro |
waist | Pro |
weight | Pro |
$ curl -H "Authorization: Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu" \ -H "X-PlayerUID: 9418fd52-baef-401c-a2b3-e6fe16d93596" \ -X POST \ "https://api.avatarsdk.com/avatars/" \ -F "pipeline=body_0.3" \ -F "pipeline_subtype=mobile" \ -F "name=modifications test" \ -F "parameters={\"body_shape\": {\"plus\": {\"gender\": \"male\", \"height\": 180, \"weight\": 85}}}" \ -F "photo=@photo.jpg"
import json, requests, io, zipfile headers = { 'Authorization': 'Bearer F88pQWs8hoPzbeCg4xTGifDxxs1eKu', 'X-PlayerUID': '9418fd52-baef-401c-a2b3-e6fe16d93596', } data = { 'pipeline': 'body_0.3', 'pipeline_subtype': '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()
You could request to compute additional textures along with the default one, which is always computed. See avatar textures to find out how to retrieve additional textures.
Uniformly colored texture
Mask in PNG format
Metalness map in JPG format
Roughness map in JPG format
Slightly smoother than the original texture
Original texture with a smoothed area of eyelashes
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 the parameters retrieval request to retrieve a list of available additional textures for a particular pipeline type and pipeline subtype for your account.
$ 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
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)
Avatar's export parameters contain a set of flags and parameters to specify what resulting avatar downloadable data should include: 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, body_0.3, and metaperson_2.0 pipelines.
The general format for export parameters of head_1.2, head_2.0, body_0.3 pipelines is the following:
{ "flag": value, "category": { "list": [values], "flag": value } }
The general format for export parameters of the metaperson_2.0 pipeline is the following:
{ "flag": value, "category": { "textures": { "list": [values], "flag": value }, "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 (unless stated otherwise). 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 the pipeline and the 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.
For the metaperson_2.0 pipeline, top-level and category-level sections may contain an optional textures section. Please look at the enumerable export parameters retrieval request to retrieve a list of available textures for each particular category. Texture lists, flags, and the section itself are also inherited by the categories from the top-level value and may be overwritten at the category level. To export all available textures, you can specify all of them in the top-level textures section, non-existent textures for the particular avatar part will not trigger an error and will be skipped on export computation.
All flags and values are optional and replaced by default values if not specified explicitly. Default export parameters for head_1.2, head_2.0 and body_0.3 pipelines are the following:
{ "format": "gltf", "embed" : true, "pointclouds" : false, "additional_textures" : [], "embed_textures": false, "texture_size" : null, // i.e. maximum available "template": "", // i.e. default template "lod": 0, // 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 } }
Default export parameters for the metaperson_2.0 pipeline are the following:
{ "format": "gltf", "embed": true, "lod": "LOD1", "split_vertices": false, "export_quads": false, "finalize": false, "apply_visibility_masks": true, "make_public": false, "make_public_direct": false, "textures": { "list": [], "profile": "2K.png", "embed": false }, "avatar": { "list": [ "AvatarBody", "AvatarLeftCornea", "AvatarRightCornea", "AvatarLeftEyeball", "AvatarRightEyeball", "AvatarEyelashes", "AvatarHead", "AvatarTeethLower", "AvatarTeethUpper" ], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "apply_visibility_masks": true, "textures": { "list": [ "Color", "GltfMetallicRoughness", "Normal" ], "embed": null // i.e. top-level value } }, "haircuts": { "list": [], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "textures": null, // i.e. top-level value "color": null // i.e. no recolor }, "outfits": { "list": [], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "apply_visibility_masks": true, "textures": null // i.e. top-level value }, "outfits_top": { "list": [], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "apply_visibility_masks": true, "textures": null // i.e. top-level value }, "outfits_bottom": { "list": [], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "apply_visibility_masks": true, "textures": null // i.e. top-level value }, "outfits_shoes": { "list": [], "format": null, // i.e. top-level value "embed": null, // i.e. top-level value "lod": null, // i.e. top-level value "apply_visibility_masks": true, "textures": null // i.e. top-level value }, "blendshapes": { "list": [], "values": null, // no blendshapes deformations "embed": true // i.e. top-level value } }
See also frequently asked questions on export parameters usage here: FAQ
List of textures to export besides the default diffuse model texture. Available values are:
For the outfits section body_visibility_mask is also available (see outfits section for visibility mask information).
If texture supports recoloring, this flag specifies the base color for the recoloring process
If the avatar format (i.e. top-level format) supports sub-meshes/textures (i.e. fbx, gltf, glb) this flag indicates whether to embed this particular category of meshes/textures into the avatar or store these resources as separate files. If avatar format does not support sub-meshes/textures - the flag is set to false and category meshes/textures are saved as separate files
Please note: the value of the top-level flag is not propagated to the textures section for the metaperson_2.0 pipeline and must be specified explicitly to embed textures. See also FAQ
If the format supports texture embedding (i.e. fbx or glb), this flag indicates whether to embed textures or store them as separate files. If avatar format does not support texture embedding - the flag is set to false and textures are saved as separate files
Please note: this flag is not available for metaperson_2.0 pipeline. To embed textures in this pipeline, please use the embed flag in the textures section. See also FAQ
Produce a final avatar mesh:
See also FAQ
Please note: it is your responsibility to specify only one conflicting avatar part at a time: i.e. only one haircut/outfit/etc.
Make avatar model export available through a direct link without API authentication. Valid only for models with embedded sub-meshes and textures, as only the avatar.zip archive is processed. The public link will be available through the public_file field of avatar export like in the example below:
{ "avatar_code": "3135741b-0a6f-45df-a71e-fdca65ee9dcd", "code": "cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570", "comment": "finalize", "created_on": "2024-08-13T12:16:14.499757Z", "files": [ { "category": null, "file": "https://api.avatarsdk.com/avatars/3135741b-0a6f-45df-a71e-fdca65ee9dcd/exports/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/files/avatar/file/", "identity": "avatar", "static_files": [] } ], /* public url */ "public_file": "https://metaperson.avatarsdk.com/public/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/avatar.zip", "status": "Completed", "url": "https://api.avatarsdk.com/avatars/3135741b-0a6f-45df-a71e-fdca65ee9dcd/exports/cd1f8651-bc61-4ffb-93c2-6c8b5c3f7570/" }
See also FAQ
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 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
Resize texture to the specified size. The avatar texture size is 4096x2048 px. Most asset textures are 4096x4096 px for outfits and 2048x2048 px for haircuts, but size varies between assets. Please check the original texture size before setting a custom value as setting it greater than the original one will not result in improved texture quality.
Please note: if texture size is also set in avatar modification parameters - then texture is resized according to avatar modifications first, and then according to export parameters.
Avatar blendshapes deformations factors in the form of
{ "blendshape_set": {"blendshape_name": value, ...}, ... }
Please find available blendshape names and set names in the blendshapes parameters section
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.
Some export files may contain files, that are not modified from export to export: e.g. normals map or default, non-recolored haircut textures. These files are explicitly listed within each export file. They may be downloaded only once and cached on the client side for other export files to save bandwidth and minimize export download size. Please note: they still have to be downloaded separately from the export file for the first time as they are not included in the export file archive.
Please see the avatar exports list request description to find information about static files' retrieval.
While the shape and texture are different for each particular avatar face, there are still a lot of other resources that do not change and may be reused within avatars with minimal or no modification at all: e.g. artificial haircut textures, outfits, etc. If your application generates a lot of avatars, it may be convenient to download these static resources once and reuse them for future avatars saving bandwidth. Furthermore, you can start these resources download in advance, even before the avatar computation is completed, minimizing the time until the avatar is ready to be displayed.
Please see the static resources list request to find more information on how to retrieve available static resources and how to retrieve the resources themselves.
[1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11) Color is represented as a JSON object with red, green, and blue keys and [0, 255] values inclusive for corresponding color channels. E.g. {"red": 222, "green": 173, "blue": 190} |
[2] | (1, 2, 3) Size is represented as a JSON object with width and height keys and positive integer values. E.g. {"width": 256, "height": 256} |
Player model DTO [*]:
{ // Absolute URL to this DTO "url": string, // Player unique identifier (PlayerUID) "code": string, // ISO 8601 datetime "created_on": string, // May be used to contain arbitrary information for your taste "comment": string }
[*] | DTO is an acronym for Data Transfer Object |
[ { "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":"" }, ... ]
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", ... ] }, ... }
Retrieve all available or default parameters for specified pipeline and default pipeline subtype. Use filters to retrieve parameters for the non-default pipeline subtype. The response is one key-value pair with pipeline_subtype as a key and parameters as a value.
Parameters may be just copy-pasted as-is (or partially) into the parameters field of create avatar request parameters. The only exception is the avatar_modifications parameters category: this category contains key-value parameters. See the avatar modification parameters section for details.
Please see the example response below (a little bit shortened for the sake of simplicity):
{ "base/legacy": { "blendshapes": { "base": [ "legacy_45", "visemes_17" ] }, "haircuts": { "base": [ "female_NewSea_J086f", "female_NewSea_J096f", "female_NewSea_J123f", "male_NewSea_J003m", "male_NewSea_J082m", "male_makehuman_short02" ], "facegen": [ "facegen_afro", "facegen_balding", ... "facegen_wavy_shag" ] } } }
Enumerable export parameters DTO for head_1.2, head_2.0 and body_0.3 pipelines:
{ // export parameters category "category": [ // list of enumerable parameters values ], ... }
Enumerable export parameters DTO for metaperson_2.0 pipeline:
{ // export parameters category "category": { "list": [ // list of enumerable parameters values ], "textures": [ // list of textures available for the category values ] } ... }
/export_parameters/available/{pipeline}/
Retrieve all available enumerable export parameters for specified pipeline and a pipeline subtype. Use filters to retrieve parameters for the non-default pipeline subtype. The response is a JSON object of available enumerable values for each export parameters category.
Please see the example response below for head_1.2, head_2.0, and body_0.3 pipelines (a little bit shortened for the sake of simplicity):
{ "blendshapes": [ "mobile_51", "visemes_15" ], "haircuts": [ "generated", ... "wavy_bob" ] }
Please see the example response below for the metaperson_2.0 pipeline (a little bit shortened for the sake of simplicity):
{ "avatar": { "list": [ "AvatarBody", "AvatarHead", ... ], "textures": [ "Color", "GltfMetallicRoughness", "Normal", "Roughness", "UnityMetallicSmoothness" ] }, "haircuts": { "list": [ "HaircutGenerated", "Haircut0", ... ], "textures": [ "Color", "Normal", ... ] } }
Static resources DTO:
{ // Pipeline subtype. E.g. 'female', 'male', etc. "pipeline_subtype": { // Asset category. E.g. 'avatar', 'haircuts', etc. "category": { // Asset name. E.g. 'AvatarHead', 'Haircut1', etc. "asset": { // Asset LOD. E.g. 'LOD1', 'LOD2', etc. "lod": { // Asset textures "textures": { // Texture Profile. E.g., '1K.jpg', '1K.png', etc. "texture_profile": { // Texture Profile Variant. E.g., 'base', 'stripes', etc. Mostly for outfits "profile_variant": { // Key: texture name. E.g. 'Color', 'Normal', etc. // Value: absolute URL to the corresponding texture file "texture_name": URL, }, }, }, ... }, ... }, ... }, ... }, ... }
Retrieve a JSON object with all available static resources for the specified pipeline. Please find the JSON object format in the static resources DTO section above.
The size of the resulting JSON may be reduced by applying request filters (i.e. retrieve only particular LODs and formats). Please see the filters section below.
To retrieve the resource itself, follow the URL in the corresponding asset section.
Please see the example response below (shortened for the sake of simplicity):
{ "female": { "avatar": { "AvatarHead": { "LOD1": { "textures": { "2K.jpg": { "base": { "Color": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Color_2K.jpg", "Normal": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Normal0_2K.jpg", "GltfMetallicRoughness": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_GltfMetallicRoughness_2K.jpg", "Roughness": "https://api.avatarsdk.com/static_resources/metaperson_2.0/textures/avatar/AvatarHeadFemale/AvatarHeadFemale_Roughness_2K.jpg" } } } }, ... }
Please note: all filters are case-sensitive.
Multiple values may be specified via , (comma) sign, e.g. ?lod=LOD1,LOD2
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, // Optional more verbose description of status field above. Mostly set // for `Failed` status "status_verbose": {"code": int, "message": string}, // Current progress of avatar status. In rage [0:100] "progress": integer, // Avatar name "name": string, // Pipeline used to calculate avatar "pipeline": string, // Avatar description "description": string, // ISO 8601 datetime "created_on": string, // ISO 8601 last change datetime. May be `null` if it hasn't changed yet since the creation "ctime": string, // Absolute URL to retrieve zip with a mesh of avatar // NOTE: not suitable for pipelines utilizing export parameters, use exports // link below "mesh": string, // Absolute URL to retrieve the jpeg texture of the avatar // NOTE: not suitable for pipelines utilizing export parameters, use exports // link below "texture": string, // Absolute URL to retrieve Avatar source image thumbnail "thumbnail": string, // Absolute URL to retrieve a list of available haircuts for this avatar model // NOTE: not suitable for pipelines utilizing export parameters, use the exports link below "haircuts": string, // Absolute URL to retrieve zip archive of available blendshapes // for this avatar model // NOTE: not suitable for pipelines utilizing export parameters, use exports // link below "blendshapes": string, // Absolute URL to retrieve JSON object with this avatar meta-information "model_info": string, // Absolute URL to retrieve a list of available avatar exports for this avatar model "exports": string }
See the avatar blendshapes for more information about blendshapes retrieval
[ { "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/" }, ... ]
Create a new avatar calculation task. Available in developer and client access modes. After POSTing a request, the avatar photo for the calculation is uploaded to the calculation backend (state Uploading), then Queued until a free calculation backend is found, then Computing, and finally Completed.
In some cases, the calculation task may be Failed due to a bad (blurry/dark/etc.) photo being submitted or for some other reasons. In rare cases task may be Timed out - calculation took too long time.
It is your responsibility to poll the avatar calculation task for progress (status and progress fields of avatar DTO). Access to the URL fields of the incomplete avatar will not succeed.
Accepts multipart/form-data requests with the following fields:
name - new avatar name
description - new avatar description
photo - new avatar source photo. Either a photo or a selfie must be provided. Error is returned if none or both are provided
selfie - selfie code. Please see the selfies section to learn more about selfies. Either a selfie or a photo must be provided. Error is returned if none or both are provided. Error is returned if the selfie file has not uploaded yet by the end-user
pipeline - an optional field to specify which pipeline to use for new avatar generation. Please see the the available pipelines for the list of possible field values. The assumed value is animated_face if the form field is not provided
pipeline_subtype - modification of pipeline. Please see available pipelines for the list of possible field values
parameters - specific parameters to compute for the submitted avatar. See parameters DTO for this field format. If no value is submitted - it is replaced with default parameters for the specified pipeline and (optionally) pipeline subtype. See the parameters retrieval request to find out default/available parameters for pipeline type/subtype pairs. If no parameters are required to compute the avatar - submit an empty JSON object: {}
export_parameters - parameters to specify what resulting avatar downloadable data should include: like model format, set of textures, blendshapes, whether to embed all these assets into the one model or save as separate files, etc. Please see the export parameters section to find out more.
Please note: if this section is empty for head_1.2 and head_2.0 pipelines - no avatar exports will be created.
export_comment - avatar export comment. An arbitrary string, note to self, etc.
Accepts multipart/form-data requests with the following fields:
Retrieve the number of avatars created (created field), the number of free avatars left (i.e. included in your billing plan, prepaid field), and the number of avatars to be paid (to_pay field) in the current billing period.
The time frame to count avatars may be specified with since and until filters. In this case, only the number of created avatars is returned.
Please see the example response below:
{ "created": 8192, "prepaid": 0, "to_pay": 2192 }
Represents per-avatar haircuts morphed to fit the particular avatar model geometry.
The same haircut meshes are interchangeable between different avatars if the corresponding pointcloud is applied. E.g. you could store mesh from haircut1 of avatar1, then download only pointclouds for haircut1 of avatar2, avatar3, etc. and replace pointcloud in the previously-stored mesh. This way you could save customer's network traffic.
Per-Avatar haircut DTO:
{ // Identifier of haircut "identity": string, // Haircut formal gender. One of [male, female, unisex] "gender": string, // Absolute URL to a preview of specified haircut "preview": string, // Absolute URL to this haircut "url": string, // Absolute URL to haircut png texture "texture": string, // Absolute URL to avatar model "model": string, // Absolute URL to per-avatar haircut point cloud zip "pointcloud": string, // Absolute URL to per-avatar haircut mesh zip "mesh": string }
Retrieve a list of per-avatar haircuts. The particular avatar is identified by the code URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID. Please see the avatar haircut DTO for the response format description.
Please note: you should not use this method to retrieve a list of avatar haircuts for avatars created with export parameters: avatar exports list request should be used instead.
Please see the example response below:
[ { "identity":"female_NewSea_J086f", "gender":"female", "preview":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/preview/", "url":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/", "texture":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/texture/", "model":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/", "pointcloud":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/pointcloud/", "mesh":"https://api.avatarsdk.com/avatars/b63f9737-8594-460a-99a4-74e60b042bd4/haircuts/female_NewSea_J086f/mesh/" }, ... ]
Retrieve a particular instance of per-avatar haircut. Avatar is identified by the code URL part, and haircut - by the identity URL part. Available in developer and client access modes. In client access mode restricted to avatars created by specified PlayerUID. Please see the avatar haircut DTO for the response object description.
Please note: you should not use this method to retrieve avatar haircuts for avatars created with export parameters: the avatar export retrieval request should be used instead.
Retrieve the zip archive with avatar mesh.
Please note: you should not use this method to retrieve avatar mesh for avatars created with export parameters: the avatar export retrieval request should be used instead.
Avatars computed with animated_face, head_1.2, and head_2.0 (head/mobile and bust/mobile subtypes only) pipelines support different levels of mesh details (LOD). Specify the desired LOD on mesh retrieval as a request parameter. Please find more information on mesh properties in the LOD table for each particular pipeline description in the available pipelines section.
Base texture sizes:
animated_face | head_1.2 | head_2.0 | body_0.3 | |
---|---|---|---|---|
base/static | base/legacy, base/mobile | |||
2048x2048 | 1024x1024 | 4096x2048 [3] | 2048x2048 [4] | 4096x2048 [4] |
[3] | Texture size is 2048x2048 if the repack_texture flag is set. Please see the 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, }
Additional textures (along with a default one) can be requested to compute for a particular avatar. See the additional textures parameters to find out which textures can be requested.
Use this request to retrieve a list of available textures for the particular avatar. The particular avatar is identified by the code URL part.
Please note: you should not use this method to retrieve a list of avatar textures for avatars created with export parameters: avatar exports list request should be used instead.
Please see the example response below:
[ { "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/slightly_cartoonish_texture/file/", "identity": "slightly_cartoonish_texture" }, { "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/model_cartoonish/file/", "identity": "model_cartoonish" }, { "file": "https://api.avatarsdk.com/avatars/33639df4-7593-44ab-a793-5e61a82bc81b/textures/model/file/", "identity": "model" } ]
Retrieve a particular texture file identified by its identity for a particular avatar identified by code. Texture format may vary (i.e. JPEG, PNG, etc.), thus consult Content-Type HTTP Response Header for particular texture format.
Please note: you should not use this method to retrieve an avatar texture for avatars created with export parameters: avatar exports list request should be used instead.
Retrieve the zip archive with all available blendshapes for the specific avatar. If no blendshapes are available - the request will end with HTTP 204 NO CONTENT response.
Please note: you should not use this method to retrieve avatar blendshapes for avatars created with export parameters: the avatar export retrieval request should be used instead.
By default, blendshapes are delivered in ply files packed into a zip archive. Blendshapes format may be changed to one fbx file also packed into a zip archive.
Avatars computed with animated_face, head_1.2, and head_2.0 (head/mobile subtype only) pipelines support different levels of blendshapes details (LOD). For more information on LOD details see avatar mesh retrieve request. Specify the desired LOD on blendshapes retrieval as a request parameter.
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 } }
For some applications, it may be the case, that the camera or selfie photo is not available within the same device (e.g. an application on a desktop computer without an attached web camera). At the same time, almost everyone has cameras or selfies on his/her mobile phone, but it may be inconvenient to transfer these photos to the device with the application.
The solution is to create a selfie upload page, visit it within the mobile device, and upload a new or existing selfie photo. For end-user convenience, the QR code with the upload page URL is also available. After uploading the photo, the application could download the photo and continue its workflow of avatar creation. It is also possible to avoid the photo download step by passing the selfie code into the avatar creation request directly.
Please note: only one photo can be uploaded per selfie upload page. To upload a new photo, a new selfie upload page must be created.
Selfie model DTO:
{ // Selfie code "code": string, // ISO 8601 datetime after which, the selfie will be unavailable (24 hours currently) "expires": string, // Absolute URL to selfie file "file_url": string, // Absolute URL to QR code file with selfie upload page URL "upload_page_qr": string, // Absolute URL to selfie upload page "upload_page_url": string, // Flag indicates whether the upload page visited "upload_page_visited": boolean, // Absolute URL to this DTO "url": string }
Avatar export DTO:
{ // Avatar identifier "avatar_code": string, // Avatar export identifier "code": string, // Avatar export comment, may be `null` if not present "comment": 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 }
[ { "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/" } ]
Retrieve a particular Avatar export file. Avatar is identified by the code URL part, Avatar export is identified by the export_code URL part, and the export file is identified by the export_file URL part. Please see the avatar export DTO to see where to find each URL part.
Please note: all export files and their static files must be downloaded to retrieve full Avatar export.
Please see also note on static export files. Static file cache key may be constructed by concatenating Avatar export file category, identity, and static filename. E.g., for the texture of the afro haircut from the example above, the cache key may be: haircuts/afro/texture.png
Please note: for the metaperson_2.0 pipeline, static export files are static resources essentially, thus cache key construction rules are not applicable. Use the full URL as a cache key instead.
Create a subsequent avatar export on already Completed avatar. Please see the avatar export DTO section for the response format. May be useful to create finalized avatar export with different list of assets (see the finalize export flag).
After POSTing a request, the avatar export task is created and being transitioned through the following states: Queued, Computing, Completed, Failed. It is your responsibility to poll the avatar export task for the progress.
Accepts multipart/form-data requests with the following fields: