create-3d-avatar

name	create-3d-avatar
description	Turn a text prompt (or reference image) into a rigged, animation-ready 3D avatar (GLB). Use when you or the user want to create, generate, or make a 3D avatar, character, or humanoid figure that can be posed and animated — "make a 3D avatar of a knight", "generate a character I can animate", "create a rigged astronaut". Generates the mesh and adds a humanoid skeleton in one step. Returns a GLB URL plus a pose-studio link.
when_to_use	User wants a posable/animatable humanoid character. For a static object or prop, use generate-3d-model. To rig a GLB you already have, use rig-a-model.
license	MIT
metadata	{"category":"3d/creative","cross-platform-safe":true,"pack":"three-ws-skills"}

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)
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" }'

# 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.

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.