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.
Instant Agent Genesis: prompt or selfie to a living agent
Genesis is the one-minute on-ramp for the whole platform. You give it a text
prompt, a selfie, or a public avatar to remix. It returns a rigged 3D AI agent
that already owns a custodial Solana wallet, a custodial EVM wallet, a synthesized
persona and voice, and an optional verifiable on-chain identity. Every step is
real: the 3D body comes off the same reconstruction pipeline /create uses, the
wallet addresses are real custodial addresses, and the on-chain record returns a
real transaction hash. Nothing is mocked or faked as it runs.
Page: /genesis · APIs: /api/avatars/reconstruct, /api/avatars/regenerate-status, /api/avatars/fork, /api/agents, /api/agents/:id/wallet/provision, /api/persona/extract, /api/agents/:id
Why it exists
Creating a usable agent used to mean stitching together five surfaces: generate a model, rig it, mint a wallet, write a system prompt, pick a voice, register an identity. Each one is its own page, its own wait, its own chance to give up. Genesis collapses that into a single guided flow with a real progress bar driven by real job state, so a first-time visitor goes from an idea to a wallet-holding, animation-ready agent they fully own in under a minute of active work. It is the front door: the artifact it produces is a first-class agent that plugs straight into Agent Studio, the economy, breeding, and every embed surface.
How it works
Genesis is a state machine over the platform's existing production endpoints. It never invents a shortcut path; it orchestrates the real ones.
Body. The
textandselfiemodes both POST to/api/avatars/reconstruct(a prompt or a photo), then poll/api/avatars/regenerate-statuswith capped exponential backoff (1.5s first poll, 1.4x backoff, 12s ceiling, 8-minute 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
remixmode 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 callsPOST /api/agents/:id/wallet/provisionto guarantee both a custodial Solana address and a custodial EVM address exist. These are real custodial keys held for the agent (see Agent Wallets and Custody), Solana first because Solana is the home chain.Persona and voice.
POST /api/persona/extractsynthesizes a structured in-character system prompt from your description, running through the shared LLM helper (llmCompleteinapi/_lib/llm.js). That helper is free-providers-first by policy: the platform-funded and keyless free tiers lead the chain, Vertex Gemini on GCP credits sits behind them as the reliability anchor, and paid keys (Anthropic, OpenAI) are appended to the tail as a last resort. Nothing here depends on a paid key being present or in quota, and a single upstream 429 or 5xx never returns a hard error. Voices load from/api/tts/voices. Your chosen name, persona, and voice are persisted withPATCH /api/agents/:id.On-chain identity (optional). The final step mints a real ERC-8004 identity record for the agent and returns a real tx hash, defaulting to Base (chain id 8453) to match the rest of the platform's EVM identity layer. This step is optional: the agent is fully functional without it.
Walkthrough
- Open /genesis. Pick a mode: type a prompt, drop
a selfie, or remix one of the featured public avatars loaded from
/api/avatars/featured. - Sign in. Genesis claims the agent and its wallets to your account, so
pressing Begin requires a wallet sign-in first (the banner wires
signInWithWallet). - Kick off generation. The step bar tracks the real reconstruction job: queued, generating, rigging, ready. Progress reflects the job state, not a timer.
- Watch the agent resolve. Once the avatar is ready, Genesis resolves the auto-provisioned agent and provisions both wallets. The real Solana and EVM addresses appear.
- Name it and give it a voice. Persona extraction proposes a system prompt from your prompt; edit the name and pick a voice, then save.
- Optionally bind an on-chain identity. One click registers the ERC-8004 record and shows the returned transaction hash.
- You now own a complete agent. Open it in Agent Studio to keep authoring, drop it on a site via Integrations, or breed it in Agent Genome.
Examples
Genesis is a browser flow, but its endpoints are the public agent APIs. This drives the same body-generation step from a script (see API reference and Authentication for the session cookie or bearer token):
# 1. Start a text-to-avatar reconstruction
JOB=$(curl -s -X POST https://three.ws/api/avatars/reconstruct \
-H 'content-type: application/json' \
-H "authorization: Bearer $THREEWS_TOKEN" \
-d '{"name":"Silver Explorer","prompt":"A silver-haired explorer in a teal flight jacket"}')
echo "$JOB"
# 2. Poll status until the rigged model is ready
JOB_ID=$(echo "$JOB" | python3 -c 'import sys,json;print(json.load(sys.stdin)["jobId"])')
curl -s "https://three.ws/api/avatars/regenerate-status?jobId=$JOB_ID" \
-H "authorization: Bearer $THREEWS_TOKEN"
# 3. Resolve the auto-provisioned agent and guarantee both wallets
AVATAR_ID=... # from the finished status payload
AGENT=$(curl -s "https://three.ws/api/agents?avatar_id=$AVATAR_ID" \
-H "authorization: Bearer $THREEWS_TOKEN")
AGENT_ID=$(echo "$AGENT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["agents"][0]["id"])')
curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/wallet/provision" \
-H "authorization: Bearer $THREEWS_TOKEN"
# returns { solana_address, wallet_address (EVM), ... } with real custodial addresses
States and limits
- Signed out. Pressing Begin while signed out shows "Sign in first" instead of
starting a job: generation, wallet provisioning, and identity binding all require
sign-in (
/api/avatars/reconstructreturns 401 unauthenticated). The auth banner is always reachable. - Generation deadline. Reconstruction has an 8-minute deadline and the agent-resolve step a 60-second deadline; both surface a designed error with a retry action rather than hanging.
- Rigging fallback. If no rig model is configured or rigging fails, the pipeline
delivers the static mesh tagged
unriggedso you are never left empty-handed. Any humanoid avatar drives the pre-baked clip library via bone-name canonicalization, 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 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 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.
Related
- Agent Studio: keep authoring the agent Genesis created
- Agent Genome: breed two agents into an inherited child
- Avatar Reconstruction: the selfie-to-3D pipeline
- Agent Wallets and Custody: the custodial keys
- ERC-8004: the on-chain identity record
- Persona Hub: how personas are synthesized
- Pages: /genesis, /create, /agent-studio