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 { "image_url": "<https URL to a reference image>" }
  • prompt: describe a single full-body humanoid in a neutral standing pose, for example "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.