LogoLogo
WebsiteBlogForumsSign up
  • Welcome
  • How Ready Player Me works
  • FAQ
  • 👩‍💻Integration Guides
    • Overview
    • Unity
      • Quickstart
      • Avatar Creator Integration
        • WebView Avatar Creator
          • Avatar Creator for Android & iOS
          • Avatar Creator for WebGL
        • Build your own Avatar Creator
          • Start with the sample
          • Elements
            • Asset Selection Element
            • Color Selection Element
            • Template Selection Element
            • Body Shapes Selection Element
            • Gender Selection Element
            • Avatar List Element
            • Photo Capture Element
            • Signup Element
            • Login Element
            • Logout Element
          • User Management
      • Load 2D Renders
      • Avatar Loader Window
      • Setup Multiplayer
      • Setup for XR (Beta)
        • Setup the Player Avatar
        • Setup Meta Movement SDK
        • Setup Final IK
        • Setup XR Hands
          • RpmHandDriver script
        • Facial Animations
        • VR Avatar Creator
      • Animations
        • Ready Player Me Animation Library
        • Mixamo Animations
      • Optimize
        • Avatar Configuration
        • Avatar Caching
        • Defer Agents
      • Code Samples
        • Loading 3D Avatars
        • Loading 2D Avatars
        • Avatar Creator (WebGL)
        • Avatar Creator (Desktop)
        • Avatar Creator (Mobile)
        • Distance-based LODs
      • Troubleshooting
        • Editor UI Window Issues
        • Avatar loading issues
        • iOS issues
        • WebGL issues
        • Firewall issues
        • Updating the SDK
          • Unity SDK 3.0.0 Migration guide
          • Unity SDK 4.0.0 Migration guide
          • Unity SDK 5.0.0
          • Unity SDK 7.0.0
          • WebView 2.0 Migration
        • Package installation issues
      • Help us improve the Unity SDK
      • FAQ for Unity
      • Early Access Features
    • Unreal Engine
      • Quickstart
        • Import SDK Manually
      • Avatar Creator Integration
        • Build your own Avatar Creator
          • Sample Structure
          • Customization Guide
        • WebView Avatar Creator
      • Load Avatars
      • Animations
        • Ready Player Me Animation Library
        • Loading Mixamo animations
        • Mannequin animation retargeting
        • Blender FBX export to UE
        • Oculus Lipsync integration
      • Optimize
        • Avatar configuration
        • Avatar caching
        • Avatar preloading
      • Code Samples
        • Unreal Engine 5 samples
        • Lyra project integration example
        • VR Avatars
        • Unreal Engine 4
      • Troubleshooting
        • Project compilation issues
        • Missing materials on built applications
        • Avatar loading issues
        • Animation issues
        • Unreal SDK breaking changes
        • Avatar lighting issues
        • Updating from earlier versions
          • Unreal SDK 3.0.0 Migration guide
        • Auto LOD issues
      • Help us improve the Unreal Engine SDK
      • FAQ for Unreal Engine
      • Early Access Features
    • React
      • Quickstart
    • React Native
    • iOS Native
    • Android Native
    • Web Integration
      • Quickstart
      • User Management
        • Guest Accounts
        • Account Linking
      • Avatar Creator integration
      • Optimize
    • API Integration
      • Quickstart
      • Custom Avatar Creator
      • User management
        • Ready Player Me Account
        • Anonymous Accounts
    • UX/UI Guidelines
      • Summary & quick tips
      • UX and UI guidelines and essentials
        • Foundation for good user experience
          • Layout
          • Colors
          • Typography
          • Icons
          • Dark mode and light mode
        • Mobile best practices
          • Layout
        • Making Ready Player Me feel native
          • Seamless Avatar Integration
          • Consistent Branding
          • Responsive Layout
          • Performance Optimization
        • Discoverability of the avatar editor
          • Onboarding tutorial
          • Clear navigation
          • Contextual Placement
  • 🖌️Customizing Guides
    • Studio (Developer Dashboard)
    • Avatar Creator Appearance
      • Avatar URLs
      • Avatar Shortcodes
    • Upload and Manage Custom Assets
      • Asset Manager in Studio
      • Configure in Studio
      • Manage custom assets using the API
      • Unlocking assets through API (Beta)
    • Create Custom Assets
      • Fullbody Outfits
        • Checking Skin Weights
      • Tops, Bottoms, Shoes
        • Editing templates
      • Hairstyle
      • Headwear
      • Facewear
      • Glasses
      • Hero Characters
      • Modeling Guidelines
  • 🔃API Reference
    • REST API
      • Authentication
      • Avatars
        • GET - 3D avatar
        • GET - 2D Render of an Avatar
        • GET - Metadata
        • PUT - Equip an asset
        • PUT - Unequip an asset
      • Assets
        • Asset Entity Properties
        • POST - Create Asset
        • GET - List Assets
        • PATCH - Update Asset
        • POST - Upload Asset Files
        • POST - Add Asset to Application
        • DELETE - Remove Asset from Application
        • PUT - Unlock asset for a user
        • PUT - Lock asset for a user
      • Users
        • POST - Create User
      • Auth
        • GET - Token
      • Changelog
    • Avatars
      • Full-body avatars
      • Full-body XR avatars
      • Half-body avatars
      • Morph targets
        • Apple ARKit
        • Oculus OVR LipSync
    • Avatar Creator
  • 🔉Support
    • Forums
    • Licensing & Privacy
Powered by GitBook
On this page
  • Get and authorize with an API Key
  • Upload a custom asset
  • 1. Create the asset meta-data.
  • Use this endpoint to create a new asset
  • 2. Upload or Update an Icon
  • Use this endpoint to upload the icon for an asset
  • 3. Upload or Update the 3D Model
  • Use this endpoint to upload the model for an asset
  • 4. Add an asset to an application
  • Use this endpoint to add an asset to an application
  • 5. Remove the asset from the application
  • Use this endpoint to remove an asset from an application
  • 6. Get all custom assets
  • List Assets
  • Full API Reference

Was this helpful?

  1. Customizing Guides
  2. Upload and Manage Custom Assets

Manage custom assets using the API

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

PreviousConfigure in StudioNextUnlocking assets through API (Beta)

Last updated 1 year ago

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.

Get and authorize with an API Key

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.

--header 'x-api-key: {your-api-key}'

Upload a custom asset

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.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

{
    "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'"
            }
        ]
    }
}
{
    "type": "ForbiddenError",
    "status": 403,
    "message": "Cannot execute \"create\" on \"Asset\""
}

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.

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",
    }
}
{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request"
}

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 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 obtain 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.isVisibleInEditor

string

Defines if asset is visible in this application's avatar editor.

{
    "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'"
            }
        ]
    }
}
{
    "type": "ForbiddenError",
    "status": 403,
    "message": "Cannot execute \"update\" on \"Asset\""
}

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'"
            }
        ]
    }
}
{
    "type": "ForbiddenError",
    "status": 403,
    "message": "Cannot execute \"update\" on \"Asset\""
}

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

Query Parameters

Name
Type
Description

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.

"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
    }
}

Full API Reference

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

🖌️
Studio -> API Keys
You can learn how to create one in these guides here
REST API documentation
REST API Reference
Create Asset