Contents
This page contains a step-by-step tutorial on how to retrieve OAuth Bearer token, create a Player, retrieve available Avatar creation parameters, create a full body avatar with outfits from a photo and download avatar mesh, blendshapes, outfits, and haircut in fbx or gltf formats and its textures using the curl command-line utility.
To obtain curl utility for Windows, please visit the following page: https://curl.haxx.se/windows/. Please consult your Linux/macOS distributive packaging system help to install curl utility.
Please note that code samples syntax is different for Windows and Linux/macOS platforms, thus see the corresponding sample section for your platform by clicking on the platform title.
Go to https://accounts.avatarsdk.com/developer/ (create an application if you have no application yet), copy App Client ID and App Client Secret from Client Access application to the corresponding variables. Please make sure you have set Authorization Grant to Client credentials. Set the TOKEN variable to the access_token value after successful authorization. Please note, that token will expire in 36000 seconds and you will need to run the authorization procedure again.
SET "CLIENT_ID=iCM5o..." SET "CLIENT_SECRET=S8TM5..." curl -X POST --user "%CLIENT_ID%:%CLIENT_SECRET%" ^ "https://api.avatarsdk.com/o/token/" ^ -F "grant_type=client_credentials" { "access_token": "PAvD64lbikgVA0GzxgKV2ZhLnPbZ8P", "token_type": "Bearer", "expires_in": 36000, "scope": "read write" } SET "TOKEN=PAvD64lbikgVA0GzxgKV2ZhLnPbZ8P"
CLIENT_ID="iCM5o..." CLIENT_SECRET="S8TM5..." curl -X POST --user "$CLIENT_ID:$CLIENT_SECRET" \ "https://api.avatarsdk.com/o/token/" \ -F "grant_type=client_credentials" { "access_token": "PAvD64lbikgVA0GzxgKV2ZhLnPbZ8P", "token_type": "Bearer", "expires_in": 36000, "scope": "read write" } TOKEN="PAvD64lbikgVA0GzxgKV2ZhLnPbZ8P"
Create a Player ID that will own all future avatars. Please note, that the Player ID does not expire.
curl -H "Authorization: Bearer %TOKEN%" ^ -X POST ^ "https://api.avatarsdk.com/players/" ^ -F "comment=curl sample" { "url": "https://api.avatarsdk.com/players/16322807-89e3-4223-a83c-1d6afa8abd11/", "code": "16322807-89e3-4223-a83c-1d6afa8abd11", "created_on": "2020-04-14T07:09:55.976235Z", "comment": "curl sample" } SET "PLAYER=16322807-89e3-4223-a83c-1d6afa8abd11"
curl -H "Authorization: Bearer $TOKEN" \ -X POST \ "https://api.avatarsdk.com/players/" \ -F "comment=curl sample" { "url": "https://api.avatarsdk.com/players/16322807-89e3-4223-a83c-1d6afa8abd11/", "code": "16322807-89e3-4223-a83c-1d6afa8abd11", "created_on": "2020-04-14T07:09:55.976235Z", "comment": "curl sample" } PLAYER="16322807-89e3-4223-a83c-1d6afa8abd11"
Query available parameters
Query all available parameters for body/mobile subtype of body_0.2 pipeline. Please note, that this request is useful during parameters discovery and should be omitted during normal application workflow once you figure out which parameters fit you best.
curl -H "Authorization: Bearer %TOKEN%" ^ -X GET ^ "https://api.avatarsdk.com/parameters/available/body_0.2/?pipeline_subtype=body/mobile" { "body/mobile": { "avatar_modifications": { "plus": [ "eye_iris_color", "eye_sclera_color", "add_glare", "add_eyelid_shadow", "parametric_eyes_texture", "hair_color", "teeth_color", "texture_size", "generated_haircut_texture_size", "generated_haircut_faces_count", "remove_smile", "remove_glasses", "enhance_lighting" ] }, "blendshapes": { "base": [ "mobile_51", "visemes_15" ] }, "body_shape": { "plus": [ "gender", "height", "weight", "chest", "waist", "hips" ] }, "haircuts": { "base": [ "generated", "long_disheveled", "long_wavy", "mid_length_straight", "ponytail_with_bangs", "short_disheveled", "short_simple" ], "plus": [ "afro", "afro_short", "balding", "balding2", "bob", "bob_parted", "burr_cut", "classic_side_part", "classic_tapper", "cowlick", "cowlick2", "crew_cut", "crew_cut2", "crew_cut3", "cuckoo_nest", "curtained_hair", "flattop", "high_volume_brushed_up", "long_afro", "long_bob", "long_dreads", "long_hair", "long_hair2", "man_bun", "man_bun2", "mid_length_curved", "ponytail", "rasta", "short_bob_asymmetrical_bangs", "short_curls", "short_curls2", "short_parted", "short_slick", "side_french_braid", "straight_bob_bangs", "top_knot", "wavy_shag", "corkscrew_curls", "long_crimped", "mid_length_ruffled", "mid_length_straight2", "mid_length_wispy", "roman", "shoulder_length", "very_long", "wavy_bob" ] }, "model_info": { "plus": [ "gender", "race", "age", "hair_color", "skin_color", "eye_sclera_color", "eye_iris_color", "facial_landmarks_68" ] }, "outfits": { "base": [ "outfit_0", "outfit_1", "outfit_2", "outfit_3", "outfit_4", "outfit_5" ] } } }
curl -H "Authorization: Bearer $TOKEN" \ -X GET \ "https://api.avatarsdk.com/parameters/available/body_0.2/?pipeline_subtype=body/mobile" { "body/mobile": { "avatar_modifications": { "plus": [ "eye_iris_color", "eye_sclera_color", "add_glare", "add_eyelid_shadow", "parametric_eyes_texture", "hair_color", "teeth_color", "texture_size", "generated_haircut_texture_size", "generated_haircut_faces_count", "remove_smile", "remove_glasses", "enhance_lighting" ] }, "blendshapes": { "base": [ "mobile_51", "visemes_15" ] }, "body_shape": { "plus": [ "gender", "height", "weight", "chest", "waist", "hips" ] }, "haircuts": { "base": [ "generated", "long_disheveled", "long_wavy", "mid_length_straight", "ponytail_with_bangs", "short_disheveled", "short_simple" ], "plus": [ "afro", "afro_short", "balding", "balding2", "bob", "bob_parted", "burr_cut", "classic_side_part", "classic_tapper", "cowlick", "cowlick2", "crew_cut", "crew_cut2", "crew_cut3", "cuckoo_nest", "curtained_hair", "flattop", "high_volume_brushed_up", "long_afro", "long_bob", "long_dreads", "long_hair", "long_hair2", "man_bun", "man_bun2", "mid_length_curved", "ponytail", "rasta", "short_bob_asymmetrical_bangs", "short_curls", "short_curls2", "short_parted", "short_slick", "side_french_braid", "straight_bob_bangs", "top_knot", "wavy_shag", "corkscrew_curls", "long_crimped", "mid_length_ruffled", "mid_length_straight2", "mid_length_wispy", "roman", "shoulder_length", "very_long", "wavy_bob" ] }, "model_info": { "plus": [ "gender", "race", "age", "hair_color", "skin_color", "eye_sclera_color", "eye_iris_color", "facial_landmarks_68" ] }, "outfits": { "base": [ "outfit_0", "outfit_1", "outfit_2", "outfit_3", "outfit_4", "outfit_5" ] } } }
We will use the following parameters for our avatar: avatar with two sets of blendshapes, generated haircut, and two outfit sets. The resulting parameters are:
{ "body_shape": { "plus": { "height": 180, "weight": 85, "chest": 106, "waist": 81, "hips": 91 } }, "blendshapes": { "base": ["mobile_51", "visemes_15"] }, "haircuts": { "base": ["generated"] }, "outfits": { "base": ["outfit_0", "outfit_1"] } }
Please note: The dimensions for height, chest, waist, and hips are in centimeters, weight is in kilograms.
Create an avatar with the parameters above and a photo.jpg photo from the current directory (adjust path if necessary):
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X POST "https://api.avatarsdk.com/avatars/" ^ -F "name=test from curl sample" ^ -F "pipeline=body_0.2" ^ -F "pipeline_subtype=body/mobile" ^ -F "parameters={\"body_shape\": {\"plus\": {\"height\": 180, \"weight\": 85, \"chest\": 106, \"waist\": 81, \"hips\": 91}}, \"blendshapes\": {\"base\": [\"mobile_51\", \"visemes_15\"]}, \"haircuts\": {\"base\": [\"generated\"]}, \"outfits\": {\"base\": [\"outfit_0\", \"outfit_1\"]}}" ^ -F "photo=@photo.jpg" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Uploading", "progress": 0, "created_on": "2020-04-14T07:44:12.554903Z", "name": "test from curl sample", "description": "" } SET "AVATAR=0c60a909-2e5b-4c49-9365-368b4cf78d43"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X POST "https://api.avatarsdk.com/avatars/" \ -F "name=test from curl sample" \ -F "pipeline=body_0.2" \ -F "pipeline_subtype=body/mobile" \ -F "parameters={\"body_shape\": {\"plus\": {\"height\": 180, \"weight\": 85, \"chest\": 106, \"waist\": 81, \"hips\": 91}}, \"blendshapes\": {\"base\": [\"mobile_51\", \"visemes_15\"]}, \"haircuts\": {\"base\": [\"generated\"]}, \"outfits\": {\"base\": [\"outfit_0\", \"outfit_1\"]}}" \ -F "photo=@photo.jpg" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Uploading", "progress": 0, "created_on": "2020-04-14T07:44:12.554903Z", "name": "test from curl sample", "description": "" } AVATAR="0c60a909-2e5b-4c49-9365-368b4cf78d43"
Once the photo is uploaded, avatar computation starts. Request the avatar status periodically (once per 5 seconds should be enough) to check avatar computation status and progress:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Computing", "progress": 0, "name": "test from curl sample", "description": "", "created_on": "2020-04-14T07:44:12.554903Z", "ctime": null, "model_info": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/model_info/", "thumbnail": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/thumbnail/", "mesh": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/mesh/", "texture": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/texture/", "preview": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/preview/", "haircuts": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/haircuts/", "blendshapes": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/blendshapes/", "pipeline": null, "pipeline_subtype": null }
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Computing", "progress": 0, "name": "test from curl sample", "description": "", "created_on": "2020-04-14T07:44:12.554903Z", "ctime": null, "model_info": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/model_info/", "thumbnail": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/thumbnail/", "mesh": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/mesh/", "texture": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/texture/", "preview": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/preview/", "haircuts": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/haircuts/", "blendshapes": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/blendshapes/", "pipeline": null, "pipeline_subtype": null }
Once the avatar is ready, its status is set to Completed and progress to 100:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Completed", "progress": 100, "name": "test from curl sample", "description": "", "created_on": "2020-04-14T07:44:12.554903Z", "ctime": null, "model_info": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/model_info/", "thumbnail": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/thumbnail/", "mesh": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/mesh/", "texture": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/texture/", "preview": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/preview/", "haircuts": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/haircuts/", "blendshapes": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/blendshapes/", "pipeline": "body_0.2", "pipeline_subtype": "body/mobile" }
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/" { "url": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/", "code": "0c60a909-2e5b-4c49-9365-368b4cf78d43", "status": "Completed", "progress": 100, "name": "test from curl sample", "description": "", "created_on": "2020-04-14T07:44:12.554903Z", "ctime": null, "model_info": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/model_info/", "thumbnail": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/thumbnail/", "mesh": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/mesh/", "texture": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/texture/", "preview": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/preview/", "haircuts": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/haircuts/", "blendshapes": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/blendshapes/", "pipeline": "body_0.2", "pipeline_subtype": "body/mobile" }
Once the avatar is ready, download the model zip archive. Replace fbx with gltf if you need an avatar in gltf format:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/mesh/?fmt=fbx" ^ -o "model.zip"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/mesh/?fmt=fbx" \ -o "model.zip"
Archive content is the following (for the avatar in fbx format):
model.fbx outfit_0.png outfit_0_metallic_map.png outfit_0_normal_map.png outfit_0_roughness_map.png outfit_0_body_visibility_mask.png outfit_1.png outfit_1_metallic_map.png outfit_1_normal_map.png outfit_1_roughness_map.png outfit_1_body_visibility_mask.png
Avatar texture and haircuts texture should be downloaded via the separate requests:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/texture/" ^ -o "model.jpg" curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/haircuts/generated/texture/" ^ -o "generated.png"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/texture/" \ -o "model.jpg" curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/haircuts/generated/texture/" \ -o "generated.png"