GET - 3D avatar

Get a 3D avatar GLB file with desired performance and configuration settings.

Get an avatar GLB by id.

GET https://avatars.readyplayer.me/avatarId.glb

Get an avatar GLB model with desired performance and configuration settings.

Path Parameters

Name	Type	Description
avatarId.glb	String	ID of an avatar.

Query Parameters

Name	Type	Description
quality	String	Use quality presets to combine performance related parameters.
meshLod	Int	Control the triangle count of the assets equipped on the avatar.
textureSizeLimit	Int	Sets the upper limit for texture resolution in pixels of any texture in the avatar.
textureAtlas	Int	Generates a texture atlas of the desired resolution. The operation merges all meshes and splits opaque objects from transparent ones resulting in a maximum of 2 draw calls.
textureChannels	String	Define which textureChannels should be included in the .glb. It can be a comma-separated combination of the following values: baseColor, normal, metallicRoughness, emissive, occlusion
morphTargets	String	Comma-separated list of individual morph targets or morph target standard groups to include on the avatar.
dracoCompression	Boolean	Reduces file size by compressing output avatars with Draco mesh compression. More effective on complex meshes.
meshCompression	Boolean	Reduces file size by compressing output avatars with Mesh Optimization compression. More effective on meshes with morph targets.
textureFormat	String	Reduce avatar file size by formatting all textures into the specified format. Using webp encoding can result in up to 40% reduction in avatar file size. Supported values: webp, jpeg, png
textureQuality	String	Choose which texture quality preset to get on the avatar.
morphTargetsGroup	String	Preset for list of morph targets to include (e.g. animation shapes for mouth movement).
meshDisplacement	Number	Offset for assets / clothing (usually to reduce clipping).
disableAnimation	Boolean	Disable embedded animations in assets like the nft set (disabled gltf extension "animation pointer") mostly for compability reasons or file size reduction
preferRedirects	Boolean	If set to true (default) will redirect to CDN avatar url.
removeSkin	Boolean	Removes hidden skin surfaces under top, bottom and footwear on the body, reducing triangles, clipping and file size (hidden surface removal)
deferredCompression	Boolean	Delay compression processing (possibly for async optimization pipelines).
targetBlueprintId	String	Blueprint used to compile the avatar.

200: OK Model/gltf-binary of avatar.

404: Not Found The requested model is not available.

Parameters, expected values, and examples

You can combine multiple parameters by concatenating with &.

So for example requesting an avatar with meshLod 2 and without texture atlassing would look like that:

https://avatars.readyplayer.me/65a8dba831b23abb4f401bae.glb?meshLod=2&textureAtlas=none

Parameters, expected values, and examples

/avatarId.glb

ID of an avatar.

Expected values (String)

• 65a8dba831b23abb4f401bae.glb

Notes

You must include the .glb to recieve the glb

Without any of the optional parameters, the avatar is returned based on default values.

Examples

?quality

Use quality presets to combine performance related parameters from below.

Expected values (String)

• low - meshLod=2, textureSizeLimit=256, textureAtlas=256, morphTargets=none

• medium - meshLod=1, textureSizeLimit=512=textureAtlas=512, morphTargets=none

• high - meshLod=0, textureSizeLimit=1024=textureAtlas=1024, morphTargets=none

• ultra - meshLod=0, textureSizeLimit=2048=textureAtlas=2048, morphTargets=none

All other values overwrite quality. So e.g. you can use quality=low and overwrite the meshLod with 0 to get the high-res avatar. See Examples.

Example

?meshLod

Control the triangle count of the assets equipped on the avatar. This does not impact the quality of the head model of the avatar.

Expected values (Number)

• 0 - No triangle count reduction is applied (default).

• 1 - Retain 50% of the original triangle count.

• 2 - Retain 25% of the original triangle count.

Examples

?textureSizeLimit

Set the upper limit for texture resolution in pixels of any texture in the avatar.

Expected values (Number)

The value needs to be a multiple of two.

• Min: 256

• Max: 4096 (default)

Examples

?textureQuality

Set the quality for textures on the Avatar by choosing from one of the presets.

Expected values (String)

• low - overall lower quality textures on the avatar and equipped assets.

• medium - higher quality head and upper body assets (default).

• high - overall high quality textures on the whole avatar and assets.

These options are intended to provide more optimization control when having to render many Avatars in a 3D scene. The intention for low quality is to be used for Avatars that are farther in the distance and don't require as much detail.

Examples

?textureAtlas

Generate a texture atlas of the desired resolution. This operation merges all meshes and splits opaque objects from transparent ones resulting in a maximum of 2 draw calls.

The texture atlas is generated for all PBR channels - baseColor, normal, metallicRoughness, emissive, and occlusion, if any of the assets making up the avatar includes them.

Expected values (String, Number)

• none - Do not create a texture atlas (default).

• 256 - Create a texture atlas of 256x256px.

• 512 - Create a texture atlas of 512x512px.

• 1024 - Create a texture atlas of 1024x1024px.

• 2048 - Create a texture atlas of 2048x2048px.

Examples

?textureFormat

Reduce avatar file size by formatting all textures into the specified format.

Using webp encoding can result in up to 40% reduction in avatar file size.

At the moment, our Unity and Unreal SDKs do not officially support the WebP texture format. However, for web applications, utilizing the WebP format can be very effective to reduce avatar file size.

Expected Values (String)

• webp

• jpeg

• png

Examples

?textureChannels

Select the texture channels you want to have included in the .glb. (By default, the .glb comes with all available channels).

Expected values (String)

• baseColor

• normal

• metallicRoughness

• emissive

• occlusion

• none

You can combine these values by comma separation. See examples.

Examples

?morphTargets

Comma-separated list of individual morph targets or morph target standard groups to include on the avatar.

Expected values (String)

• Default

• ARKit

• Oculus Visemes

• + or any supported morph targets.

The default value is "Default".

Examples

?dracoCompression

Reduce the file size by compressing output avatars with Draco mesh compression.

Expected values (Boolean)

• true - Enable compression.

• false - No compression (default).

Draco mesh compression is disabled by default for maximum compatibility for various glTF loaders.

Examples

?meshCompression

Reduce the file size by compressing output avatars with Mesh Optimization compression. This technique is more effective on avatars with morph targets.

Expected values (Boolean)

• true - Enable compression.

• false - No compression (default).

Mesh Optimization compression is disabled by default for maximum compatibility for various glTF loaders.

Examples

?morphTargetsGroup

Comma-separated list of individual morph target group to include (e.g. animation shapes for mouth movement)

Expected values (String)

• Editor expressions

• Editor emotions

• Basic expressions

• ARKit

• SpeechGraphics

• Default + Oculus Visemes + eyeBlink

• Oculus Visemes

• Eyes Extra

• Default

• MetaQuest

Example

?meshDisplacement

Offset for assets / clothing (usually to reduce clipping)

Expected values (Number):

Range between:

min: 0
max: 0.01

Examples

?disableAnimation

Flag to disable embedded animations in assets like the nft set (disabled gltf extension "animation pointer") mostly for compability reasons or file size reduction

Expected values (Boolean)

• true - Disable embedded (default).

• false - Enable embedded.

Examples

?preferRedirects

If this flag is set to true, a redirection to our CDN is returned. Then the glb (if follow redirects is enabled) is returned.

If is set to false, the glb is returned.

Expected values (Boolean)

• true - Redirect to CDN url (default).

• false - Return the glb.

We really encourage to let this as true (by default), so you can benefict from the CDN. Also, we recommend to not cache/store the returned url from CDN. Simply use the https://avatars.readyplayer.me API

Examples

?removeSkin

If this flag is set to true, it removes hidden skin surfaces under top, bottom and footwear on the body, reducing triangles, clipping and file size (hidden surface removal)

Expected values (Boolean)

• true - Remove hidden skin (default).

• false - Do not remove hidden skin.

Examples

?deferredCompression

If this flag is set to true it defers the compression

Expected values (Boolean)

• true - Defers compression.

• false - Do not defer compression (default).

Examples

?targetBlueprintId

Specifies the blueprint used to compile the avatar.

This is used, for example, if we have an avatar that is created for a human (human is a blueprint), and we want it for an orc (orc is another blueprint)

Expected value (String)

Examples

The default values above only apply when you have not requested any changes to those settings previously. Please reach out to [email protected] if you want to reset your default settings.