Skip to main content

​
Get Avatar Thumbnail

GET /api/avatar/{username} Retrieves or waits for a user’s avatar thumbnail image (head or body shot).
​
username
string
required
The username to get avatar for. Append -body suffix for full body shot instead of head shot.
​
wait
boolean
If present, waits for the avatar image to be created or updated before responding

​
Shot Types

The endpoint supports two shot types based on the username parameter:
​
Head Shot
default
Default behavior - returns head thumbnail from {userId}-head.png
​
Body Shot
-body suffix
Append -body to username - returns full body thumbnail from {userId}-body.png

​
Response

Returns a PNG image file. If the avatar doesn’t exist, returns a placeholder image (static/dots.png).

​
Wait Mode

When the wait parameter is present:
  • If file doesn’t exist: waits for it to be created
  • If file exists: waits for it to be modified
  • Uses filesystem watching to detect changes
  • Returns immediately if watching fails

​
Example Requests

# Get head thumbnail
curl "http://mercury.local/api/avatar/Player1"

# Get body thumbnail
curl "http://mercury.local/api/avatar/Player1-body"

# Wait for avatar update
curl "http://mercury.local/api/avatar/Player1?wait"

​
Storage Location

Avatar images are stored at:
  • Head shots: ../data/avatars/{userId}-head.png
  • Body shots: ../data/avatars/{userId}-body.png

​
Implementation

Source: api/avatar/[username]/+server.ts:5

​
Render Character (Base)

GET /api/render/character Returns base body colors XML for character rendering. Used as a foundation for avatar rendering.

​
Response

Returns XML with all body colors set to value 1: 
<roblox>
  <Item class="BodyColors">
    <Properties>
      <int name="HeadColor">1</int>
      <int name="LeftArmColor">1</int>
      <int name="LeftLegColor">1</int>
      <int name="RightArmColor">1</int>
      <int name="RightLegColor">1</int>
      <int name="TorsoColor">1</int>
    </Properties>
  </Item>
</roblox>

​
Example Request

curl "http://mercury.local/api/render/character"

​
Implementation

Source: api/render/character/+server.ts:1

​
Render Character with Asset

GET /api/render/characterasset Returns a character appearance URL that combines base body colors with a specific asset. Used for generating avatar renders with clothing or accessories.
​
id
number
required
Asset ID to apply to the character

​
Response

Returns a plain text string with semicolon-delimited URLs: 
http://mercury.local/api/render/character;http://mercury.local/asset?id={assetId}
​
Cache-Control
string
Set to no-cache

​
URL Format

The response contains two parts:
  1. Base character render endpoint
  2. Asset endpoint for the specified asset ID

​
Example Request

curl "http://mercury.local/api/render/characterasset?id=123456"

​
Example Response

http://mercury.local/api/render/character;http://mercury.local/asset?id=123456

​
Implementation

Source: api/render/characterasset/+server.ts:5

Build docs developers (and LLMs) love

Get started for freeTalk to us