Create a rigged 3D avatar

Turn a text prompt or a reference image into a rigged, animation-ready humanoid avatar (GLB). One call generates the textured mesh, then auto-rigs it — adding a humanoid skeleton and skin weights — so the model can be posed and play animation clips immediately.

The result is a glbUrl for the rigged model plus a pose-studio link that opens the avatar ready to pose in the browser.

When to use which tool

Auto-rigging assumes a humanoid figure. A clearly non-humanoid subject (furniture, vehicle, quadruped) is steered to generate-3d-model instead.

Fastest path — the MCP tool

If the three.ws MCP server is connected, call the one-step avatar tool:

• Tool: forge_avatar
• Input: { "prompt": "<character description>" } or

{ "imageurl": "<https URL to a reference image>" } - prompt — describe a single full-body humanoid in a neutral standing pose: "a friendly cartoon astronaut in a glossy white suit". - imageurl — reconstruct and rig a character from a photo/render. - allownonhumanoid — set true only to rig a non-humanoid subject anyway.

• Returns: the rigged glbUrl (or riggedGlbUrl), the intermediate mesh URL,

a pose-studio link, and per-stage timing.

For a fast unrigged figure (no skeleton), use texttoavatar instead — same inputs, mesh only.

Portable path — the hosted HTTP endpoint

No MCP client needed. The free hosted lane is a public JSON-RPC endpoint at https://three.ws/api/mcp-studio:

curl -s -X POST https://three.ws/api/mcp-studio \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "forge_avatar",
      "arguments": { "prompt": "a friendly cartoon astronaut in a glossy white suit" }
    }
  }'

structuredContent returns the rigged model:

{
  "kind": "avatar",
  "glbUrl": "https://three.ws/cdn/creations/def456/rigged.glb",
  "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2F...",
  "format": "glb",
  "rigged": true,
  "prompt": "a friendly cartoon astronaut in a glossy white suit"
}

Manual two-step (REST)

forge_avatar is generate-then-rig bundled. You can run the steps yourself over POST /api/forge — generate a mesh, then rig it:

# 1. Generate the figure (see generate-3d-model/reference.md for the submit/poll shape)
#    "tier": "high" matches what forge_avatar/text_to_avatar request automatically —
#    it is the tier the router maps to the self-host Hunyuan3D lane for IRL realism.
curl -s -X POST https://three.ws/api/forge -H 'content-type: application/json' \
  -d '{ "prompt": "a friendly cartoon astronaut in a glossy white suit", "tier": "high" }'

# 2. Rig the resulting GLB (see rig-a-model)
curl -s -X POST "https://three.ws/api/forge?action=rig" -H 'content-type: application/json' \
  -d '{ "glb_url": "<glbUrl from step 1>" }'

What to do with the result

1. Give the user the pose-studio / viewer link — they can pose and preview the

rigged avatar in the browser.

1. Give the glbUrl for download / import into a 3D engine; it already carries

a humanoid skeleton and skin weights, so animation clips play on it.

Prompting tips

• One full-body humanoid, neutral standing pose, arms slightly away from the

body — best for a clean rig.

• Name the silhouette and materials: `"a tall slender elf ranger in green leather

armor"`. Avoid scenes, props held in hand, or multiple characters.

• Hands are the hardest part of the mesh to get right. forge_avatar /

texttoavatar already direct the generator toward relaxed, open hands with fingers separated and visible (never a fist, never a hand hidden behind the body or in a pocket) — do not fight that by asking for "hands on hips" or "arms crossed" unless you accept a higher chance of fused-finger geometry.

• Both avatar tools always request the platform's high quality tier under the

hood — the self-host Hunyuan3D lane (people/organic-subject strength, portrait realism cues on the reference image) instead of the faster draft/standard default. This is automatic; no input needed.

Higher-fidelity & paid lanes

The full three.ws MCP server also exposes higher-fidelity, art-directed and paid avatar lanes. The free hosted path above is the cross-platform-safe one. The rig internals (skeleton convention, what makes a model riggable) live in the rig-a-model skill.

Errors

• rate_limited / busy — honor retryAfter and retry.
• not_configured — lane momentarily cold; retry shortly.
• Generation succeeded but rigging failed — you still get the unrigged mesh URL;

hand it back and offer to retry rigging via rig-a-model.

Never report a dead or empty link as success.