Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

3.7 KB
Raw Blame

three.ws

@three-ws/ai-sdk

Give any Vercel AI SDK agent the ability to forge, rig, animate, and render 3D models, and talk to a three.ws agent.

npm license node three.ws


Five tool() definitions that wrap three.ws's generative 3D pipeline, ready to drop into generateText/streamText:

Tool What it does Auth
forge Text prompt → textured GLB Free
rig Static GLB → humanoid-rigged GLB Free
render Any public GLB → turntable preview + geometry stats Free
animate Text prompt → retargeted motion on a rigged GLB Paid (x402)
agentChat Message → a three.ws agent's reply Free

forge, rig, and render call three.ws's free, no-key /api/mcp-studio server. agentChat calls the public /api/chat endpoint. animate calls the paid, x402-gated /api/mcp server: this package never signs a payment for you, it surfaces the real PaymentRequired challenge so your own x402 client (e.g. x402-fetch) can pay from your own wallet.

Install

npm install @three-ws/ai-sdk ai zod

Quick start

import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import { createThreeWsTools } from '@three-ws/ai-sdk';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const tools = createThreeWsTools();

const { text, toolResults } = await generateText({
	model: openai('gpt-5.5'),
	tools,
	prompt: 'Forge a low-poly fox, then render a turntable of it so I can see it.',
});

console.log(text);
console.log(toolResults);

Run it directly (no model needed) to see the tools call the live API:

import { createThreeWsTools } from '@three-ws/ai-sdk';

const tools = createThreeWsTools();
const forged = await tools.forge.execute({ prompt: 'a friendly round robot mascot', tier: 'draft' });
console.log(forged);
// { ok: true, text: 'Generated this model from your prompt...', raw: {...} }

const rendered = await tools.render.execute({
	glbUrl: 'https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF-Binary/Duck.glb',
});
console.log(rendered.text);

Paying for animate

import { wrapFetchWithPayment } from 'x402-fetch';
import { createThreeWsTools } from '@three-ws/ai-sdk';

// Resolve the x402 challenge with your own wallet, then pass the resulting
// X-PAYMENT header value straight through. This package never spends for you.
const tools = createThreeWsTools();
const unpaid = await tools.animate.execute({ glbUrl: myRiggedGlbUrl, prompt: 'wave hello' });
if (unpaid.paymentRequired) {
	// use your x402 client + wallet against unpaid.challenge, then retry with xPayment set
}

Configuration

createThreeWsTools({
	baseUrl: 'https://three.ws', // override for a self-hosted deployment
	apiKey: process.env.THREE_WS_API_KEY, // only needed for `animate`
});

Each tool is also exported individually: forgeTool, rigTool, renderTool, animateTool, agentChatTool.

License

Apache-2.0