Rig a 3D model

Turn a static GLB into an animation-ready one. The three.ws auto-rig
pipeline (Make-It-Animatable) adds a humanoid skeleton and per-vertex skin weights,
so the model can be posed and play animation clips.

The result is a riggedGlbUrl plus a pose-studio link that opens the
rigged model in the browser, ready to pose.

When to use which tool

Goal	Use
Add a skeleton to a GLB you already have	this skill
A new static object / prop from text	generate-3d-model
A new rigged character from text/image in one call	create-3d-avatar

Rigging assumes a roughly humanoid figure (head, torso, two arms, two legs,
standing). Props, furniture, and vehicles won't rig meaningfully.

Fastest path — the MCP tool

If the three.ws MCP server is connected, call the rig tool directly:

• Tool: rig_mesh
• Input: { "glb_url": "<https URL to the static GLB>" }
  • Any reachable GLB URL works — a glbUrl from generate-3d-model, a CDN
    link, or a model you host yourself.
• Returns: riggedGlbUrl, sourceGlbUrl, poseStudioUrl, jobId,
  creationId, durationMs.

Portable path — the hosted HTTP endpoint

No MCP client needed. rig_mesh is exposed free on the hosted studio JSON-RPC
endpoint at https://three.ws/api/mcp-studio (no key, no account):

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": "rig_mesh",
      "arguments": { "glb_url": "https://three.ws/avatars/cesium-man.glb" }
    }
  }'

structuredContent returns the rigged model:

{
  "ok": true,
  "riggedGlbUrl": "https://three.ws/cdn/creations/def456/rigged.glb",
  "sourceGlbUrl": "https://three.ws/avatars/cesium-man.glb",
  "poseStudioUrl": "https://three.ws/pose?src=https%3A%2F%2Fthree.ws%2F...",
  "jobId": "r9k2m7x4",
  "durationMs": 48000
}

Raw REST pipeline

The MCP tool is a thin client over the public rig endpoint. Submit, then poll:

# 1. Start the rig job
curl -s -X POST "https://three.ws/api/forge?action=rig" \
  -H 'content-type: application/json' \
  -d '{ "glb_url": "https://three.ws/avatars/cesium-man.glb" }'
# → { "job_id": "r9k2m7x4", ... }

# 2. Poll until done (every ~3s, budget ~180s)
curl -s "https://three.ws/api/forge?job=r9k2m7x4" -H 'accept: application/json'
# → { "status": "done", "glb_url": "https://.../rigged.glb" }  (or "failed" / still "running")

Build the pose-studio link yourself from any rigged GLB URL:
https://three.ws/pose?src=<URL-encoded riggedGlbUrl>.

What to do with the result

1. Give the user the pose-studio link — pose and preview in the browser.
2. Give the riggedGlbUrl for download / import; it carries a humanoid
   skeleton and skin weights, so animation clips retarget onto it.
3. The original mesh is never modified — sourceGlbUrl stays valid.

Errors

• rate_limited / 429 — the rigger is busy; honor retryAfter and retry.
• not_configured / 503 — auto-rigging momentarily unavailable; retry shortly.
• rig_failed — the model couldn't be rigged (usually not humanoid enough).
  Tell the user why and suggest create-3d-avatar to generate a riggable figure.
• timeout — the job outlived the poll budget; the response includes a
  resumeUrl — keep polling it rather than restarting the job.

Never report a dead or empty link as success — only return a riggedGlbUrl the
job actually produced.