GET - 2D Render of an Avatar

Get a 2D render of an avatar for stickers or profile pictures.

All avatars are hosted in a CDN under https://models.readyplayer.me.

Please always use the https://models.readyplayer.me URL for Avatar requests instead of https://api.readyplayer.me/.

Get avatar 2D render by id.

GET https://models.readyplayer.me

Get an avatar 2D image with desired settings.

Path Parameters

Name	Type	Description
avatarId.(png|jpg)*	String	ID of an avatar.

Query Parameters

Name	Type	Description
blendShapes	String	Map of 3D meshes to their blend shapes.
cacheControl	Boolean	Uses custom Cache-Control header
uat	String	User Avatar Timestamp
size	Number	Image width and height
quality	Number	Image compression quality
camera	String	Camera preset
background	String	Background color value
expression	String	Avatar facial expression
pose	String	Avatars pose

200: OK 2D Render of the avatar.

404: Not Found The requested avatar is not available.

{
    // Response
}

Parameters, expected values, and examples

/avatarId.(png|jpg)

ID of an avatar with .png or .jpg file extension.

Expected values (String)

• 64e3055495439dfcf3f0b665.png

• 64e3055495439dfcf3f0b665.jpg

It may take some time to render the image in the backend for the initial request. For subsequent requests, the images will be fetched from cache and delivered much faster.

Example

Request avatar render by ID.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png

Returned value

You will receive a .png image.

?expression

Specify which facial expression the Avatar will be making.

Expressions can also be combined together with poses and blend shapes for more advanced use-cases.

Expected values (String)

• happy

• lol

• sad

• scared

• rage

Example

Requesting a happy Avatar.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?expression=happy

Request an Avatar laughing out loud.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?expression=lol

Request a sad Avatar.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?expression=sad

Requesting a scared Avatar.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?expression=scared

Request an enraged Avatar.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?expression=rage

?pose

Specify which pose the Avatar will take for the image.

Poses can also be combined together with expressions for more advanced use-cases.

Expected values (String)

• power-stance

• relaxed

• standing

• thumbs-up

Example

Requesting an Avatar with a thumbs-up pose.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?pose=thumbs-up

Request an Avatar power posing.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?pose=power-stance

Request an Avatar that's in a relaxed state of mind.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?pose=relaxed

Request an Avatar that's intensely standing.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?pose=standing

Combine poses and expressions for more fun variations.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?pose=thumbs-up&expression=lol

?blendShapes

Map of 3D meshes to their blend shapes.

Expected values (String) blendShapes[mouthSmile]=0.2

• mouthSmile is an example of a blend shape included in the avatar.

You can find all available blend shapes in Full-body Avatars.

You can combine multiple blend shapes by concatenating them with '&' as shown in the following example:

?blendShapes[mouthSmile]=0.2&blendShapes[browInnerUp]=0.2

Example

Request a smiling avatar

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?blendShapes[mouthSmile]=0.8

Returned value

You will receive a .png image of a smiling avatar.

?camera

Specify which camera preset should be used for the image.

Expected values (String)

• portrait - this is the default camera.

• fullbody

Example

Request a render with a portrait close-up of the Avatar.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?camera=portrait

Request a render with full body camera preset.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?camera=fullbody

?background

Control the background color in RGB format. Expected values (String)

• 255,255,255 - red, green, blue

Example

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?background=144,89,156

?quality

Defines the compression quality for lossy formats like jpg. Default quality is highest.

Expected values (Number)

• min 0

• max 100

Higher number means higher image quality.

Example

Requesting lower quality image.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.jpg?quality=30

Requesting high-quality image.

https://models.readyplayer.me/64e3055495439dfcf3f0b665.jpg?quality=100

?size

Specify image dimensions for width and height in pixels.

Expected values (Number)

• min 1

• max 1024

Example

Requesting with different image sizes. Useful for optimising for different devices and available viewport space.

Small 64x64

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?size=64

Medium 256x256

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?size=256

Extra large 1024x1024

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?size=1024

?uat

The User Avatar Timestamp (UAT) parameter allows users to set and retrieve the last modified timestamp of their avatars using the ".json" endpoint. It ensures efficient avatar synchronization, minimizing server requests, and delivering real-time updates to avatars for an enhanced user experience and seamless integration with our partners. By default we use no-cache meaning user will go to our CDN and get a cached version (you don't get the benefit of browser disk storage) Expected values (String)

• 2023-07-05T10:39:48.911Z

Example

Get the last updatedAt value at:

https://models.readyplayer.me/64e3055495439dfcf3f0b665.json

Add at the end of the avatar

https://models.readyplayer.me/64e3055495439dfcf3f0b665.png?cacheControl=true&uat=2023-07-05T10:39:48.911Z

Next time avatar gets modified, json will change and you'll get the latest version directly