Skip to content

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.

docs(genesis): describe the full-body text-to-avatar path and log the fix in the changelog

nirholase40cd738ba83
diff --git a/data/changelog.json b/data/changelog.json
index 86bcf9960..ddd593cc9 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -28390,6 +28390,16 @@
"improvement"
],
"link": "/docs/freshness"
+ },
+ {
+ "date": "2026-09-18",
+ "title": "Text avatars now wear what you describe",
+ "summary": "Typing a description on /genesis (or sending a prompt to the avatar API) used to produce the same template body with a face pasted onto it, so an explorer in a teal flight jacket came back in someone else's clothes. Text avatars are now built from your words head to toe: the prompt is painted as a full-body character, sculpted into a textured 3D model on our own GPU, and given a skeleton so it animates immediately. Selfies still use the face pipeline, which is what a likeness needs. The free 3D generator behind the forge_avatar tool also stopped failing when the community GPU spaces were out of quota: it now moves the job onto our own worker instead of giving up.",
+ "tags": [
+ "fix",
+ "improvement"
+ ],
+ "link": "/genesis"
}
]
}
diff --git a/docs/avatar-reconstruction.md b/docs/avatar-reconstruction.md
index a103c5973..b73ac6b6b 100644
--- a/docs/avatar-reconstruction.md
+++ b/docs/avatar-reconstruction.md
@@ -1,7 +1,13 @@
# Selfie → Avatar Reconstruction
-This is the subsystem that turns a **user's photo** (or a text→image reference)
-into a rigged, animation-ready 3D avatar. It is distinct from the Forge
+This is the subsystem that turns a **user's photo** into a rigged,
+animation-ready 3D avatar. A **text prompt** sent to the same endpoint does NOT
+use this pipeline: fitting a face onto a template body ignores everything a
+prompt says about outfit, build, and style, so prompts run the full-body lane
+instead (a full-body reference image, reconstructed on the self-hosted Hunyuan3D
+worker, then auto-rigged). The lane plan lives in
+[`api/_lib/prompt-avatar.js`](../api/_lib/prompt-avatar.js); both inputs share
+the job contract, the status poll, and the finalize tail described below. It is distinct from the Forge
generation lane in the [Avatar Pipeline](avatar-pipeline.md): the Forge generates
an *arbitrary* mesh from a prompt, whereas reconstruction fits a *specific
person* onto a fixed, pre-rigged template — the same architecture Avaturn and
@@ -10,7 +16,7 @@ blendshapes instead of a bare mesh that still needs auto-rigging.
- **Worker:** [`workers/avatar-reconstruction/`](../workers/avatar-reconstruction) — FastAPI on a Cloud Run L4 GPU.
- **Backend provider:** [`api/_providers/gcp.js`](../api/_providers/gcp.js), selected by `AVATAR_REGEN_PROVIDER=gcp` (see [`api/_lib/regen-provider.js`](../api/_lib/regen-provider.js)).
-- **User entry points:** the selfie/upload flow and text→avatar prompt flow in [`api/avatars/_actions.js`](../api/avatars/_actions.js) (`POST /api/avatars/reconstruct`).
+- **User entry points:** the selfie/upload flow (and, via the full-body lane, the text→avatar prompt flow) in [`api/avatars/_actions.js`](../api/avatars/_actions.js) (`POST /api/avatars/reconstruct`).
- **Completion:** normally driven by the browser polling `/api/avatars/regenerate-status`, which runs the finalize stages inline. [`api/cron/reconstruct-sweep.js`](../api/cron/reconstruct-sweep.js) is the server-side backstop for when it isn't — see below.
## Who finishes the job
diff --git a/docs/genesis.md b/docs/genesis.md
index bfbc5caa2..55271183a 100644
--- a/docs/genesis.md
+++ b/docs/genesis.md
@@ -30,12 +30,21 @@ never invents a shortcut path; it orchestrates the real ones.
- **Body.** The `text` and `selfie` modes both POST to `/api/avatars/reconstruct`
(a prompt or a photo), then poll `/api/avatars/regenerate-status` with capped
exponential backoff (1.5s first poll, 1.4x backoff, 12s ceiling, 8-minute
- deadline). This is the identical rigged-avatar pipeline behind `/create/prompt`
- and `/create/selfie`. The reconstruction model returns a textured mesh; when the
- mesh has no skeleton and the active provider has a rig model configured, the
- pipeline chains an auto-rig job (GCP UniRig / Hunyuan3D `generation_all`) and only
- surfaces the avatar once it can be animated, so you never receive a T-posed
- static mesh. The `remix` mode instead POSTs to `/api/avatars/fork`, forking a
+ deadline). The two inputs take different engines behind that one contract:
+ - **Text** builds the whole character from your words. The prompt is painted as
+ one full-body reference image (a single figure in a neutral A-pose, head to
+ feet in frame, plain background), reconstructed into a textured mesh on our
+ self-hosted Hunyuan3D-2.1 GPU worker, then auto-rigged with a humanoid
+ skeleton on our rig worker. Outfit, hair, build and style all come from the
+ prompt, so "a silver-haired explorer in a teal flight jacket and brown boots"
+ comes back wearing exactly that. If the Hunyuan3D worker is unavailable the
+ job fails over to self-hosted TRELLIS, then the external image-to-3D lanes,
+ then your own Meshy or Tripo key when you have one saved.
+ - **Selfie** runs the face pipeline: it reconstructs your face from the photo
+ and fits it to a rigged body, which is what a likeness needs.
+
+ Either way the avatar is only surfaced once it has a skeleton, so it animates
+ straight away. The `remix` mode instead POSTs to `/api/avatars/fork`, forking a
public avatar into a fresh one you own.
- **Agent and wallets.** Reconstruct and fork auto-provision the agent record.
Genesis resolves it via `GET /api/agents?avatar_id=...`, then calls
@@ -127,8 +136,11 @@ curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/wallet/provision" \
so the rig is not limited to a curated allowlist.
- **On-chain identity is optional and reversible in practice.** Skipping it leaves a
fully working agent; you can bind an identity later.
-- **Selfie framing.** The reconstruction path is a face pipeline. A clean headshot
- reconstructs far more reliably than a full-body photo.
+- **Selfie framing.** The selfie path is a face pipeline. A clean headshot
+ reconstructs far more reliably than a full-body photo. Text prompts never use it.
+- **Text prompts describe one humanoid.** The text path frames a single standing
+ figure for rigging, so a prompt for an object or a crowd will not produce a
+ useful avatar. Use [/forge](https://three.ws/forge) for props and scenes.
- **Ownership.** The agent, both wallets, and the identity are yours. Remix forks a
public avatar into a new agent you own; it never mutates the source.