Custom Avatar Creator

Get Assets and Icons to dress your avatar and build your avatar creator asset UI

Custom avatar creator

Before you begin

• Make sure you have created an anonymous user and assigned them an avatar in the previous step. We will need the created user ID, avatar ID, and user authorization token in this section.

• You will also need to know your application ID. 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. This should be selected as seen below.

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

1. Get equipable assets

To show all the equipable assets on the avatar-creator, you need to fetch them first. You can do this with the asset list endpoint specified below. You can authenticate a user with their token from the previous step, and you can provide a range of different query param filters to filter the returned assets. For this example, you will need to:

• replace user-id in the query with an anonymous user ID you created before

• replace application-id in the query with the application ID you got before from the studio

• add X-APP-ID header, which has the value of your application ID

• add Authorization header, which contains user authorization token as Bearer.

Get all of the available asset in application for the specific user

GET https://api.readyplayer.me/v1/assets?filter=usable-by-user-and-app&filterApplicationId=[application-id]&filterUserId=[user-id]

More info about the rest of the parameters and responses can be seen in the API documentation: https://docs.readyplayer.me/ready-player-me/api-reference/rest-api/assets/get-list-assets

Query Parameters

Name	Type	Description
filterApplicationId		Application id from studio
filterUserId	String	User id

Headers

Name	Type	Description
X-APP-ID*	String	Application id from studio
Authorization*	Bearer [token]

200: OK

{
    "data": [
        {
            "id": "123456789",
            "name": "outfit",
            "organizationId": "63eba72b442b6965bf9f1ed2",
            "listed": true,
            "locked": false,
            "type": "outfit",
            "editable": false,
            "gender": "female",
            "hasApps": true,
            "campaignIds": [],
            "iconUrl": "https://www.datocms-assets.com/36636/1682332188-573b9a7f-bf01-4f17-965d-d34d56bd2bdf.jpg",
            "maskUrl": "",
            "baseColorUrl": "",
            "occlusionUrl": "",
            "psdTemplateUrl": "",
            "badgeLogoUrl": "",
            "faceBlendShapes": [],
            "color": null,
            "hairStyle": "",
            "eyebrowStyle": "",
            "eyeStyle": "",
            "beardStyle": "",
            "glassesStyle": "",
            "lockedCategories": [],
            "activeForCampaign": "",
            "iconText": "",
            "iconGlow": false,
            "price": "",
            "fullPrice": "",
            "position": 25627,
            "createdAt": "2023-04-28T17:17:29.061Z",
            "updatedAt": "2023-06-09T13:55:31.608Z"
        }
    ]
}

2. Sort assets by type

To sort assets by type in the editor, you can use the type parameter from the previous step response. All of the available types for the assets are listed under the Asset entity.

Asset types are also different for each gender. So make sure that if you, e.g., want to modify a female avatar, you only download and display female assets.

Example of listing the assets by type

3. Equip asset to the user

At this stage, you will now have your draft avatar from the previous page, and you will have used the asset list endpoint to fetch a list of assets that you can equip. Now that we have these two components we need some way to put them together so that we can equip some of these assets to our draft avatar.

You will need an asset ID and the user avatar ID, to equip the given asset to the user.

Equip asset to the avatar

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

Request Body

Name	Type	Description
outfit	String	id of the outfit

200: OK

{
    "data": {
        "id": "1234567980",
        "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": "145859028",
            "shirt": "",
            "skinColor": 5,
            "skinColorHex": "#cf927a"
        }
    }
}

4. Fetch the updated avatar

After making the call to add the asset to the avatar, you can then fetch this avatar as a GLB by calling the following URL with your avatar ID.

Fetch assigned avatar as GLB file

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

200: OK GLB file

5. Save updated avatar

Once your draft avatar has been equipped with all of the desired assets from the asset list endpoint, you can then move on to confirming and saving your new avatar draft. You can do this 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
    }
}

6. Fetch avatar

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

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

200: OK Avatar in GLB format

7. Make your project awesome!

You now have a working application with a working implementation of the Ready Player Me avatar creator that will create avatars linked to your Ready Player Me application. You can now take a look at how to import your own custom assets to your application or you can go in any direction you think makes sense for your project.