Manage custom assets using the API
Create UGC tools or embed Ready Player Me in your content pipeline.
Last updated
Was this helpful?
Create UGC tools or embed Ready Player Me in your content pipeline.
Last updated
Was this helpful?
You can embed the asset 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.
For all subsequent requests to the Asset endpoints, you need an API Key. Please go to to create one.
You can authorize by adding x-api-key to the header of the request.
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.
POST https://api.readyplayer.me/v1/assets
data.name*
string
Minimum length of 1 character
data.type*
enum(string)
Possible values:
outfit, costume,facewear, glasses, hair, headwear
data.gender*
enum(string)
Possible values:
male, female, neutral
data.modelUrl*
url
Must be a valid url pointing to a GLB file.
data.iconUrl*
url
Must be a valid url pointing to a PNG or JPG file.
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 access to.
data.applicationIds
array
List of application ids, this asset should be added to. If empty, this asset is not added to any applications.
data.locked
boolean
A boolean value which when set to true requires the asset to be unlocked for specific user before it is usable by them.
default: false
data.listed
boolean
A boolean value indicating if this asset is visible in avatar editor for linked applications or not.
default: false
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.
An Icon is needed to show the asset in the avatar-creator for the end user.
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
.
Content-Type*
multipart/form-data
file*
file
The icon file to upload (PNG orJPG)
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.
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
.
Content-Type*
multipart/form-data
file*
file
Must be a valid GLB file.
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 obtain the Application ID, you can make a POST request to the following endpoint:
POST https://api.readyplayer.me/v1/assets/:id/application
id*
string
The id of the asset you want to update.
data.applicationId*
string
The id of the application you wish to add the asset to.
data.isVisibleInEditor
string
Defines if asset is visible in this application's avatar editor.
After getting the success message, you should be able to see your custom asset in your avatar creator https://[yoursubdomain].readyplayer.me.
When you no longer want to have the asset available in your avatar creator, you can remove it from the application.
DELETE https://api.readyplayer.me/v1/assets/:id/application
id*
string
The id of the asset you want to update.
data.applicationId*
string
The id of the application you wish to remove the asset from.
You can retrieve a paginated, ordered list of all uploaded assets in your organization.
GET https://api.readyplayer.me/v1/assets
limit
number
The amount of documents you want to fetch per page.
page
number
The page of documents you would like to fetch.
organizationId
string
Filter out assets that have been created by your organization.
You can either use the URL parameter in the command to upload an Icon, or use the POST to upload the image itself. Therefore the asset needs to exist already.
You need to have a Ready Player Me compatible asset. .
Use this endpoint to fetch a paginated list of assets. With query parameters, you can control filters, the order, the number of assets you want per page, and the selected page. See all available fields in our
To see example requests, please check out the
