Quickstart

This step-by-step guide is designed to assist game developers in setting up player accounts and generating avatars through API integration.

Before you begin

• You will need to know your application subdomain. This is accessible from the studio on your application page. If you don't have an account in the studio, then you will need to sign up.

Main Goals:

• Account creation: Enable users to effortlessly create their accounts within your application.

• Apply an existing template to the user: Facilitate users in customizing their avatars by applying pre-existing templates to their avatars for quick personalization.

• Get user model: Fetch the created model into your application

All of the requests shown in this section are also visible in the public Ready Player Me Postman collection

1. Authorize and create an anonymous user

In this guide, we'll walk you through the process of creating an anonymous user and obtaining the access token required to access the API endpoints. The following endpoint will create a new user and it returns the access token to use for the creation of an avatar.

Create anonymous user

POST https://[your-application-subdomain].readyplayer.me/api/users

200: OK

{
    "data": {
        "visitedAt": "2023-10-22T15:42:58.190Z",
        "campaigns": [],
        "assets": [],
        "wallets": [],
        "partners": [
            "asfas-nr3il4"
        ],
        "_id": "65366366362cd70266fc9959",
        "deleteAt": "2024-01-23T12:13:26.615Z",
        "createdAt": "2023-10-23T12:13:26.616Z",
        "updatedAt": "2023-10-23T12:13:26.616Z",
        "__v": 0,
        "isAnonymous": true,
        "isGuest": false,
        "id": "65366366362cd70266fc9959",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0Fub255bW91cyI6dHJ1ZSwidXNlcklkIjoiNjUzNjYzNjYzNjJjZDcwMjY2ZmM5OTU5IiwiYWJpbGl0eSI6W1sibWFuYWdlIiwiQXZhdGFyIix7InVzZXJJZCI6IjY1MzY2MzY2MzYyY2Q3MDI2NmZjOTk1OSJ9XSxbIm1hbmFnZSIsIlVzZXIiLHsiX2lkIjoiNjUzNjYzNjYzNjJjZDcwMjY2ZmM5OTU5In1dLFsicmVhZCIsIlBhcnRuZXIiXSxbInJlYWQsY3JlYXRlIiwiT3JnYW5pemF0aW9uIl0sWyJ1c2UiLCJUcmFja2luZyIseyJfaWQiOnsiJGluIjpbIjY1MzY1YmViODQ3YjUxMTVmNzY3ZTM3YiJdfX1dLFsicmVhZCIsIkFwcGxpY2F0aW9uIl0sWyJyZWFkIiwiQXNzZXQiXSxbInVzZSIsIkFzc2V0Iix7ImxvY2tlZCI6eyIkbmUiOnRydWV9fV0sWyJ1c2UiLCJBc3NldCIseyJpZCI6eyIkaW4iOltdfX1dLFsidXNlIiwiQXNzZXRMaXN0RmlsdGVyIix7InF1ZXJ5LmZpbHRlclVzZXJJZCI6IjY1MzY2MzY2MzYyY2Q3MDI2NmZjOTk1OSJ9XSxbInVzZSIsIkFzc2V0Iix7Imdyb3Vwcy5pZCI6eyIkaW4iOltdfX1dLFsicG9zdCIsIldlYmhvb2tFdmVudCIseyJyb3V0aW5nS2V5Ijoic3R1ZGlvLXVpLnYxLmdldHRpbmctc3RhcnRlZC5jb21wbGV0ZWQifV0sWyJwb3N0IiwiV2ViaG9va0V2ZW50Iix7InJvdXRpbmdLZXkiOiJzdHVkaW8tdWkudjEuYWRkLWFwcGxpY2F0aW9uLmNvbXBsZXRlZCJ9XSxbInJlYWQiLCJDYW1wYWlnbiIsMCwwLCJpZCxuYW1lLGNyZWF0ZWRBdCx1cGRhdGVkQXQiXSxbInJlYWQiLCJBc3NldCIsMCwxLCJtb2RlbFVybCxuZnRJZCJdXSwiaWF0IjoxNjk4MDYzMjA2fQ.loUw_SBj2YfjZZp783AKNR2mZLzXLHLe7YQ8McPBkUU"
    }
}

2. Create a default avatar for the user

To create and render an initial avatar for your user, you need to call 3 endpoints.

2.1 Fetch all possible templates

Firstly you need to fetch all of the possible templates that you can create an avatar from. Templates are pre-configured avatar templates which make it easier for you to create an avatar via the API. To fetch the avatar templates you can call the following endpoint authenticated with the token returned on the request from step 1.

Get all templates

GET https://api.readyplayer.me/v2/avatars/templates

Headers

Name	Type	Description
Authorization*	Bearer [token]

200: OK

{
    "data": [
        {
            "imageUrl": "https://readyplayerme-avatars.s3.amazonaws.com/avatar-template-images/white-female-1.png",
            "gender": "female",
            "id": "1234567890"
        },
        {
            "imageUrl": "https://readyplayerme-avatars.s3.amazonaws.com/avatar-template-images/white-male-1.png",
            "gender": "male",
            "id": "12345678901"
        }
    

2.2 Create a draft avatar from a template

Once you have made a call to fetch the list of templates, you can then take one of the template IDs and make a call to create a draft avatar for the user by calling the following endpoint.

Assign a specific template to the user

POST https://api.readyplayer.me/v2/avatars/templates/[template-id]

Headers

Name	Type	Description
Authorization*	Bearer [token]

Request Body

Name	Type	Description
partner*	String	Application subdomain
bodyType*	fullbody	Avatar type

201: Created

{
    "data": {
        "id": "65367050b6ff020dad1ebc57",
        "partner": "default",
        "gender": "female",
        "bodyType": "fullbody",
        "assets": {
            "beardColor": 0,
            "beardStyle": "",
            "eyeColor": "9781803",
            "eyeShape": "",
            "eyebrowColor": 0,
            "eyebrowStyle": "41302445",
            "faceMask": "",
            "faceShape": "",
            "glasses": "9247416",
            "hairColor": 0,
            "hairStyle": "9247471",
            "headwear": "",
            "lipShape": "",
            "noseShape": "",
            "outfit": "",
            "shirt": "",
            "skinColor": 5,
            "skinColorHex": "#cf927a"
        }
    }
}

2.3 Fetch draft avatar

After making the call to create your new draft avatar, you can then fetch this avatar as a GLB by calling the following URL with your new avatar-id.

Fetch the assigned avatar as a GLB file

GET https://api.readyplayer.me/v2/avatars/[avatar-id].glb?preview=true

200: OK GLB file

2.4 Save draft avatar

The previous steps created a draft avatar for the user, which will expire after x amount of time. To save the avatar and permanently save it for the user, you will need to save the avatar with the following endpoint:

Save updated avatar

PUT https://api.readyplayer.me/v2/avatars/[avatar-id]

Headers

Name	Type	Description
Authorization*	Bearer [token]

200: OK

{
    "data": {
        "id": "65367050b6ff020dad1ebc57",
        "partner": "default",
        "gender": "female",
        "bodyType": "fullbody",
        "assets": {
            "skinColor": 5,
            "eyeColor": "9781803",
            "hairStyle": "9247471",
            "hairColor": 0,
            "beardStyle": "",
            "beardColor": 0,
            "eyebrowStyle": "41302445",
            "eyebrowColor": 0,
            "shirt": "",
            "outfit": "143549640",
            "glasses": "9247416",
            "faceMask": "",
            "headwear": "",
            "lipShape": "",
            "eyeShape": "",
            "noseShape": "",
            "faceShape": "",
            "createdAt": "2023-10-24T06:38:08.421Z",
            "updatedAt": "2023-10-24T06:38:08.421Z",
            "skinColorHex": "#cf927a"
        },
        "favorite": false,
        "default": true
    }
}

3. Fetch avatar

You can now fetch your newly saved avatar from the URL below with the avatar id.

Return avatar in glb format

GET https://models.readyplayer.me/[avatar-id].glb

200: OK Avatar in GLB format

4. Customize your avatar

You now have a working example with Ready Player Me avatars. You can go now into the next section, which explains how to customize your character with outfits.