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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsonindex 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.mdindex 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 Forgegeneration lane in the [Avatar Pipeline](avatar-pipeline.md): the Forge generatesan *arbitrary* mesh from a prompt, whereas reconstruction fits a *specificperson* 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 jobdiff --git a/docs/genesis.md b/docs/genesis.mdindex 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 cappedexponential 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 apublic 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 afully 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 apublic avatar into a new agent you own; it never mutates the source.