Generate a 3D model from text

Turn a natural-language prompt into a textured, downloadable GLB model on the free three.ws text→3D lane (NVIDIA NIM / Microsoft TRELLIS). No API key and no account: the platform's server-side keys cover provider cost.

The result is always two things: a durable glbUrl (download / import into any 3D tool) and a viewer link that renders the model in the browser.

When to use which tool

Fastest path: the MCP tool

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

• Tool: forge_free
• Input: { "prompt": "<description>", "tier": "draft" }
  • prompt: 3 to 1000 chars. Lead with the subject, then its key materials and colors. The free lane conditions on ~77 characters, so front-load what matters: "a friendly round robot mascot, glossy white plastic, big blue eyes".
  • tier: draft (fast, default), standard, or high. All free; higher tiers only take longer.
• Returns: glbUrl, viewerUrl, tier, backend, durationMs.

This is text-only (the free TRELLIS preview does not accept uploaded photos). For image / multi-view → 3D, use the art-directed lanes described in reference.md.

Portable path: the hosted HTTP endpoint

No MCP client required. The same free lane is a public JSON-RPC endpoint at https://three.ws/api/mcp-studio (no auth, 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": "forge_free",
      "arguments": { "prompt": "a small glossy green ceramic frog figurine", "tier": "draft" }
    }
  }'

Response (structuredContent) carries the model:

{
  "kind": "model",
  "glbUrl": "https://three.ws/cdn/creations/abc123/mesh.glb",
  "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2F...",
  "format": "glb",
  "prompt": "a small glossy green ceramic frog figurine"
}

Discover the full free tool set first with {"jsonrpc":"2.0","id":1,"method":"tools/list"}.

What to do with the result

1. Give the user the viewer link: they can rotate and inspect the model in the browser immediately.
2. Give the glbUrl for download / import into Blender, Unity, three.js, etc.
3. If they want it animated, feed glbUrl into the rig-a-model skill.

Higher-fidelity & art-directed lanes

The full three.ws MCP server also exposes art-directed and image→3D lanes (mesh_forge) and paid lanes with denser geometry. Those, the tier trade-offs, the raw POST /api/forge REST shape, and full error handling are in reference.md: load it only when you need more than the free text→3D path above.

Errors

The free lane is shared and protected by per-IP rate limits and a global capacity breaker. Handle these and retry rather than failing:

• rate_limited / busy: honor retryAfter (seconds) and try again.
• not_configured: the durable lane is momentarily cold; retry shortly.
• lane_degraded: a result was produced but its URL was unreachable; retry.

Never report a dead or empty link as success; only return a glbUrl the call actually produced.