create-3d-avatar git:20260908.6a73c0fA

Immutable. This exact content is served forever at /api/v1/blob/c899ee2457eb22b2.

---
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`:

```bash
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:

```json
{
  "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:

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