Manage custom outfits using the API

Create UGC tools or embed Ready Player Me in your content pipeline.

This page will be in a different section, once released, which currently does not exist. so this place is just temporary.

You can embed the outfit management into your pipeline using the Assets endpoints of the Ready Player Me API. It also enables you to create tools to create UGC tools on top of the APIs.

Upload a custom outfit

1. Create the asset meta-data.

An "asset" can be seen as the meta-data of an asset model. Therefore it contains a name, type, gender, URLs for the 3D-model and the icon, etc. but not the asset itself.

Use this endpoint to create a new asset

POST https://api.readyplayer.me/v1/assets

Request Body

Name

Type

Description

data.name*

string

Minimum length of 1 character

data.organizationId*

string

The id of the organization you wish to create the asset under. This is directly linked to your permissions, and you will only be able to create assets for organizations which you have permission to.

data.iconUrl*

url

Must be a valid url pointing to a PNG or JPG file.

data.modelUrl*

url

Must be a valid url pointing to a GLB file.

data.gender*

enum(string)

Possible values: male, female

data.type*

enum(string)

Possible values: outfit

data.applicationIds

array

List of application ids, this asset should be added to. If empty, this asset is not added to any application.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request",
    "data": {
        "body": [
            {
                "instancePath": "/data",
                "schemaPath": "#/properties/data/required",
                "keyword": "required",
                "params": {
                    "missingProperty": "name"
                },
                "message": "must have required property 'name'"
            }
        ]
    }
}

To create an asset, the URL of a 3D model and an icon is optional. You can update it later or upload a Model / Icon using the respective POST commands (Upload Model, Upload Asset).

If you specify a model URL, it will trigger the validation of the model. Please check out all details about the validation in the 3D asset creation guide. In case of a negative validation, you will be returned the validation errors in the response, and the asset will not be created.

If you specify an icon URL, it will check its max dimensions of 256x256 and max file size of 5MB. In case of a negative validation, you will be returned the validation errors in the response, and the asset will not be created.

Once an asset is created and has a valid model and icon, it can be added to an application. By default, an asset does not belong to any application and therefore is also not visible in the avatar creator.

2. Upload or Update an Icon

An Icon is needed to show the asset in the avatar-creator for the end user.

You can either use the URL parameter in the Create Asset command to upload an Icon, or use the POST to upload the image itself. Therefore the asset needs to exist already.

Use this endpoint to upload the icon for an asset

POST https://api.readyplayer.me/v1/assets/:id/icon

This endpoint requires the body to be of type form-data, and to have a Content-Type of multipart/form-data.

Headers

Name

Type

Description

Content-Type*

multipart/form-data

Request Body

Name

Type

Description

file*

file

The icon file to upload (PNG orJPG)

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

Recommended Specs: .png or .jpg with a dimension of 256x256 pixel max. The image may not exceed 5MB. However, for the best loading speed of the avatar creator, you should optimize the image size.

3. Upload or Update the 3D Model

You need to have a Ready Player Me compatible full-body outfit. You can learn how to create one from a template in the Asset Creation Guideline.

You can use the URL parameter in the Create Asset command to upload a 3D model or the POST to upload the model itself separately. For the second approach, the asset needs to exist already.

Once the model is uploaded, it will trigger the validation of the model. Please check out all details about the validation in the 3D asset creation guide. In case of a negative validation, you will be returned the validation errors in the response, and the asset will not be created.

Use this endpoint to upload the model for an asset

POST https://api.readyplayer.me/v1/assets/:id/model

This endpoint requires the body to be of type form-data, and to have a Content-Type of multipart/form-data.

Headers

Name

Type

Description

Content-Type*

multipart/form-data

Request Body

Name

Type

Description

file*

file

Must be a valid GLB file.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

4. Add an asset to an application

In Studio (Developer Dashboard) you need to create an Application for every game or app you create. Each application has an Application ID, which you can find in the URL of the page.

After you obtained the Application ID you can make a POST request to the following endpoint:

Use this endpoint to add an asset to an application

POST https://api.readyplayer.me/v1/assets/:id/application

Path Parameters

Name

Type

Description

id*

string

The id of the asset you want to update.

Request Body

Name

Type

Description

data.applicationId*

string

The id of the application you wish to add the asset to.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [
            "62cebaa1a04e199829e9277a"
        ],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request",
    "data": {
        "body": [
            {
                "instancePath": "/data",
                "schemaPath": "#/properties/data/required",
                "keyword": "required",
                "params": {
                    "missingProperty": "applicationId"
                },
                "message": "must have required property 'applicationId'"
            }
        ]
    }
}

After getting the success-message, you should be able to see your custom asset in your avatar creator https://[yoursubdomain].readyplayer.me.

5. Remove the asset from the application

When you no longer want to have the asset available in your avatar creator, you can remove it from the application.

Use this endpoint to remove an asset from an application

DELETE https://api.readyplayer.me/v1/assets/:id/application

Path Parameters

Name

Type

Description

id*

string

The id of the asset you want to update.

Request Body

Name

Type

Description

data.applicationId*

string

The id of the application you wish to remove the asset from.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request",
    "data": {
        "body": [
            {
                "instancePath": "/data",
                "schemaPath": "#/properties/data/required",
                "keyword": "required",
                "params": {
                    "missingProperty": "applicationId"
                },
                "message": "must have required property 'applicationId'"
            }
        ]
    }
}

6. Get all custom assets

You can retrieve a paginated, ordered list of all uploaded assets in your organization.

List Assets

GET https://api.readyplayer.me/v1/assets

Use this endpoint to fetch a paginated list of assets. With query parameters, you control the order, the number of assets you want per page, and the selected page.

Query Parameters

Name

Type

Description

order

string

The properties you would like to order the list by. You can specify multiple properties by adding the query param multiple times. Please check the example-response to check the names.

limit

number

The amount of documents you want to fetch per page.

page

number

The page of documents you would like to fetch.

"data": {
        "docs": [
            {
                "id": "63dbcb0571dad1e9aa85630c",
                "type": "outfit",
                "gender": "male",
                "iconUrl": "https://example.org/icon.png",
                "modelUrl": "https://example.org/model.glb",
                "status": "published",
                "organizationId": "61d8d13e5c7658ae34513411",
                "name": "my outfit",
                "applicationIds": [
                    "63d8e1782096e0afb2dbbe9f"
                ],
                "createdAt": "2023-02-02T14:39:01.026Z",
                "updatedAt": "2023-02-02T14:39:08.656Z",
                "publishedAt": "2023-02-02T16:39:19.216+02:00"
            }],
        "totalDocs": 18,
        "limit": 1,
        "totalPages": 18,
        "page": 1,
        "pagingCounter": 1,
        "hasPrevPage": false,
        "hasNextPage": true,
        "prevPage": 0,
        "nextPage": 2
    }
}

Currently, it is not possible to apply any filters to the request. So you need to fetch the list and query it on your end.

PreviousAssets NextPOST - Create Asset

Last updated 2 years ago

Was this helpful?

hashtagUpload a custom outfit

hashtag1. Create the asset meta-data.

hashtagUse this endpoint to create a new asset

hashtagRequest Body

hashtag2. Upload or Update an Icon

hashtagUse this endpoint to upload the icon for an asset

hashtagHeaders

hashtagRequest Body

hashtag3. Upload or Update the 3D Model

hashtagUse this endpoint to upload the model for an asset

hashtagHeaders

hashtagRequest Body

hashtag4. Add an asset to an application

hashtagUse this endpoint to add an asset to an application

hashtagPath Parameters

hashtagRequest Body

hashtag5. Remove the asset from the application

hashtagUse this endpoint to remove an asset from an application

hashtagPath Parameters

hashtagRequest Body

hashtag6. Get all custom assets

hashtagList Assets

hashtagQuery Parameters

Upload a custom outfit

1. Create the asset meta-data.

Use this endpoint to create a new asset

Request Body

2. Upload or Update an Icon

Use this endpoint to upload the icon for an asset

Headers

Request Body

3. Upload or Update the 3D Model

Use this endpoint to upload the model for an asset

Headers

Request Body

4. Add an asset to an application

Use this endpoint to add an asset to an application

Path Parameters

Request Body

5. Remove the asset from the application

Use this endpoint to remove an asset from an application

Path Parameters

Request Body

6. Get all custom assets

List Assets

Query Parameters