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.

9.0 KB
Raw Blame

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 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). 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 POST /api/agents/:id/wallet/provision to 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/extract synthesizes a structured in-character system prompt from your description, running through the shared LLM helper (llmComplete in api/_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 with PATCH /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

  1. Open /genesis. Pick a mode: type a prompt, drop a selfie, or remix one of the featured public avatars loaded from /api/avatars/featured.
  2. 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).
  3. Kick off generation. The step bar tracks the real reconstruction job: queued, generating, rigging, ready. Progress reflects the job state, not a timer.
  4. 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.
  5. 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.
  6. Optionally bind an on-chain identity. One click registers the ERC-8004 record and shows the returned transaction hash.
  7. 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/reconstruct returns 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 unrigged so 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