git:20260723.04f38d2 to git:20260908.6a73c0f

---

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.

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