Avatar WEB API curl usage sample

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 full body avatar from a photo and download avatar mesh, blendshapes and haircut in fbx format 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 for Linux/macOS platforms, thus see the corresponding sample section for your platform by clicking on the platform title.

Commands sequence

  1. Authorization

    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.

    Windows
    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"
    
    Linux
    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"
    
  2. Create a Player ID

    Create a Player ID that will own all future avatars. Please note, that the Player ID does not expire.

    Windows
    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"
    
    Linux
    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"
    
  3. Query available parameters

    Query all available parameters for body/mobile subtype of body_0.1 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.

    Windows
    curl -H "Authorization: Bearer %TOKEN%" ^
         -X GET ^
         "https://api.avatarsdk.com/parameters/available/body_0.1/?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",
            "enhance_lighting",
            "gender",
            "height",
            "weight"
          ]
        },
        "blendshapes": {
          "base": [
            "mobile_51",
            "visemes_15"
          ]
        },
        "haircuts": {
          "base": [
            "generated"
          ]
        },
        "model_info": {
          "plus": [
            "gender",
            "race",
            "age",
            "hair_color",
            "skin_color",
            "eye_sclera_color",
            "eye_iris_color",
            "facial_landmarks_68"
          ]
        }
      }
    }
    
    Linux
    curl -H "Authorization: Bearer $TOKEN" \
         -X GET \
         "https://api.avatarsdk.com/parameters/available/body_0.1/?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",
            "enhance_lighting",
            "gender",
            "height",
            "weight"
          ]
        },
        "blendshapes": {
          "base": [
            "mobile_51",
            "visemes_15"
          ]
        },
        "haircuts": {
          "base": [
            "generated"
          ]
        },
        "model_info": {
          "plus": [
            "gender",
            "race",
            "age",
            "hair_color",
            "skin_color",
            "eye_sclera_color",
            "eye_iris_color",
            "facial_landmarks_68"
          ]
        }
      }
    }
    
  4. Create an avatar

    We will use the following parameters for our avatar:

    {
      "avatar_modifications": {
        "plus": {
          "gender": "male",
          "height": 1.8,
          "weight": 85
        }
      },
      "blendshapes": {
        "base": ["mobile_51", "visemes_15"]
      },
      "haircuts": {
        "base": ["generated"]
      }
    }
    

    Create an avatar with the parameters above and a photo.jpg photo from the current directory (adjust path if necessary):

    Windows
    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.1" ^
         -F "pipeline_subtype=body/mobile" ^
         -F "parameters={\"blendshapes\": {\"base\": [\"mobile_51\", \"visemes_15\"]}, \"avatar_modifications\": {\"plus\": {\"gender\": \"male\", \"height\": 1.8, \"weight\": 85}}, \"haircuts\": {\"base\": [\"generated\"]}}" ^
         -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"
    
    Linux
    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.1" \
         -F "pipeline_subtype=body/mobile" \
         -F "parameters={\"blendshapes\": {\"base\": [\"mobile_51\", \"visemes_15\"]}, \"avatar_modifications\": {\"plus\": {\"gender\": \"male\", \"height\": 1.8, \"weight\": 85}}, \"haircuts\": {\"base\": [\"generated\"]}}" \
         -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"
    
  5. Poll avatar status

    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:

    Windows
    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
    }
    
    Linux
    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 is 100:

    Windows
    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.1",
      "pipeline_subtype": "body/mobile"
    }
    
    Linux
    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.1",
      "pipeline_subtype": "body/mobile"
    }
    
  6. Download model files

    Once the avatar is ready, download its base mesh with blendshapes, skeleton and all computed haircuts meshes in one unified file and corresponding textures in separate files. Replace fbx with gltf if you need an avatar in gltf format:

    Windows
    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%/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"
    
    Linux
    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/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"