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

Goal	Use
A posable humanoid character from text/image	this skill
A static object / prop / creature	generate-3d-model
Add a skeleton to a GLB you already generated	rig-a-model

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
  { "image_url": "<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".
  • image_url — reconstruct and rig a character from a photo/render.
  • allow_non_humanoid — 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 text_to_avatar 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.
2. 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 /
  text_to_avatar 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.
  Asking is not the same as getting: measured across six personas on 2026-09-08,
  a prompt that explicitly said "hands open, fingers separated" still came back
  with both hands fused into one clasped blob at the chest in one case, and with
  cleanly separated fingers in another. What correlates with separated fingers is
  the hands being away from the torso and from each other in the described
  pose, so say where the hands are ("arms hanging at his sides, palms forward"),
  not just what they are doing.
• 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.