This page contains a step-by-step tutorial on how to retrieve OAuth Bearer token, create a Player, retrieve available Avatar creation parameters, create an avatar from a photo and download its model files along with extra Avatar meta-information 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 for 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 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-01-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-01-14T07:09:55.976235Z", "comment": "curl sample" } PLAYER="16322807-89e3-4223-a83c-1d6afa8abd11"
Query all available parameters for base/legacy subtype of animated_face 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/animated_face/?pipeline_subtype=base/legacy" { "base/legacy": { "model_info": { "base": [ "hair_color" ], "plus": [ "skin_color", "gender", "age", "race", "predict_haircut", "facial_landmarks_68", "eye_sclera_color", "eye_iris_color", "lips_color" ] }, "blendshapes": { "base": [ "legacy_45", "visemes_17" ] }, "additional_textures": { "base": [ "slightly_cartoonish_texture" ], "plus": [ "smooth_eyelashes_texture", "lips_mask" ] }, "avatar_modifications": { "indie": [ "allow_modify_neck" ], "plus": [ "caricature_amount", "lips_color", "teeth_color" ] }, "haircuts": { "facegen": [ "facegen_afro", "facegen_balding", "facegen_bob", "facegen_bob_parted", "facegen_burr_cut", "facegen_classic_side_part", "facegen_classic_tapper", "facegen_corkscrew_curls", "facegen_cowlick", "facegen_cowlick2", "facegen_crew_cut", "facegen_crew_cut2", "facegen_crew_cut3", "facegen_cuckoo_nest", "facegen_curtained_hair", "facegen_flattop", "facegen_high_volume_brushed_up", "facegen_long_afro", "facegen_long_bob", "facegen_long_crimped", "facegen_long_dreads", "facegen_long_hair", "facegen_long_hair2", "facegen_man_bun", "facegen_man_bun2", "facegen_mid_length_messy", "facegen_mid_length_ruffled", "facegen_pigtails", "facegen_ponytail", "facegen_short", "facegen_short_bob_asymmetrical_bangs", "facegen_short_curls", "facegen_short_curls2", "facegen_short_parted", "facegen_side_french_braid", "facegen_straight_bob_bangs", "facegen_top_knot", "facegen_very_long", "facegen_wavy_shag" ], "base": [ "female_NewSea_J086f", "female_NewSea_J096f", "female_NewSea_J123f", "male_NewSea_J003m", "male_NewSea_J082m", "male_makehuman_short02" ] } } }
curl -H "Authorization: Bearer $TOKEN" \ -X GET \ "https://api.avatarsdk.com/parameters/available/animated_face/?pipeline_subtype=base/legacy" { "base/legacy": { "model_info": { "base": [ "hair_color" ], "plus": [ "skin_color", "gender", "age", "race", "predict_haircut", "facial_landmarks_68", "eye_sclera_color", "eye_iris_color", "lips_color" ] }, "blendshapes": { "base": [ "legacy_45", "visemes_17" ] }, "additional_textures": { "base": [ "slightly_cartoonish_texture" ], "plus": [ "smooth_eyelashes_texture", "lips_mask" ] }, "avatar_modifications": { "indie": [ "allow_modify_neck" ], "plus": [ "caricature_amount", "lips_color", "teeth_color" ] }, "haircuts": { "facegen": [ "facegen_afro", "facegen_balding", "facegen_bob", "facegen_bob_parted", "facegen_burr_cut", "facegen_classic_side_part", "facegen_classic_tapper", "facegen_corkscrew_curls", "facegen_cowlick", "facegen_cowlick2", "facegen_crew_cut", "facegen_crew_cut2", "facegen_crew_cut3", "facegen_cuckoo_nest", "facegen_curtained_hair", "facegen_flattop", "facegen_high_volume_brushed_up", "facegen_long_afro", "facegen_long_bob", "facegen_long_crimped", "facegen_long_dreads", "facegen_long_hair", "facegen_long_hair2", "facegen_man_bun", "facegen_man_bun2", "facegen_mid_length_messy", "facegen_mid_length_ruffled", "facegen_pigtails", "facegen_ponytail", "facegen_short", "facegen_short_bob_asymmetrical_bangs", "facegen_short_curls", "facegen_short_curls2", "facegen_short_parted", "facegen_side_french_braid", "facegen_straight_bob_bangs", "facegen_top_knot", "facegen_very_long", "facegen_wavy_shag" ], "base": [ "female_NewSea_J086f", "female_NewSea_J096f", "female_NewSea_J123f", "male_NewSea_J003m", "male_NewSea_J082m", "male_makehuman_short02" ] } } }
We will use the following parameters for our avatar:
{ "model_info": { "plus": [ "gender", "age", "race" ] }, "additional_textures": { "plus": ["lips_mask"] }, "blendshapes": { "base": ["visemes_17"] }, "haircuts": { "base": ["female_NewSea_J086f"] } }
Save avatar parameters and export parameters into the file parameters.json. Run the avatar computation request with the parameter file above, the photo.jpg image from the current directory (adjust path if necessary), TOKEN and PLAYER values obtained earlier and save the avatar code for further use:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X POST "https://api.avatarsdk.com/avatars/" ^ -F "name=test from curl sample" ^ -F "pipeline=animated_face" ^ -F "pipeline_subtype=base/legacy" ^ -F "parameters=<parameters.json" ^ -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-01-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=animated_face" \ -F "pipeline_subtype=base/legacy" \ -F "parameters=<parameters.json" \ -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-01-14T07:44:12.554903Z", "name": "test from curl sample", "description": "" } AVATAR="0c60a909-2e5b-4c49-9365-368b4cf78d43"
Once the photo is uploaded avatar computation is started. 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-01-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-01-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 is 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-01-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": "animated_face", "pipeline_subtype": "base/legacy" }
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-01-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": "animated_face", "pipeline_subtype": "base/legacy" }
Once the avatar is ready, download its mesh (zipped archive) and texture:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/mesh/" ^ -o "model.zip" 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/mesh/" \ -o "model.zip" curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/texture/" \ -o "model.jpg"
Download avatar blendshapes (visemes_17 was stated in parameters on avatar creation request) in FBX format as zip archive:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/blendshapes/?fmt=fbx" ^ -o "blendshapes.zip"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/blendshapes/?fmt=fbx" \ -o "blendshapes.zip"
Query all computed haircuts for the avatar, download haircut mesh and texture:
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/haircuts/" [ { "gender": "female", "identity": "female_NewSea_J086f", "mesh": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/mesh/", "model": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/", "pointcloud": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/pointcloud/", "preview": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/preview/", "texture": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/texture/", "url": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/" } ] curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/haircuts/female_NewSea_J086f/mesh/" ^ -o "female_NewSea_J086f.zip" curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/haircuts/female_NewSea_J086f/texture/" ^ -o "female_NewSea_J086f.png"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/haircuts/" [ { "gender": "female", "identity": "female_NewSea_J086f", "mesh": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/mesh/", "model": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/", "pointcloud": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/pointcloud/", "preview": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/preview/", "texture": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/texture/", "url": "https://api.avatarsdk.com/avatars/3c78e0ec-bc22-415f-8917-fee6ecc7204d/haircuts/female_NewSea_J086f/" } ] curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/haircuts/female_NewSea_J086f/mesh/" \ -o "female_NewSea_J086f.zip" curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/haircuts/female_NewSea_J086f/texture/" \ -o "female_NewSea_J086f.png"
Download additional texture (lips_mask was stated in parameters on avatar creation request):
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/textures/" [ { "identity": "lips_mask", "file": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/textures/lips_mask/file/" }, { "identity": "model", "file": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/textures/model/file/" } ] curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/textures/lips_mask/file/" ^ -o "lips_mask.png"
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/textures/" [ { "identity": "lips_mask", "file": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/textures/lips_mask/file/" }, { "identity": "model", "file": "https://api.avatarsdk.com/avatars/0c60a909-2e5b-4c49-9365-368b4cf78d43/textures/model/file/" } ] curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/textures/lips_mask/file/" \ -o "lips_mask.png"
Request avatar info (gender, age, and race were stated in parameters on avatar creation request):
curl -H "Authorization: Bearer %TOKEN%" ^ -H "X-PlayerUID: %PLAYER%" ^ -X GET ^ "https://api.avatarsdk.com/avatars/%AVATAR%/model_info/" { "pipeline": "animated_face", "race": "white", "pipeline_subtype": "base/legacy", "gender": "female", "age": "not_child", "gender_confidence": 0.9999961853027344, "races": { "white": 1, "black": 1.785005032672871e-09, "asian": 1.384531517212295e-10 }, "age_confidence": 1, "race_confidence": 1 }
curl -H "Authorization: Bearer $TOKEN" \ -H "X-PlayerUID: $PLAYER" \ -X GET \ "https://api.avatarsdk.com/avatars/$AVATAR/model_info/" { "pipeline": "animated_face", "race": "white", "pipeline_subtype": "base/legacy", "gender": "female", "age": "not_child", "gender_confidence": 0.9999961853027344, "races": { "white": 1, "black": 1.785005032672871e-09, "asian": 1.384531517212295e-10 }, "age_confidence": 1, "race_confidence": 1 }