Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Character Library: rigged characters, ready to animate
The Character Library is a free, curated gallery of professionally rigged humanoid 3D characters. Every character ships as a web-ready GLB with a full skeleton, skin weights, and textures, so it drives the entire three.ws animation library (idle, walk, run, wave, dance, and the rest of the canonical clip set) out of the box via animation retargeting. No account, no payment, no upload step: browse, preview live, and send any character into a studio in one click.
Page: /character-library · API: GET /api/avatars/library
Source: pages/character-library.html · src/character-library.js · api/avatars/library.js
This page covers the character gallery and its API. For the motion clips these characters play, see Animations. For the free prop counterpart to this library, see the Object Library.
What is in the library
A hundred-plus professionally rigged Mixamo humanoid characters (Y Bot, X Bot, Warrok, Remy, Vanguard, zombies, knights, and more), staged as optimized GLBs on the R2 CDN. The manifest can also merge additional CC0 characters from other sources (for example Quaternius), so the API's total field is the authoritative count. Nothing on the page hard-codes a number: the hero headline and the results counter render total from the manifest.
Every entry is animation-ready: the GLB carries a skinned mesh, and the three.ws runtime retargets the canonical clip library onto it automatically (see Animations for how retargeting and the clip registry work). There is no per-character allowlist; any character in the library plays any clip.
Using the gallery
Each card renders the character live in an auto-rotating <model-viewer> (with the pre-rendered thumbnail slotted in as a lazy-loaded poster image that fades once the model loads), shows the entry's source and file size, and offers three one-click routes. The viewer is control-free (no orbit, no extra tab stop); the whole thumbnail is a link to the preview. A manifest row with no url renders as a plain, unlinked tile with no actions.
| Button | Destination | What you get |
|---|---|---|
| Preview | /app#model=<glb-url> |
The full three.js 3D viewer |
| Use | /studio?model=<glb-url> |
Widget Studio: configure and publish an embeddable widget of this character (see the Embedding Guide) |
| Animate | /pose?src=<glb-url>&title=<name> |
Animation Studio: pose, keyframe, and export motion on this character |
Gallery controls:
- Search filters by name; press
/anywhere on the page to focus the search box. - Sort by name (A to Z, Z to A) or by file size (largest or smallest first). File size is shown on every card.
- The library is small enough that the page fetches the whole manifest once and filters client-side, so search and sort are instant. Search, sort, card copy, and the deep links are pure functions of the manifest in
src/shared/character-library-view.js, covered bytests/character-library-view.test.js. - Loading shows a skeleton grid; an empty library, an empty search result, and a fetch error each have their own designed state with a recovery action.
API: GET /api/avatars/library
Public, no authentication, GET and OPTIONS only (HEAD is answered like GET). Browser fetch from a third-party origin is not enabled: the endpoint sends Access-Control-Allow-Origin only for three.ws and its partner origins, exactly like the Object Library API. Call it server-side, or from a three.ws page. The endpoint proxies a small manifest JSON from the R2 CDN (avatars/library/manifest.json) with an edge cache (Cache-Control: public, s-maxage=300, stale-while-revalidate=3600). The GLB and thumbnail bytes never pass through the API: every entry carries absolute CDN URLs the browser loads directly.
Query parameters
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit |
integer, 1 to 1000 | none | Opt-in pagination. Omit it to get the entire library in one response. Values are clamped into 1..1000. |
offset |
integer, >= 0 | 0 | Only meaningful together with limit. |
Response shape
Without limit:
{
"avatars": [ { "...": "entry, see below" } ],
"total": 107,
"generated_at": "2026-07-21T13:39:15.447Z"
}
With limit (and optional offset), the response adds offset and next_offset. next_offset is null on the last page, and total is always the full library size, not the page size:
{
"avatars": [ "..." ],
"total": 107,
"offset": 0,
"next_offset": 25,
"generated_at": "2026-07-21T13:39:15.447Z"
}
Each entry in avatars:
| Field | Type | Meaning |
|---|---|---|
name |
string | URL-safe slug, stable identifier |
label |
string | Display name |
url |
string | Absolute CDN URL of the GLB |
thumb |
string (optional) | Absolute CDN URL of the PNG thumbnail; omitted when no thumbnail rendered |
bytes |
number | GLB file size |
skins |
number | Skinned mesh count in the GLB |
animations |
number | Animation clip count baked into the GLB itself (retargeted library clips come from the runtime, not the file) |
source |
string | Where the character came from, e.g. "mixamo" or "quaternius" |
license |
string | License tag for this entry, e.g. "Mixamo" or "CC0" (see Licensing below) |
Before the manifest is first uploaded, the endpoint returns { "avatars": [], "total": 0 } rather than an error, so consumers feature-detect by emptiness.
Example
curl -s 'https://three.ws/api/avatars/library?limit=2&offset=0'
Returns the first two characters plus total, offset, and next_offset, each entry with a directly loadable url (GLB) and thumb (PNG).
Licensing
Every manifest entry carries a license field; read it per character rather than assuming one license for the whole library.
"Mixamo": the character is an Adobe Mixamo character, used under Adobe's Mixamo terms. The manifest records the tag only, it does not restate the terms; consult Adobe's Mixamo licensing FAQ for what those terms permit before redistributing the GLB outside three.ws."CC0": public domain. Free for any use, including commercial, with no attribution required.
Using any library character inside three.ws (previewing, animating, publishing a widget or embed) is free.
How the library is staged (maintainers)
The gallery and API are read-only consumers of a manifest built by a local pipeline. The GLBs total several gigabytes, far too large for the deploy bundle, so all bytes live on the R2 CDN and only the manifest index is published:
scripts/fetch-mixamo-avatars.mjsdownloads the source characters.scripts/convert-mixamo-avatars.mjsconverts them to web GLB.scripts/fetch-mixamo-avatar-thumbnails.mjsstages the PNG thumbnails.scripts/build-mixamo-avatar-library.mjsreadspublic/avatars/mixamo/catalog.json, merges the extra CC0 characters frompublic/avatars/extra/characters.json, and PUTsavatars/library/manifest.jsonto R2 (--dry-runprints without uploading).
R2 CORS is configured by scripts/set-r2-cors.mjs so browsers can GET the GLBs cross-origin. Since 2026-09-10 the live read rule is world-open, so a manifest GLB loaded straight from the bucket host works on any origin. Measure the live policy yourself with node scripts/set-r2-cors.mjs --probe, which needs no credentials and exits 0 when the bucket matches the canonical policy. Before that date the bucket echoed only an allowlist (three.ws, *.vercel.app, localhost:3000) and every other origin got a 200 with no access-control-allow-origin, which is why older embed guides route around it. /cdn/<key> is still the better URL when you have the object key (first-party and CDN-cached for 30 days), and /api/glb is still the answer for a model URL on a host that is not ours.
Related
- Animations: the clip library every character drives, and how retargeting works.
- Animation Studio: the
/posesurface the Animate button opens. - Widget Studio and the Embedding Guide: turn a library character into a live embed on any site.
- Object Library: the same free-library pattern for CC0 props and scene objects.
- Marketplace: library characters are free; the marketplace is where priced avatars, agents, and skills are bought and sold.