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.
Turn a Selfie into a Rigged 3D Avatar
Take one front-facing photo and walk away with a rigged 3D avatar that looks like you — one you can drop onto an agent, animate, and embed anywhere. The Scanner handles capture, reconstruction, and auto-rigging end to end; you point a camera and name the result.
Prerequisites: a device with a camera (phone or laptop) or a clear front-facing photo to upload. No code, no 3D experience, and no account needed to start a scan. You'll want a three.ws account to save the avatar and put it on an agent.
What you're building
You: one front-facing selfie (optionally + left and right angles)
↓ [reconstruct → texture → auto-rig]
Result: a rigged GLB that looks like you — animation-ready,
attached to an agent, downloadable for any engine
A flat photo has no geometry. The Scanner reconstructs a 3D head-and-body mesh, wraps your real face onto it as a texture, then auto-rigs the mesh with a humanoid skeleton so it can move — idle, walk, gesture — without you touching a rig. The output is a standard glTF 2.0 binary (.glb) that works in three.ws and in external tools (VRChat, Spatial, Unity, Unreal) alike.
This tutorial covers the full path: capture → generate → auto-rig → put it on an agent.
How the flow works (one minute of theory)
The Scanner is one pipeline reachable two ways:
- /scan is the front door. It immediately forwards to /create/selfie, which is the full capture experience (including the option to bring your own reconstruction key). Either URL gets you to the same place —
/scanis the memorable one to share. - /create/selfie is where capture, the build progress, and the finished avatar all live.
Under the hood the page (src/selfie-capture.js) collects your photos, downscales them in your browser, and hands them to the pipeline (src/selfie-pipeline.js), which submits the job and polls for progress. There are exactly two calls:
POST /api/avatars/reconstruct— submit the photos, get back ajobId.GET /api/avatars/regenerate-status?jobId=…— poll until the job reportsdone.
The job moves through visible stages — reconstructing the mesh, building geometry and textures, auto-rigging the skeleton and skinning — then returns the finished avatar's id. You never call the rig step yourself; it's part of the job. This is the platform-wide rule: every avatar three.ws creates is auto-rigged so it can animate. (For the rig internals, see Avatar Creation.)
Step 1: Take or pick a good photo
Result quality is mostly decided here. The face the engine can see clearly is the face you get back.
Five rules for the front-facing shot:
- Face the camera directly — no extreme angles, chin level.
- Good, even lighting — indirect daylight is ideal; avoid harsh shadows or backlighting.
- Remove anything covering your face — sunglasses, masks, a hat brim over the eyes.
- Keep hair off your forehead and jawline where you can — the engine needs your face outline.
- Plain background helps the reconstruction isolate you.
You don't need a studio. A normal selfie in a well-lit room is plenty.
Accepted formats: JPEG, PNG, WebP, and HEIC/HEIF (iPhone photos work as-is). Photos are downscaled in your browser to a maximum of 1024px before upload — your original file never sits on disk, and only the generated avatar texture is kept.
Step 2: Open the Scanner and add your photo
Go to /scan (it lands you on /create/selfie).
You'll see one required slot: Add a front-facing photo. Two ways to fill it:
- Use camera — opens your camera in the browser with live face guides. Hold still inside the oval; the page checks framing, lighting, blur, and head angle and captures when it's a good frame.
- Upload photo — pick an existing image from your device.
If your browser or device can't open the camera (common on non-HTTPS connections and some desktop browsers), the camera option is disabled automatically — use Upload instead.
That one front-facing photo is all you need to build an avatar. The submit button stays disabled (showing "Add a photo to start") until a frontal photo is in place.
Step 3: Add side angles for sharper geometry (optional)
Open the Add side angles disclosure to reveal two more slots:
- Left — turn your head about 45° to the left.
- Right — turn your head about 45° to the right.
Each extra angle is geometry the engine doesn't have to guess, so the sides and back of your head come out noticeably crisper. The trade-off is time: the submit button updates to reflect it — roughly ~90s for one photo, ~120s when you add angles.
Keep the same lighting and the same way-up across all three shots. Side angles are optional; skip them if you just want a fast result.
Step 4: Choose style and body type
Two quick choices below the photos:
Style
- Photoreal — likeness-first; closest to how you actually look. (This is the default.)
- Stylized — cleaner, cartoon-leaning; good for streaming and games.
Body type
- Masc (default) or Femme — this selects the body proportions the rig is built on.
Pick the pair that fits how you'll use the avatar. You can always run another scan with different settings later — nothing here is permanent.
Step 5: Build the avatar
Click the build button (it reads Build my avatar · ~90s, or the high-fidelity variant if you added angles).
What happens next:
- If you're not signed in, you'll be sent to sign in and returned to the Scanner — saving an avatar requires an account.
- The page submits your photos and switches to the build view: "Building your avatar… This usually takes 1–2 minutes. Don't close this tab."
- You'll see the pipeline narrate real progress as it works:
Queued — waiting for a reconstruction slot…
Generating 3D mesh from your photo…
Building geometry and textures…
Auto-rigging skeleton and skinning…
Finishing avatar…
That "Auto-rigging skeleton and skinning…" line is the step that makes the avatar movable — the reconstruction produces a mesh, and the pipeline fits a humanoid skeleton to it and binds the skin so animation clips can drive it. You don't trigger it; it's part of every build.
The build is resilient: the job id is held in your session, so if you reload mid-build the page resumes polling the same job instead of starting over. If the engine is busy you may see "Still working — this one is taking a bit longer…"; that's expected on the longer tail, not an error.
Step 6: Why "auto-rigged" matters
A reconstructed mesh that isn't rigged is a statue — it can be viewed but not animated. That's why rigging is built into the create path, not an optional extra.
Across three.ws, every avatar that gets created auto-rigs so it can move. For the selfie flow the rig is fitted inside the reconstruction job (the step you watched in Step 5). For avatars that arrive already built — an uploaded GLB or a forged model — the same guarantee holds: if the mesh comes in static, the platform fires an auto-rig pass in the background and swaps the rigged version in place, with a sweep cron as a safety net so nothing gets stuck half-rigged. The mechanism differs; the outcome is identical: a humanoid you can animate.
Once rigged, the avatar drives the shared clip library. Bone names from common conventions (Mixamo, VRM, Unreal, and more) are mapped to a canonical skeleton, and idle/walk/gesture clips retarget onto it automatically — legs included. The practical upshot: the avatar you just built will move the moment you open it in the Animation Studio, with no extra rigging work from you.
Step 7: Name it and open your avatar
When the build finishes you land on the done view: "Your avatar is ready."
- It renders in a live 3D preview — drag to spin it and check the result. Look at the sides and back; if you skipped angles, that's where the engine had the least to work with.
- Give it a name in the Name your avatar field (up to 60 characters).
- Click Open my avatar → to go to your avatar's page at
/avatars/<id>.
From the done view you can also:
- Customize in editor — opens the avatar in the editor (
/avatars/<id>/edit) to adjust appearance, clothing, and accessories. - List on marketplace — flips the avatar to public and takes you to its marketplace listing.
- Not quite right — try again — resets the form so you can rescan with a better photo or different settings.
Whatever you choose, the avatar is already saved to your account as a rigged GLB.
Step 8: Put the avatar on an agent
An avatar is a body; an agent is the brain that lives in it. Creating an avatar already wires up an agent for you — the two are tied together so the avatar shows up, animates, and can transact.
You have two paths:
It's already done. When the avatar is saved, three.ws attaches it to an agent automatically: it links the avatar to one of your agents that doesn't yet have a body, and if you don't have one, it creates a default agent and gives it this avatar. Open Open my avatar → and the agent behind it is provisioned and ready.
Reassign it deliberately. If you want this avatar to become the face of a specific existing agent, attach it explicitly:
// Session-cookie calls carry a CSRF token. Tokens are single-use, so mint a
// fresh one per request. (API-key callers send `Authorization: Bearer <key>`
// with the `avatars:write` scope instead and skip this step.)
const { token } = await (await fetch('/api/csrf-token', { credentials: 'include' })).json();
await fetch('/api/onboarding/link-avatar', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': token },
credentials: 'include',
body: JSON.stringify({
avatarId: '0f25b676-e27b-4929-875c-4135fea0f635', // your id from /avatars/<id>
force: true, // replace the agent's current avatar
}),
});
// → { agent: { id, avatar_id, updated_at } }
force: true overrides an avatar the agent already has. Omit it (or set false) to only attach when the agent has no avatar yet. Either way the call is owner-scoped: you can only attach avatars to agents you own.
Once linked, give the agent a personality and a brain, then share it or embed it on a site.
Step 9: Use the avatar everywhere
Because the output is a clean, rigged glTF 2.0 file, it isn't locked to three.ws:
- Animate it in the Animation Studio — load it, browse the clip gallery, and retarget motion onto it live. It works because it's rigged.
- Download the GLB from the avatar page to use it in Unity, Unreal, Blender, or any glTF-aware tool.
- Embed it on a website with the web component — see Embed in 30 seconds.
- Refine the look in the avatar editor at
/avatars/<id>/edit. Clothing and accessories layer on top of the GLB without re-rigging it; Avatar Creation documents how that layering works. - Tune how it looks on your site with Customize size, position and background, which covers the embed's layout, framing, and backdrop.
Privacy — what happens to your photo
Your photo(s) are uploaded to the platform's storage and referenced by the build job so it can complete and be retried on failure — the same way any creation tool keeps its source input while the job runs. Concretely:
- Not public. The raw photo isn't exposed by any public endpoint or gallery — only the generated avatar is shareable, and only if you set its visibility to unlisted/public.
- Not analyzed beyond this build. Nothing runs face recognition, identity matching, or profiling against your photo outside of producing the 3D reconstruction you asked for.
- Deleting an avatar removes it from your account and any listing immediately; it's a soft delete, not an instant hard purge of the underlying storage object.
If you'd rather nothing persisted at all, use a disposable/cropped photo — the reconstruction only needs a clear, evenly-lit face, not an identifiable original.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| "Add a photo to start" won't go away | No frontal photo in the required slot | The front-facing slot is mandatory; side angles alone aren't enough |
| The Use camera option is missing or disabled | Browser/device can't open the camera (often non-HTTPS, or no camera) | Use Upload photo instead, or open the page in Safari/Chrome on a device with a camera |
| Build failed: "Try clearer photos in better light" | Blurry photo, no detectable face, or harsh lighting | Reshoot per Step 1 — face the camera, even light, nothing covering your face |
| Sides or back of the head look wrong | Only a frontal photo was provided | Add Left and Right angles (Step 3) and rebuild |
| "Photos are too large" | The upload exceeded the size limit | Photos are downscaled to 1024px in-browser; retry, or use a smaller source image |
| Asked to sign in mid-build | Saving an avatar needs an account | Sign in when prompted — you're returned to the Scanner and the build continues |
| "Too many requests" / rate-limited | Per-visitor cooldown after repeated attempts | Wait about a minute and try again |
| The reload during a build started a fresh scan | Rare; the pending job id wasn't found | The build resumes automatically when the job id is in your session — re-open /create/selfie and let it poll |
| Asked for a reconstruction API key | This deployment runs in bring-your-own-key mode | Paste a key from the supported provider in the form shown; it's stored for your session only |
Recap
You turned a single selfie into a rigged, agent-ready 3D avatar:
- Capture — one front-facing photo at /scan → /create/selfie; optional left/right angles sharpen the geometry.
- Choose — Photoreal vs Stylized, Masc vs Femme body type.
- Generate —
POST /api/avatars/reconstructbuilds the mesh and texture; the page pollsregenerate-statusand shows real progress. - Auto-rig — the build fits a humanoid skeleton and skins the mesh so it can animate; this happens for every avatar three.ws creates, no manual step.
- Attach — the avatar is linked to an agent automatically, or attach it to a specific agent with
POST /api/onboarding/link-avatar.
The result is a standard .glb that animates in the Animation Studio, embeds on the web, and works in external engines — a real likeness of you, ready to move.
See also
- Turn Photos into a 3D Model — reconstruct an object (not a person) from a few photos in the Forge.
- Animate your avatar — apply and tune motion on the rigged avatar you just built.
- Avatar Creation — the full reference: every creation path, rig requirements, and accessories.
- Customize size, position and background: how the finished avatar is framed and placed once it is embedded on a page.
- Give your agent a personality — turn the body into a character.