🧙‍♂️ spellshape-agent

spellshape-agent is the official JavaScript/TypeScript SDK for interacting with the SpellShape AI 3D design endpoints from any Node.js or browser project.

It makes it easy to:
- Expand terse object prompts into rich 3D briefs
- Generate parametric 3D model schemas from text
- Chat about — and with — generated scene data
- Analyze images and extract visual information for 3D design

Built for use in creative coding, generative design, and AI-augmented workflows.

*

🚀 Installation

``bash
npm install spellshape-agent
`

*

🪄 Quick Start

`js
import SpellshapeAgent from 'spellshape-agent';

const agent = new SpellshapeAgent({ apiKey: 'YOUR_X_API_KEY' });

// Expand a brief text prompt into a detailed 3D modeling instruction:
const expanded = await agent.expand('a chair');

// Generate a full parametric schema from the expanded prompt:
const schema = await agent.generate(expanded);

// Chat with the agent about your schema:
const response = await agent.chat('How tall is the chair?', schema);

// Analyze an image and extract design information:
const imagePrompt = await agent.vision('https://example.com/chair-image.jpg');

console.log({ expanded, schema, response, imagePrompt });
`

*

📚 API

$3


- apiKey: string (required) — Your API key (X-API-Key header)
- apiBase: string (optional) — Custom API base URL (defaults to https://agent.spellshape.com/api/agent/v1)

$3

Expands a short user prompt (e.g. "a chair") into a richly described 3D object brief.

- prompt: string
- Returns: Promise — Detailed modeling prompt

$3

Generates a parametric 3D scene/model schema from a prompt or modifies an existing schema.

- promptOrExpandedPrompt: string — Can be either a raw prompt or an already expanded prompt
- opts: object (optional) — Additional generation options
- Returns: Promise