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.

feat(3d-vision): let an AI agent see the 3D model it just made

nirholasd5f5189c07b0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ad854550..6fdc70892 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,12 +7,14 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-08-28
- **Companion** (`/companion`): A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.
+- **Docs · 3D Vision: let an agent see the model** (`/docs/3d-vision`): Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.
- **Docs · Feedback** (`/docs/feedback`): Telling the corner companion what broke: the proactive ask at the moment of failure, the route, build SHA, and console errors captured for you, the severity and clustering rules, the report API, and the boundary that keeps untrusted visitor text from ever reaching anything with write access.
- **Publishing to the Solana dApp Store** (`/docs/seeker-publishing`): The release runbook for the three.ws Seeker app: Publisher Portal setup, the release keystore, building and verifying a signed APK, and submitting it for review.
- **three.ws on iOS** (`/docs/ios-app`): What the App Store app adds on top of the website: the native share sheet, universal links, wallet deep links back to the page you left, real permission prompts, and an offline screen that recovers on its own.
- **Agent history catches up on fast chains in days instead of weeks**: The cross-chain index read one window of blocks per chain every 15 minutes. That is enough to keep pace with a slow chain but not to close a gap on a fast one: Arbitrum was 18.4 million blocks behind and would have taken about six weeks to catch up, while most runs finished early with most of their time budget unused. Runs now spend that spare time on whichever chain is furthest behind, and do nothing extra when every chain is current. `[improvement]`
- **Agent history on Base, Ethereum and Gnosis is moving again**: The cross-chain agent index had stopped advancing on three networks. A single unprintable byte inside an on-chain metadata string was rejected by the database, and because the index only records its position after a successful write, every following run re-read the same block and hit the same byte. Base had been frozen for 13 days, Gnosis for 15 and Ethereum for 4. Those bytes are now stripped on the way in, so the event is kept and the crawl moves past it. Registrations, ownership transfers, metadata edits and reputation attestations on those chains flow into agent profiles again. `[fix]`
- **Agent payments now stop themselves when the fee wallet runs dry**: The platform sponsors the network fee on every agent payment. When that wallet ran down to the point where it could not cover a single fee, the check meant to pause payments could not run, because it depended on a balance lookup and the network providers were rate-limited at the same moment. Payments kept being attempted for three hours and none of them could complete. The pause now reads its answer from the failure itself, which costs nothing and works exactly when the network is too busy to answer questions. The status page also names the real cause now, a wallet that needs funding, instead of pointing at the payment rail. `[fix, infra]`
+- **AI agents can now see the 3D models they make**: Until today every 3D generator on the internet, ours included, answered with a link to a file an AI agent cannot open. A person clicks it; an agent is blind to it, which is why an agent that makes a 3D model has never been able to tell a clean one from a melted one. That changes now: ask to look at any model and it comes back rendered from four angles as actual pictures the agent sees, with the geometry explained in plain language. An agent can finally check its own work, spot that the back of the model was never finished, and try again saying exactly what was wrong. It works over MCP, over a plain web request, and through a new open-source package called @three-ws/see, and it is free, including for agents that bought a model from us and want to confirm they got what they paid for. (`/docs/3d-vision`) `[feature, sdk]`
- **Next on the roadmap: your agent on your home screen**: A fifth phase has been added to the public roadmap: native widgets. Right now three.ws is something you open. The plan is for the agent you own to sit on your home screen and your desktop, showing itself and one live number about it, refreshed by the system without you opening anything, with a tap that drops you back into the right screen. Android is first, because the Android app is already built and signed: three.ws ships as a real app for Solana Seeker, and as of today Google confirms the app's release key against the site, so a three.ws link opens inside the app instead of a browser tab. Windows 11 follows through the installed web app, which needs no separate store submission, then macOS and iOS through a shared widget extension. None of it is shipped yet. It is written down, scoped and public so you can hold us to it, and the phase is on the roadmap in the repo along with the work order behind it. `[docs]`
- **Photo uploads, avatar saves, launches and team tasks fail fast instead of hanging**: A handful of steps still had no time limit on the outside service they called. When that service accepted the connection and then went quiet, the request sat there until the platform killed it, and you got a spinner that ended in nothing: a photo-to-avatar upload that never came back, a saved model that never finished downloading, a coin launch stuck fetching its own thumbnail, an ordinals order whose status never loaded, a team task where one hired agent held up the whole run. Each of those now has a deadline and a clear answer when it is missed, and the ones that are safe to repeat retry once first. Anything that spends money or starts a generation is never repeated: it is bounded and then reported, so no upload is billed twice and no hire is paid twice. Saving a model from a link is also checked more tightly now, against the address it actually connects to and with the size limit applied while it downloads. `[improvement, fix, infra]`
- **Tell the agent in the corner what is broken**: The companion that walks your pages now listens. When a page actually fails, it turns and asks what you were doing, and the report it sends carries what you should never have to type: the page, the exact build it happened on, your screen size, and the errors the browser recorded at that moment. You can also open it any time from the control beside the avatar, and dictate instead of typing. Reports are grouped so that twenty people hitting one problem read as one problem, and every one of them is read by a person before anything changes. (`/docs/feedback`) `[feature, improvement]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index a73dc4ff9..07c4467fe 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -62,6 +62,7 @@ bottom.
| Crypto Data API docs / landing | [pages/crypto.html](pages/crypto.html) `→ /crypto` | In-repo · docs surface | Screenshot-worthy public docs + funnel-top for the free, keyless Crypto Data API (`/api/crypto/*`: token snapshot, security, holders, launches, bonding, whales, symbol, wallet, trending, portfolio, airdrops). Renders hero, endpoint table, tabbed quickstart (curl/JS/Python), per-endpoint request/response reference and a live "Try it" console. Probes production at runtime and marks each endpoint Live vs Coming soon (degrades gracefully while sibling endpoints roll out). CTAs funnel to paid uniques: [/launcher](pages/launcher.html), [/vanity-wallet](public/vanity-wallet.html), [/forge](pages/forge.html). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) |
| Free Crypto Data API + discovery | [api/crypto/index.js](api/crypto/index.js) `→ /api/crypto`, [api/crypto/openapi.js](api/crypto/openapi.js) `→ /api/crypto/openapi.json`, docs [docs/crypto-api.md](docs/crypto-api.md) `→ /docs/crypto-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless Crypto Data API. Catalog assembler [api/_lib/crypto-catalog/index.js](api/_lib/crypto-catalog/index.js) merges `api/_lib/crypto-catalog/*.js` self-describing descriptors (currently `airdrops`, `bonding`, `holders`, `launches`, `portfolio`, `security`, `symbol`, `token`, `trending`, `wallet`, `whales`) via a static import barrel (the production source of truth, since Vercel's bundler only ships what static imports reach) plus an additive dev-time directory glob; skips malformed/throwing entries, never throws, valid-empty when zero. New descriptor = drop the file AND add its import line to the barrel. OpenAPI built from the same catalog via [api/_lib/crypto-catalog/openapi.js](api/_lib/crypto-catalog/openapi.js). Index does HTML/JSON content negotiation. Endpoint handlers live in `api/crypto/*.js`. Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) |
| Unified Crypto API aggregator — storefront + OpenAPI | Registry [api/v1/_providers.js](api/v1/_providers.js) (`providerCatalog()`), front door [api/v1/x/[...slug].js](api/v1/x/%5B...slug%5D.js) `→ /api/v1/x/<provider>/<endpoint>`, discovery `→ GET /api/v1/x`, storefront [pages/crypto-api.html](pages/crypto-api.html) `→ /crypto-api`, OpenAPI 3.1 [api/openapi-json.js](api/openapi-json.js) `→ /openapi.json`, docs § in [docs/api-reference.md](docs/api-reference.md#unified-api--apiv1x-aggregator), dir guide [api/v1/README.md](api/v1/README.md) | Live | Third-party crypto/DeFi/on-chain APIs (CoinGecko, DefiLlama × 2, Jupiter, DexScreener, Solana RPC, OpenAI-compatible) re-offered as one bill: free per-IP tier → BYOK pass-through → three.ws plan → x402 pay-per-call, in that order. Everything (OpenAPI paths, the `/crypto-api` live table, the docs quota table) renders from `providerCatalog()` at request/page-load time — no hand-enumeration, so a new provider descriptor shows up everywhere with zero page edits. Test: [tests/openapi-aggregator.test.js](tests/openapi-aggregator.test.js). Not to be confused with the separate `/api/crypto/*` bundle below (different campaign, different registry). Spec: x402-catalog campaign (retired 2026-07-28; readable in git history) |
+| 3D Vision (let an agent see a model) | [api/_lib/3d-vision.js](api/_lib/3d-vision.js), route [api/3d/look.js](api/3d/look.js) `→ /api/3d/look`, MCP tool `look_at_model` in [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) and on every OKX forge endpoint ([api/_okx3d/forge.js](api/_okx3d/forge.js)), SDK [packages/see/](packages/see) (`@three-ws/see`) | Live | Every text-to-3D API answers with a URL to a binary an AI agent cannot open, so the agent that generated a model has no way to check its own work; that blindness is why agentic 3D stalls at one shot. This renders any public GLB from up to six angles (three-quarter, front, side, back, top, bottom; the default four are the smallest set that answers "is this good") and hands the frames back as **MCP image content blocks**, which a multimodal client renders into the conversation, so the model literally looks at its own output and can regenerate naming the fault it saw. Reuses the platform's headless renderer ([api/_lib/avatar-render.js](api/_lib/avatar-render.js)) with the `full-body` preset so props and creatures are not cropped like humanoids, renders frames sequentially because the browser is shared, and reports a partial turntable rather than failing. Geometry comes from the existing free inspector and is best-effort: a hiccup costs the numbers, never the frames. Free and keyless on REST and MCP, and free for OKX buyers on the paid forge endpoints, so an agent can confirm it got what it paid for. Docs: [docs/3d-vision.md](docs/3d-vision.md). Tests: [tests/3d-vision.test.js](tests/3d-vision.test.js) |
| Free 3D API + docs | [api/3d/index.js](api/3d/index.js) `→ /api/3d`, [api/3d/openapi.js](api/3d/openapi.js) `→ /api/3d/openapi.json`, landing page [public/3d.html](public/3d.html) `→ /3d`, reference doc [docs/3d-api.md](docs/3d-api.md) `→ /docs/3d-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless 3D API. Catalog assembler [api/_lib/3d-catalog/index.js](api/_lib/3d-catalog/index.js) merges `api/_lib/3d-catalog/*.js` descriptors (currently `generate`, `inspect`) via a static import barrel (production source of truth) plus an additive dev-time directory glob; new descriptor = drop the file AND add its barrel import line; skips malformed, never throws; OpenAPI built from the same catalog via [api/_lib/3d-catalog/openapi.js](api/_lib/3d-catalog/openapi.js). Index does HTML/JSON content negotiation and advertises the paid ladder (Forge Pro, Rigged Avatars). Docs page: hero, live endpoint table, runnable quickstart with a live "Run inspect" console, embedded `<model-viewer>` GLB preview, and the free→paid ladder. Free endpoints: [api/3d/generate.js](api/3d/generate.js) (prompt 12), [api/3d/inspect.js](api/3d/inspect.js) (prompt 13). GPT Store Actions surface: [api/3d/studio.js](api/3d/studio.js) `→ /api/3d/studio`, a store-compliant twin of `generate` that strips the x402/upgrade block, drops internal ids, and runs the [api/_mcp-studio/safety.js](api/_mcp-studio/safety.js) age-13+ content gate before any GPU work; backs the "three.ws 3D Studio" custom GPT ([prompts/store-submissions/_generated/openai-actions.yaml](prompts/store-submissions/_generated/openai-actions.yaml) + [openai-gpt-config.md](prompts/store-submissions/_generated/openai-gpt-config.md), store-submission prompt 12). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) |
| Paid Market Data API (x402, 17 endpoints) | Registry [api/_lib/market-data/registry.js](api/_lib/market-data/registry.js), fetchers [api/_lib/market-data/fetch.js](api/_lib/market-data/fetch.js), factory [api/_lib/market-data/endpoint.js](api/_lib/market-data/endpoint.js), routes `api/x402/market-*.js` `→ /api/x402/market-<category>`, free index [api/x402/market.js](api/x402/market.js) `→ /api/x402/market`, catalog projection [api/_lib/service-catalog/services/market-data.js](api/_lib/service-catalog/services/market-data.js), docs [docs/market-data-api.md](docs/market-data-api.md) `→ /docs/market-data-api` | Live | Every free /markets feed (coins, coin profile, price history, categories, exchanges, derivatives, global+Fear&Greed, ETH gas, trending, DeFi TVL, chains, ~15k yield pools, stablecoins, fees/revenue, DEX volumes, hacks) wrapped as pay-per-call x402 endpoints at $0.001 USDC (Solana/Base), plus the $0.005 one-call `market-pulse` bundle. One registry drives the live 402s, the discovery-doc listings, and the free index — zero drift by construction; the fetchers delegate to the SAME exported builders the free pages use (`api/coin/*`, `api/defi/*`), so paid data always matches the site. Params rejected pre-settle (422) and upstream outages (503) never charge the buyer. Tests: [tests/market-data-api.test.js](tests/market-data-api.test.js). |
| Datapoint fabric (x402, 480k+ endpoints) | Registry [api/_lib/market-data/datapoints.js](api/_lib/market-data/datapoints.js), dynamic route [api/x402/d/[...path].js](api/x402/d/%5B...path%5D.js) `→ /api/x402/d/<family>/<id>/<metric>`, free catalog [api/x402/d/index.js](api/x402/d/index.js) `→ /api/x402/d`, discovery slice `buildDatapointItems` in [api/wk.js](api/wk.js), docs § in [docs/market-data-api.md](docs/market-data-api.md#the-datapoint-fabric--480000-standalone-endpoints) | Live | Every individual market datapoint as its OWN standalone paid endpoint — one URL = one value = one $0.0005 USDC x402 micro-payment (override `X402_PRICE_DATAPOINT_<FAMILY>`). 9 families × 68 metrics × live id spaces ≈ 484k addressable endpoints (~17.5k coins × 20, ~15.5k pools × 7, ~6k protocols × 6, chains, stablecoins, exchanges, global/gas/fear-greed) served by ONE dynamic route reading the registry; ids are runtime values, nothing hardcodes a third-party asset. Path that cannot exist → 404/422 with NO 402 issued; unknown id/outage rejects pre-settle. Free catalog enumerates families, metrics, prices, and pages each family's full live id space (200/page) so crawlers can walk the universe; the .well-known discovery doc carries a curated runtime-derived slice (~83 concrete resources). Tests: [tests/market-datapoints.test.js](tests/market-datapoints.test.js). |
diff --git a/api/3d/look.js b/api/3d/look.js
new file mode 100644
index 000000000..66e448b2b
--- /dev/null
+++ b/api/3d/look.js
@@ -0,0 +1,154 @@
+// POST /api/3d/look + GET /api/3d/look
+//
+// Let an agent SEE a 3D model. Give it a GLB URL; it renders the model from
+// several angles, persists the frames, and answers with image URLs plus the
+// geometry facts and a plain-language reading of them.
+//
+// Why this route exists: every text-to-3D API, ours included, has always
+// answered with a link to a binary the caller cannot open. A human clicks it.
+// An agent cannot. So an agent generating 3D has had no way to check its own
+// work, which is why agentic 3D has been stuck at one shot and a shrug. Give
+// the agent frames and the loop closes: generate, look, judge, refine.
+//
+// Free and keyless, like the rest of /api/3d. Rendering holds a headless
+// browser for seconds, so it draws on the shared render bucket rather than
+// adding unmetered capacity.
+//
+// POST { glb_url, views?, size?, stats? }
+// → 200 { model_url, size, views:[{view,theta,phi,image_url}], missing_views?,
+// stats?, notes?, viewer_url, ar_url }
+// → 400 { error:'invalid_url' | 'invalid_request', message }
+// → 422 { error:'render_failed', message } (the model could not be drawn)
+// → 429 { error:'rate_limited', message, retry_after }
+//
+// GET → the discovery doc: views, limits, and a runnable example.
+//
+// The MCP twin of this route (look_at_model, api/_mcp-studio/tools.js) returns
+// the SAME frames as MCP image content blocks, which is what actually puts the
+// picture in front of a vision-capable model rather than a link to one.
+
+import { cors, wrap, json, readJson } from '../_lib/http.js';
+import { limits, clientIp } from '../_lib/rate-limit.js';
+import { renderTurntable, describeGeometry, VIEW_ANGLES, DEFAULT_VIEWS, MAX_VIEWS, MIN_SIZE, MAX_SIZE, DEFAULT_SIZE } from '../_lib/3d-vision.js';
+import { persistImageBytes } from '../_lib/image-persist.js';
+import { originFromReq, viewerUrl, arLaunchUrl } from '../_mcp-studio/gpt-forge-client.js';
+
+const MAX_BODY_BYTES = 4_000;
+
+// Geometry facts come from the free inspector rather than a second glTF parser
+// here, so "what this model is" has exactly one implementation. It is
+// best-effort: an inspector hiccup costs the caller its stats, never its
+// frames, because the frames are the thing that could not be got any other way.
+async function statsFor(base, glbUrl) {
+ try {
+ const res = await fetch(`${base}/api/3d/inspect?url=${encodeURIComponent(glbUrl)}`, {
+ headers: { accept: 'application/json' },
+ signal: AbortSignal.timeout(20_000),
+ });
+ if (!res.ok) return null;
+ const body = await res.json();
+ return body?.stats && typeof body.stats === 'object' ? body.stats : null;
+ } catch {
+ return null;
+ }
+}
+
+function discovery(base) {
+ return {
+ route: '/api/3d/look',
+ summary: 'Render a 3D model from several angles so an AI agent can see and judge it.',
+ free: true,
+ views: Object.fromEntries(Object.entries(VIEW_ANGLES).map(([k, v]) => [k, `theta ${v.theta}, phi ${v.phi}`])),
+ defaults: { views: DEFAULT_VIEWS, size: DEFAULT_SIZE },
+ limits: { max_views: MAX_VIEWS, min_size: MIN_SIZE, max_size: MAX_SIZE },
+ example: {
+ method: 'POST',
+ body: { glb_url: 'https://example.com/model.glb', views: ['three-quarter', 'back'], size: 512 },
+ },
+ mcp_equivalent: {
+ server: `${base}/api/mcp-studio`,
+ tool: 'look_at_model',
+ note: 'Returns the same frames as MCP image content blocks, viewable directly by a multimodal model.',
+ },
+ docs: `${base}/docs/3d-vision`,
+ };
+}
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
+ const base = originFromReq(req);
+
+ if (req.method === 'GET' || req.method === 'HEAD') {
+ return json(res, 200, discovery(base), { 'cache-control': 'public, max-age=300' });
+ }
+ if (req.method !== 'POST') {
+ res.setHeader('allow', 'GET, POST');
+ return json(res, 405, { error: 'method_not_allowed', message: 'Use POST with a glb_url, or GET for the discovery doc.' });
+ }
+
+ let body;
+ try {
+ body = await readJson(req, MAX_BODY_BYTES);
+ } catch (err) {
+ return json(res, err?.status === 413 ? 413 : 400, {
+ error: 'invalid_request',
+ message: err?.status === 413 ? 'Request body too large.' : 'Send a JSON body: { "glb_url": "https://..." }.',
+ });
+ }
+
+ const glbUrl = typeof body?.glb_url === 'string' ? body.glb_url.trim() : '';
+ if (!/^https:\/\//i.test(glbUrl)) {
+ return json(res, 400, { error: 'invalid_url', message: '"glb_url" must be a public https URL to a .glb file.' });
+ }
+
+ const rl = await limits.renderIp(clientIp(req));
+ if (!rl.success) {
+ const retryAfter = Math.max(1, Math.ceil((rl.reset - Date.now()) / 1000));
+ res.setHeader('retry-after', String(retryAfter));
+ return json(res, 429, {
+ error: 'rate_limited',
+ message: 'Too many renders from this address; try again shortly.',
+ retry_after: retryAfter,
+ });
+ }
+
+ let turntable;
+ try {
+ turntable = await renderTurntable({ glbUrl, views: body?.views, size: body?.size });
+ } catch (err) {
+ // A caller-supplied URL that is unreachable, not a GLB, or points somewhere
+ // private is the caller's problem to fix, not a server fault: say which.
+ const code = err?.code === 'render_failed' ? 422 : 400;
+ return json(res, code, {
+ error: err?.code === 'render_failed' ? 'render_failed' : 'invalid_url',
+ message: String(err?.message || 'could not render this model').slice(0, 300),
+ });
+ }
+
+ const views = [];
+ for (const frame of turntable.frames) {
+ views.push({
+ view: frame.view,
+ theta: frame.theta,
+ phi: frame.phi,
+ image_url: await persistImageBytes(frame.png),
+ });
+ }
+
+ const wantStats = body?.stats !== false;
+ const stats = wantStats ? await statsFor(base, glbUrl) : null;
+
+ return json(res, 200, {
+ model_url: glbUrl,
+ size: turntable.size,
+ views,
+ ...(turntable.failed.length ? { missing_views: turntable.failed } : {}),
+ ...(stats ? { stats, notes: describeGeometry(stats) } : {}),
+ viewer_url: viewerUrl(base, glbUrl),
+ ar_url: arLaunchUrl(base, glbUrl),
+ });
+});
+
+// Rendering several frames on one shared browser is seconds of work, not
+// milliseconds; give it room rather than truncating a turntable mid-set.
+export const config = { maxDuration: 120 };
diff --git a/api/_lib/3d-vision.js b/api/_lib/3d-vision.js
new file mode 100644
index 000000000..a62f4474c
--- /dev/null
+++ b/api/_lib/3d-vision.js
@@ -0,0 +1,140 @@
+// Machine vision for 3D: turn a GLB into something an AI agent can actually see.
+//
+// Every text-to-3D API in existence answers with a URL to a binary file. The
+// agent that asked for the model cannot open it, cannot judge it, and cannot
+// tell a clean mesh from a melted one. It has to hand the link to a human and
+// hope. That blindness is the reason agentic 3D stalls at one shot: there is no
+// feedback signal to iterate on.
+//
+// This module closes the loop. It renders a model from several angles and
+// returns the frames as image bytes, so a vision-capable agent (MCP image
+// content blocks, or any multimodal API) LOOKS at the thing it just made,
+// forms an opinion, and fixes it. Paired with the geometry facts below, an
+// agent can answer the questions it could never answer before: is the subject
+// complete, is it facing the right way, is the topology sane, is it the size it
+// claims to be.
+//
+// The renderer is the platform's own headless pipeline (avatar-render.js), the
+// same one the quality gate and the avatar studio use, so a frame here is the
+// frame every other surface would produce. Nothing new holds a GPU.
+
+import { renderAvatarScene, SCENE_PRESETS } from './avatar-render.js';
+import { assertSafePublicUrl } from './ssrf-guard.js';
+
+// Camera angles, in the renderer's orbit terms: `theta` swings around the
+// model, `phi` is the polar angle (90 is eye level, smaller looks down).
+//
+// The default set is chosen to be the smallest number of frames that answers
+// "is this model good": the three-quarter reads form and depth the way a
+// product shot does, front and side catch asymmetry and collapsed faces, and
+// back catches the half of the model a single-view generator most often leaves
+// unfinished. More frames cost render seconds and agent context for very
+// little extra signal.
+export const VIEW_ANGLES = Object.freeze({
+ front: { theta: 0, phi: 80 },
+ 'three-quarter': { theta: 35, phi: 78 },
+ side: { theta: 90, phi: 80 },
+ back: { theta: 180, phi: 80 },
+ top: { theta: 0, phi: 25 },
+ bottom: { theta: 0, phi: 155 },
+});
+
+export const DEFAULT_VIEWS = Object.freeze(['three-quarter', 'front', 'side', 'back']);
+export const MAX_VIEWS = 6;
+export const MIN_SIZE = 128;
+export const MAX_SIZE = 1024;
+export const DEFAULT_SIZE = 512;
+
+export function isKnownView(name) {
+ return Object.hasOwn(VIEW_ANGLES, String(name));
+}
+
+// Normalize a caller's view list: unknown names are dropped rather than
+// failing the call (an agent guessing "left" should still get its render), the
+// order the caller asked for is preserved, duplicates collapse, and an empty
+// result falls back to the default set instead of rendering nothing.
+export function normalizeViews(requested) {
+ if (!Array.isArray(requested) || requested.length === 0) return [...DEFAULT_VIEWS];
+ const seen = new Set();
+ const out = [];
+ for (const name of requested) {
+ const key = String(name || '').trim().toLowerCase();
+ if (!isKnownView(key) || seen.has(key)) continue;
+ seen.add(key);
+ out.push(key);
+ if (out.length >= MAX_VIEWS) break;
+ }
+ return out.length ? out : [...DEFAULT_VIEWS];
+}
+
+export function normalizeSize(requested) {
+ const n = Math.round(Number(requested));
+ if (!Number.isFinite(n)) return DEFAULT_SIZE;
+ return Math.max(MIN_SIZE, Math.min(MAX_SIZE, n));
+}
+
+// Render one model from several angles.
+//
+// Frames are produced SEQUENTIALLY on purpose. The renderer drives one shared
+// headless browser; firing four pages at it in parallel is how you turn a
+// 4-second turntable into an out-of-memory kill under any real concurrency.
+// A failed frame is recorded and skipped rather than failing the whole set:
+// three good views beat an error, and the caller is told which angle is missing.
+export async function renderTurntable({ glbUrl, views, size, background = 'transparent' } = {}) {
+ await assertSafePublicUrl(glbUrl);
+ const names = normalizeViews(views);
+ const dim = normalizeSize(size);
+ const frames = [];
+ const failed = [];
+ for (const name of names) {
+ const orbit = VIEW_ANGLES[name];
+ try {
+ const { png } = await renderAvatarScene({
+ glbUrl,
+ width: dim,
+ height: dim,
+ background,
+ cameraOrbit: { theta: orbit.theta, phi: orbit.phi, radius: null },
+ // 'full-body' frames the entire bounding box. The other presets crop
+ // to a humanoid's torso or head, which would silently cut a prop,
+ // a vehicle or a creature in half.
+ scenePreset: SCENE_PRESETS['full-body'],
+ });
+ frames.push({ view: name, ...orbit, png, bytes: png.length });
+ } catch (err) {
+ failed.push({ view: name, error: String(err?.message || err).slice(0, 160) });
+ }
+ }
+ if (!frames.length) {
+ const detail = failed[0]?.error || 'the renderer produced no frames';
+ throw Object.assign(new Error(`could not render this model: ${detail}`), { code: 'render_failed', failed });
+ }
+ return { frames, failed, size: dim };
+}
+
+// Plain-language reading of the geometry, for an agent that has the numbers but
+// no intuition for what they mean. Every line is derived from the stats the
+// inspector already returns; nothing here guesses at quality it cannot measure.
+export function describeGeometry(stats) {
+ if (!stats || typeof stats !== 'object') return [];
+ const notes = [];
+ const tris = Number(stats.triangles);
+ if (Number.isFinite(tris) && tris > 0) {
+ const band =
+ tris < 2_000
+ ? 'very light, suitable for a distant prop or a low-end device'
+ : tris < 60_000
+ ? 'a normal real-time budget for a hero prop or character'
+ : tris < 300_000
+ ? 'heavy for real time; consider decimating before shipping to a game or the web'
+ : 'far above a real-time budget; this is a render or print asset, not a game asset';
+ notes.push(`${tris.toLocaleString('en-US')} triangles, ${band}.`);
+ }
+ const mats = Number(stats.materials);
+ if (Number.isFinite(mats) && mats > 8) {
+ notes.push(`${mats} materials means at least that many draw calls; merging identical ones is usually free performance.`);
+ }
+ if (stats.animations > 0) notes.push(`Carries ${stats.animations} animation clip(s).`);
+ if (stats.textures === 0) notes.push('No textures: the surface is untextured or vertex-coloured only.');
+ return notes;
+}
diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.js
index df5fa3b55..3116f670f 100644
--- a/api/_mcp-studio/tools.js
+++ b/api/_mcp-studio/tools.js
@@ -43,6 +43,7 @@ import {
directPrompt,
} from './gpt-forge-client.js';
import { COMPONENT_URI } from './component.js';
+import { renderTurntable, describeGeometry } from '../_lib/3d-vision.js';
import { buildSpatialArtifact } from '../_lib/spatial-mcp.js';
// Pure, dependency-free lineage core — the SAME module the paid stdio server's
// runRefineModel uses (mcp-server/src/tools/_lineage.js), so conversational
@@ -653,6 +654,88 @@ function widgetMeta(invoking, invoked) {
};
}
+// look_at_model: the one tool in this server that hands the model back a
+// PICTURE instead of a link.
+//
+// MCP content blocks can carry images, and a multimodal client renders them
+// straight into the conversation, so the frames below are literally seen by the
+// model that asked for them. That is the whole point: until now an agent that
+// generated a 3D asset had no way to check its own work, because a .glb is
+// opaque to it. With frames in hand it can answer "is the subject complete, is
+// the back finished, did I get a teapot or a lump" and then fix it, which turns
+// one-shot generation into a loop.
+//
+// Frames are capped at 512 px and four views by default: enough for a model to
+// judge form and completeness, small enough not to flood the caller's context.
+// Geometry from the free inspector, best-effort: a hiccup there costs the
+// caller its numbers, never its frames.
+async function lookStats(base, glbUrl) {
+ try {
+ const res = await fetch(`${base}/api/3d/inspect?url=${encodeURIComponent(glbUrl)}`, {
+ headers: { accept: 'application/json' },
+ signal: AbortSignal.timeout(20_000),
+ });
+ if (!res.ok) return null;
+ const body = await res.json();
+ return body?.stats && typeof body.stats === 'object' ? body.stats : null;
+ } catch {
+ return null;
+ }
+}
+
+async function handleLookAtModel(args, _auth, req) {
+ const base = originFromReq(req);
+ const glbUrl = String(args?.glb_url || '').trim();
+ if (!/^https:\/\//i.test(glbUrl)) {
+ return toolError('glb_url must be a public https URL to a .glb file.');
+ }
+
+ let turntable;
+ try {
+ turntable = await renderTurntable({ glbUrl, views: args?.views, size: args?.size ?? 512 });
+ } catch (err) {
+ return toolError(String(err?.message || 'could not render this model').slice(0, 300));
+ }
+
+ const stats = await lookStats(base, glbUrl);
+ const notes = describeGeometry(stats);
+ const shown = turntable.frames.map((f) => f.view).join(', ');
+ const missing = turntable.failed.length ? ` Could not render: ${turntable.failed.map((f) => f.view).join(', ')}.` : '';
+
+ // The text block frames what the model is about to look at, then every frame
+ // follows as an image block, each announced by name so the model can talk
+ // about "the back view" rather than "the third image".
+ const content = [
+ {
+ type: 'text',
+ text:
+ `Rendered this model from ${turntable.frames.length} angle(s): ${shown}.${missing}\n` +
+ (notes.length ? `Geometry: ${notes.join(' ')}\n` : '') +
+ 'Look at the frames below and judge the model: is the subject complete and recognisable, ' +
+ 'is the far side finished, is anything melted, fused, or missing? If it needs work, generate ' +
+ 'again with a prompt that names the specific fault.',
+ },
+ ];
+ for (const frame of turntable.frames) {
+ content.push({ type: 'text', text: `View: ${frame.view} (theta ${frame.theta}, phi ${frame.phi})` });
+ content.push({ type: 'image', data: frame.png.toString('base64'), mimeType: 'image/png' });
+ }
+
+ return {
+ content,
+ structuredContent: {
+ ok: true,
+ model_url: glbUrl,
+ size: turntable.size,
+ views: turntable.frames.map((f) => ({ view: f.view, theta: f.theta, phi: f.phi })),
+ ...(turntable.failed.length ? { missing_views: turntable.failed } : {}),
+ ...(stats ? { stats, notes } : {}),
+ viewer_url: viewerUrl(base, glbUrl),
+ ar_url: arLaunchUrl(base, glbUrl),
+ },
+ };
+}
+
const DEFS = [
{
name: 'forge_free',
@@ -838,6 +921,49 @@ const DEFS = [
_meta: widgetMeta('Checking your 3D model…', 'Here is your 3D model'),
handler: handleCheckJob,
},
+ {
+ name: 'look_at_model',
+ title: 'Look at a 3D model',
+ description:
+ 'FREE. See a 3D model instead of just linking to it. Renders the GLB from several angles and returns ' +
+ 'the frames as images you can actually look at, plus its geometry (triangles, materials, textures) and ' +
+ 'a plain reading of what those numbers mean. Use it right after generating to check your own work: is ' +
+ 'the subject complete, is the back finished, is anything melted or fused? Then regenerate naming the ' +
+ 'fault you saw. Works on any public https .glb, not only ones made here.',
+ inputSchema: {
+ type: 'object',
+ additionalProperties: false,
+ required: ['glb_url'],
+ properties: {
+ glb_url: {
+ type: 'string',
+ minLength: 12,
+ maxLength: 2048,
+ description: 'Public https URL of the .glb to look at.',
+ },
+ views: {
+ type: 'array',
+ maxItems: 6,
+ items: { type: 'string', enum: ['front', 'three-quarter', 'side', 'back', 'top', 'bottom'] },
+ description: 'Angles to render. Default: three-quarter, front, side, back.',
+ },
+ size: {
+ type: 'integer',
+ minimum: 128,
+ maximum: 1024,
+ description: 'Pixel size of each square frame. Default 512.',
+ },
+ },
+ },
+ annotations: {
+ readOnlyHint: true, // renders a picture; changes nothing
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: true,
+ },
+ _meta: widgetMeta('Looking at your 3D model…', 'Here is what the model looks like'),
+ handler: handleLookAtModel,
+ },
];
// Schemas for tools/list — strip the handler (and any server-only field).
diff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.js
index a8a00ad8a..fb73ecfd4 100644
--- a/api/_okx3d/forge.js
+++ b/api/_okx3d/forge.js
@@ -41,11 +41,14 @@ import { catalogEntry, FORGE_TOOL, FORGE_STATUS_TOOL } from '../_lib/okx-catalog
import { startForge, pollOnce, originFromReq } from '../_mcp-studio/gpt-forge-client.js';
import { shapeSubmit, shapePoll, tierOf } from '../_mcp-studio/studio-shape.js';
import { checkPromptSafety } from '../_mcp-studio/safety.js';
+import { renderTurntable, describeGeometry } from '../_lib/3d-vision.js';
export { PROTOCOL_VERSION, FORGE_TOOL, FORGE_STATUS_TOOL };
const BASE = 'https://three.ws';
const STATUS_ENDPOINT = `${BASE}/api/okx/3d/forge-status`;
+// Free on every endpoint: the buyer can see what it bought.
+const LOOK_TOOL = 'look_at_model';
const DOCS_URL = `${BASE}/docs/okx-marketplace`;
// Every listed forge row. A row not in this set is not servable here.
@@ -345,19 +348,92 @@ function forgeBazaarExtension(entry, paidTool) {
const ajv = new Ajv({ allErrors: false, strict: false });
addFormats(ajv);
+
+// look_at_model: free on every forge endpoint.
+//
+// A buyer who pays for a model and receives a URL is in exactly the bind this
+// whole marketplace was built to solve: it cannot open the file it just bought.
+// MCP image content blocks can carry the render, so the buying agent LOOKS at
+// its purchase, confirms it got what it paid for, and can ask for a different
+// prompt if it did not. No other seller on this marketplace can hand an agent
+// a picture of the goods.
+function buildLookTool() {
+ return {
+ name: LOOK_TOOL,
+ title: 'Look at a 3D model (free)',
+ description:
+ 'FREE. See a model instead of just holding a link to it. Renders the GLB from several angles and ' +
+ 'returns the frames as images you can actually look at, plus its geometry and a plain reading of ' +
+ 'what the numbers mean. Use it on anything this service returned to confirm you got what you paid ' +
+ 'for, or on any other public https .glb.',
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+ inputSchema: {
+ type: 'object',
+ required: ['glb_url'],
+ additionalProperties: false,
+ properties: {
+ glb_url: { type: 'string', minLength: 12, maxLength: 2048 },
+ views: {
+ type: 'array',
+ maxItems: 6,
+ items: { type: 'string', enum: ['front', 'three-quarter', 'side', 'back', 'top', 'bottom'] },
+ },
+ size: { type: 'integer', minimum: 128, maximum: 1024 },
+ },
+ },
+ async handler(args) {
+ const glbUrl = String(args?.glb_url || '').trim();
+ if (!/^https:\/\//i.test(glbUrl)) {
+ return toolError('invalid_url', 'glb_url must be a public https URL to a .glb file.');
+ }
+ let turntable;
+ try {
+ turntable = await renderTurntable({ glbUrl, views: args?.views, size: args?.size ?? 512 });
+ } catch (err) {
+ return toolError('render_failed', String(err?.message || 'could not render this model').slice(0, 300));
+ }
+ const shown = turntable.frames.map((f) => f.view).join(', ');
+ const content = [
+ {
+ type: 'text',
+ text:
+ `Rendered from ${turntable.frames.length} angle(s): ${shown}. ` +
+ 'Look at the frames below: is the subject complete and recognisable, is the far side ' +
+ 'finished, is anything melted or fused?',
+ },
+ ];
+ for (const frame of turntable.frames) {
+ content.push({ type: 'text', text: `View: ${frame.view}` });
+ content.push({ type: 'image', data: frame.png.toString('base64'), mimeType: 'image/png' });
+ }
+ return {
+ content,
+ structuredContent: {
+ ok: true,
+ model_url: glbUrl,
+ size: turntable.size,
+ views: turntable.frames.map((f) => ({ view: f.view, theta: f.theta, phi: f.phi })),
+ ...(turntable.failed.length ? { missing_views: turntable.failed } : {}),
+ },
+ };
+ },
+ };
+}
+
function buildSurface(id) {
const entry = catalogEntry(id);
if (!entry) throw new Error(`okx forge: no catalog entry "${id}"`);
const paid = entry.priceUsd !== '0';
const paidTool = paid ? buildForgeTool(entry) : null;
const statusTool = buildStatusTool();
+ const lookTool = buildLookTool();
const gettingStarted = buildGettingStartedTool({
server: `three.ws Forge, ${entry.name}`,
tagline:
'Text or images to a real, downloadable 3D model (GLB), with a browser preview and an ' +
'augmented-reality link that places it in a real room.',
- tools: [paidTool, statusTool].filter(Boolean),
+ tools: [paidTool, statusTool, lookTool].filter(Boolean),
priceFor: (name) => (paid && name === FORGE_TOOL ? { amount_usdc: Number(entry.priceUsd) } : null),
access: paid
? [
@@ -378,7 +454,7 @@ function buildSurface(id) {
},
});
- const toolDefs = [gettingStarted, ...(paidTool ? [paidTool] : []), statusTool];
+ const toolDefs = [gettingStarted, ...(paidTool ? [paidTool] : []), statusTool, lookTool];
const TOOL_CATALOG = toolDefs.map(({ handler, scope, ...pub }) => pub);
const TOOLS = Object.fromEntries(
toolDefs.map((d) => [
@@ -410,7 +486,7 @@ function buildSurface(id) {
TOOLS,
// Free tools servable to the anonymous principal with no OAuth/x402:
// discovery plus status polling. The paid tool is deliberately not here.
- isPublicTool: (name) => name === GETTING_STARTED_TOOL || name === FORGE_STATUS_TOOL,
+ isPublicTool: (name) => name === GETTING_STARTED_TOOL || name === FORGE_STATUS_TOOL || name === LOOK_TOOL,
// x402 price (atomic USDC string) for one tools/call, or null when free.
x402Amount: (toolName) => (paid && toolName === FORGE_TOOL ? entry.amountAtomics : null),
dispatch: makeDispatcher({
diff --git a/data/changelog.json b/data/changelog.json
index 69af97fc2..402519bd9 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-28",
+ "title": "AI agents can now see the 3D models they make",
+ "summary": "Until today every 3D generator on the internet, ours included, answered with a link to a file an AI agent cannot open. A person clicks it; an agent is blind to it, which is why an agent that makes a 3D model has never been able to tell a clean one from a melted one. That changes now: ask to look at any model and it comes back rendered from four angles as actual pictures the agent sees, with the geometry explained in plain language. An agent can finally check its own work, spot that the back of the model was never finished, and try again saying exactly what was wrong. It works over MCP, over a plain web request, and through a new open-source package called @three-ws/see, and it is free, including for agents that bought a model from us and want to confirm they got what they paid for.",
+ "tags": [
+ "feature",
+ "sdk"
+ ],
+ "link": "/docs/3d-vision"
+ },
{
"date": "2026-08-28",
"title": "The Seeker app now runs full-screen, and its release process is written down",
diff --git a/data/pages.json b/data/pages.json
index d481b1c8f..012cae35c 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -4050,6 +4050,14 @@
"changefreq": "monthly",
"added": "2026-07-30"
},
+ {
+ "path": "/docs/3d-vision",
+ "title": "Docs \u00b7 3D Vision: let an agent see the model",
+ "description": "Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-08-28"
+ },
{
"path": "/docs/3d-api",
"title": "Docs · The three.ws 3D API",
diff --git a/docs/3d-vision.md b/docs/3d-vision.md
new file mode 100644
index 000000000..eb3a0c078
--- /dev/null
+++ b/docs/3d-vision.md
@@ -0,0 +1,122 @@
+# 3D Vision: let an agent see the model
+
+Every text-to-3D API, this platform's included, has always answered with a URL to a binary file. A human clicks it. **An agent cannot.** A `.glb` is opaque to a language model, so the agent that just spent GPU time generating an asset has no way to tell a clean mesh from a melted one. It hands the link to a human and hopes.
+
+That blindness is the reason agentic 3D stalls at one shot. There is no feedback signal to iterate on.
+
+This surface closes the loop. Give it a model, get back **frames a vision-capable model can actually look at**, plus the geometry facts and a plain reading of them. Generate, look, judge, fix.
+
+Free and keyless, like the rest of [the 3D API](./3d-api.md).
+
+---
+
+## Three ways in
+
+| You are | Use | You get |
+| --- | --- | --- |
+| An MCP client (Claude, any MCP host) | tool `look_at_model` on `/api/mcp-studio` | Frames as **MCP image content blocks**, rendered into the conversation |
+| A Node program | [`@three-ws/see`](../packages/see/README.md) | `see(url)` → views, stats, notes |
+| Anything that speaks HTTP | `POST /api/3d/look` | JSON with a frame URL per angle |
+
+---
+
+## MCP: the model sees the model
+
+This is the one that matters. MCP content blocks can carry images, so a multimodal client renders the frames straight into the conversation. The agent is not told about its model; it **looks** at it.
+
+```json
+{
+ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
+ "params": {
+ "name": "look_at_model",
+ "arguments": { "glb_url": "https://example.com/robot.glb" }
+ }
+}
+```
+
+The reply opens with a text block naming what was rendered and what to judge, then one labelled text block and one `image` block per angle. A client that supports images shows them; the model forms an opinion and can immediately regenerate naming the specific fault it saw.
+
+Works on **any** public https `.glb`, not only models generated here.
+
+## REST
+
+```bash
+curl -sS -X POST https://three.ws/api/3d/look \
+ -H 'content-type: application/json' \
+ -d '{"glb_url":"https://example.com/robot.glb"}'
+```
+
+```json
+{
+ "model_url": "https://example.com/robot.glb",
+ "size": 512,
+ "views": [
+ { "view": "three-quarter", "theta": 35, "phi": 78, "image_url": "https://…/a.png" },
+ { "view": "front", "theta": 0, "phi": 80, "image_url": "https://…/b.png" },
+ { "view": "side", "theta": 90, "phi": 80, "image_url": "https://…/c.png" },
+ { "view": "back", "theta": 180, "phi": 80, "image_url": "https://…/d.png" }
+ ],
+ "stats": { "vertices": 8231, "triangles": 12400, "materials": 2, "textures": 1, "animations": 0 },
+ "notes": ["12,400 triangles, a normal real-time budget for a hero prop or character."],
+ "viewer_url": "https://three.ws/viewer?src=…",
+ "ar_url": "https://three.ws/api/ar?src=…"
+}
+```
+
+`GET /api/3d/look` returns a discovery doc: every angle, the limits, and a runnable example.
+
+## SDK
+
+```bash
+npm install @three-ws/see
+```
+
+```js
+import { see, toMessageContent } from '@three-ws/see';
+
+const look = await see('https://example.com/robot.glb');
+const content = await toMessageContent(look); // multimodal chat blocks, ready to send
+```
+
+Full API, including the generate → look → critique loop against the Claude API: [`packages/see/README.md`](../packages/see/README.md).
+
+---
+
+## The angles, and why these ones
+
+| View | Camera | What it catches |
+| --- | --- | --- |
+| `three-quarter` | theta 35, phi 78 | Form and depth, the way a product shot reads. Rendered first because it is the single most informative frame. |
+| `front` | theta 0, phi 80 | Facing, symmetry, the subject's identity |
+| `side` | theta 90, phi 80 | Profile, depth collapse, flattened geometry |
+| `back` | theta 180, phi 80 | The half a single-view generator most often leaves unfinished |
+| `top` | theta 0, phi 25 | Footprint, layout, whether it is hollow |
+| `bottom` | theta 0, phi 155 | Missing caps, inverted normals, floating geometry |
+
+The default set is `three-quarter, front, side, back`: the smallest number of frames that answers "is this model good". More frames cost render seconds and agent context for very little extra signal, which is why the cap is six.
+
+Every frame uses the `full-body` scene preset, which fits the whole bounding box. The humanoid presets crop to a torso or head and would silently cut a prop, a vehicle or a creature in half.
+
+## What it is honest about
+
+- **A partial turntable is not a failure.** If one angle fails to render you get the frames that worked plus `missing_views` naming what did not. Three good views beat an error.
+- **Stats are best-effort.** They come from [`/api/3d/inspect`](./3d-api.md), so "what this model is" has exactly one implementation. An inspector hiccup costs you the numbers, never the frames, because the frames are the part you could not get any other way.
+- **Unknown angle names are ignored, not rejected.** An agent guessing `"left"` still gets a useful turntable.
+- **Nothing is invented.** The geometry reading is derived from measured stats; it never guesses at quality it cannot measure. Judging whether the model is *good* is the vision model's job, which is the entire point.
+
+## Limits
+
+| Limit | Value | Why |
+| --- | --- | --- |
+| Views per call | 6 | Each frame is seconds of headless render |
+| Frame size | 128 to 1024 px | 512 is enough for a model to judge form |
+| Rate | shared render bucket, 60 per 10 min per IP | Rendering holds a CPU for seconds; this is a real cost ceiling |
+| Model URL | public `https://` only | SSRF-guarded before anything is fetched |
+
+Frames render **sequentially**. The renderer drives one shared headless browser; firing four pages at it in parallel turns a 4-second turntable into an out-of-memory kill under any real concurrency.
+
+## Related
+
+- [Free 3D API](./3d-api.md): generate and inspect
+- [MCP servers](./mcp.md): every tool on `/api/mcp-studio`
+- [OKX.AI marketplace](./okx-marketplace.md): paid 3D for agents that buy it
diff --git a/packages/see/LICENSE b/packages/see/LICENSE
new file mode 100644
index 000000000..dff21b7f4
--- /dev/null
+++ b/packages/see/LICENSE
@@ -0,0 +1,20 @@
+Copyright 2026 nirholas
+
+All rights reserved.
+
+This software is proprietary and may not be used, copied, modified, distributed,
+translated, or made available to any third party without the express written
+permission of the copyright owner.
+
+No rights are granted by implication, estoppel, or otherwise. Use of this
+software is subject to the terms of a separate license agreement with the
+copyright owner.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT OWNER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
diff --git a/packages/see/README.md b/packages/see/README.md
new file mode 100644
index 000000000..3dddf0a9e
--- /dev/null
+++ b/packages/see/README.md
@@ -0,0 +1,117 @@
+# @three-ws/see
+
+**Give an AI agent eyes for 3D.**
+
+Every text-to-3D API on earth answers with a URL to a binary file. A human clicks it. An agent cannot: a `.glb` is opaque to a language model, so the agent that just generated an asset has no way to check its own work. That is why agentic 3D has been stuck at one shot and a shrug.
+
+This package closes the loop in one call. Hand it a GLB URL and get back frames of the model rendered from several angles, ready to put in front of any multimodal model, plus the geometry facts and a plain reading of what they mean.
+
+```
+npm install @three-ws/see
+```
+
+No key. No account. The service is free.
+
+## Look at a model
+
+```js
+import { see } from '@three-ws/see';
+
+const look = await see('https://example.com/robot.glb');
+
+look.views;
+// [ { view: 'three-quarter', theta: 35, phi: 78, imageUrl: 'https://…/a.png' },
+// { view: 'front', … }, { view: 'side', … }, { view: 'back', … } ]
+
+look.notes;
+// [ '12,400 triangles, a normal real-time budget for a hero prop or character.' ]
+
+look.stats; // { vertices, triangles, materials, textures, animations, … }
+look.viewerUrl; // spin it in a browser
+look.arUrl; // place it in a real room from a phone
+```
+
+## Close the loop: generate, look, judge, fix
+
+The reason this exists. An agent that can see its own output stops guessing.
+
+```js
+import Anthropic from '@anthropic-ai/sdk';
+import { see, toMessageContent } from '@three-ws/see';
+
+const anthropic = new Anthropic();
+
+async function critique(glbUrl, intent) {
+ const look = await see(glbUrl);
+ const message = await anthropic.messages.create({
+ model: 'claude-sonnet-5',
+ max_tokens: 512,
+ messages: [{
+ role: 'user',
+ content: [
+ { type: 'text', text: `This model was meant to be: ${intent}. Judge it. Is the subject complete and recognisable, is the far side finished, is anything melted or fused? If it needs work, say exactly what to change.` },
+ ...(await toMessageContent(look)),
+ ],
+ }],
+ });
+ return message.content[0].text;
+}
+```
+
+`toMessageContent` shapes a look into multimodal chat content: one labelled text block per angle followed by the image itself. It passes image URLs by default; `{ fetchImages: true }` inlines base64 for APIs that will not fetch a URL themselves.
+
+## Pick your angles
+
+```js
+await see(glbUrl, { views: ['back', 'top'], size: 768 });
+```
+
+| View | What it catches |
+| --- | --- |
+| `three-quarter` | Form and depth, the way a product shot reads (default first) |
+| `front` | Facing, symmetry, the subject's identity |
+| `side` | Profile, depth collapse, flattened geometry |
+| `back` | The half a single-view generator most often leaves unfinished |
+| `top` | Footprint, layout, whether it is hollow |
+| `bottom` | Missing caps, inverted normals, floating geometry |
+
+Up to six views per call, `size` from 128 to 1024 pixels (default 512). Unknown angle names are ignored rather than failing the call, so a guess still returns something useful.
+
+## Errors are typed
+
+```js
+import { see, SeeError } from '@three-ws/see';
+
+try {
+ await see(url);
+} catch (err) {
+ if (err instanceof SeeError && err.code === 'rate_limited') {
+ await new Promise((r) => setTimeout(r, err.retryAfter * 1000));
+ }
+}
+```
+
+`invalid_url`, `render_failed`, `rate_limited`, `timeout`, `unreachable`. A partially-rendered turntable is **not** an error: you get the frames that worked plus `look.missingViews` naming the angles that did not, because three good views beat a failure.
+
+## Options
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `views` | `['three-quarter','front','side','back']` | Up to 6, from the table above |
+| `size` | `512` | Square pixels, 128 to 1024 |
+| `stats` | `true` | Set false to skip the geometry pass |
+| `baseUrl` | `https://three.ws` | Point at another deployment |
+| `timeoutMs` | `120000` | Rendering holds a browser for seconds |
+| `fetch` | global `fetch` | Inject for tests, proxies, tracing |
+
+## Using MCP instead?
+
+The same capability is an MCP tool, `look_at_model`, on `https://three.ws/api/mcp-studio`. There the frames come back as MCP **image content blocks**, so a multimodal client renders them straight into the conversation and the model sees the model with no glue code at all.
+
+## Related
+
+- [three.ws/docs/3d-vision](https://three.ws/docs/3d-vision): the full surface, REST and MCP
+- [`POST /api/3d/look`](https://three.ws/api/3d/look): the endpoint underneath (GET it for a discovery doc)
+- [`@three-ws/retarget`](https://www.npmjs.com/package/@three-ws/retarget): retarget animation onto any humanoid GLB
+
+Apache-2.0.
diff --git a/packages/see/package.json b/packages/see/package.json
new file mode 100644
index 000000000..e45f812b3
--- /dev/null
+++ b/packages/see/package.json
@@ -0,0 +1,45 @@
+{
+ "name": "@three-ws/see",
+ "version": "0.1.0",
+ "description": "Let an AI agent SEE a 3D model: render any GLB from several angles and get back frames it can actually look at, plus the geometry facts.",
+ "type": "module",
+ "main": "./src/index.js",
+ "exports": {
+ ".": {
+ "import": "./src/index.js",
+ "default": "./src/index.js"
+ }
+ },
+ "files": [
+ "src",
+ "README.md",
+ "LICENSE"
+ ],
+ "license": "Apache-2.0",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/see"
+ },
+ "homepage": "https://three.ws/docs/3d-vision",
+ "keywords": [
+ "3d",
+ "glb",
+ "gltf",
+ "ai-agents",
+ "agent",
+ "vision",
+ "multimodal",
+ "mcp",
+ "render",
+ "turntable",
+ "text-to-3d",
+ "three.ws"
+ ],
+ "engines": {
+ "node": ">=18"
+ },
+ "scripts": {
+ "test": "node --test test/"
+ }
+}
diff --git a/packages/see/src/index.js b/packages/see/src/index.js
new file mode 100644
index 000000000..ec47ba3d3
--- /dev/null
+++ b/packages/see/src/index.js
@@ -0,0 +1,129 @@
+// @three-ws/see: give an AI agent eyes for 3D.
+//
+// Every text-to-3D API answers with a URL to a binary file. A human clicks it.
+// An agent cannot: a .glb is opaque to a language model, so the agent that
+// generated the asset has no way to check its own work. That is why agentic 3D
+// has been stuck at one shot and a shrug.
+//
+// This package closes the loop in one call: hand it a GLB URL, get back frames
+// of the model rendered from several angles, ready to put in front of any
+// multimodal model, plus the geometry facts and a plain reading of them.
+//
+// import { see } from '@three-ws/see';
+// const look = await see('https://example.com/robot.glb');
+// look.views; // [{ view:'three-quarter', imageUrl, theta, phi }, ...]
+// look.notes; // ['12,400 triangles, a normal real-time budget...']
+//
+// No key, no account. The service is free.
+
+const DEFAULT_BASE = 'https://three.ws';
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/** Every camera angle the renderer understands. */
+export const VIEWS = Object.freeze(['front', 'three-quarter', 'side', 'back', 'top', 'bottom']);
+
+export class SeeError extends Error {
+ constructor(message, { code = 'see_failed', status = null, retryAfter = null } = {}) {
+ super(message);
+ this.name = 'SeeError';
+ this.code = code;
+ this.status = status;
+ this.retryAfter = retryAfter;
+ }
+}
+
+/**
+ * Render a 3D model from several angles.
+ *
+ * @param {string} glbUrl Public https URL of a .glb.
+ * @param {object} [opts]
+ * @param {string[]} [opts.views] Angles to render; defaults to three-quarter, front, side, back.
+ * @param {number} [opts.size] Square frame size in pixels, 128 to 1024. Default 512.
+ * @param {boolean} [opts.stats] Include geometry stats. Default true.
+ * @param {string} [opts.baseUrl] Point at another deployment.
+ * @param {number} [opts.timeoutMs] Abort after this long. Default 120s.
+ * @param {typeof fetch} [opts.fetch] Inject a fetch (tests, proxies, tracing).
+ * @returns {Promise<{modelUrl:string,size:number,views:Array<{view:string,theta:number,phi:number,imageUrl:string}>,missingViews:Array<{view:string,error:string}>,stats:object|null,notes:string[],viewerUrl:string,arUrl:string}>}
+ */
+export async function see(glbUrl, opts = {}) {
+ const url = String(glbUrl || '').trim();
+ if (!/^https:\/\//i.test(url)) {
+ throw new SeeError('glbUrl must be a public https URL to a .glb file', { code: 'invalid_url' });
+ }
+ const base = String(opts.baseUrl || DEFAULT_BASE).replace(/\/$/, '');
+ const doFetch = opts.fetch || globalThis.fetch;
+ if (typeof doFetch !== 'function') {
+ throw new SeeError('no fetch implementation available; pass opts.fetch', { code: 'no_fetch' });
+ }
+
+ const body = { glb_url: url };
+ if (Array.isArray(opts.views) && opts.views.length) body.views = opts.views;
+ if (opts.size != null) body.size = opts.size;
+ if (opts.stats === false) body.stats = false;
+
+ let res;
+ try {
+ res = await doFetch(`${base}/api/3d/look`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json' },
+ body: JSON.stringify(body),
+ signal: AbortSignal.timeout(Number(opts.timeoutMs) || DEFAULT_TIMEOUT_MS),
+ });
+ } catch (err) {
+ const aborted = err?.name === 'TimeoutError' || err?.name === 'AbortError';
+ throw new SeeError(aborted ? 'rendering timed out' : `could not reach ${base}: ${err?.message || err}`, {
+ code: aborted ? 'timeout' : 'unreachable',
+ });
+ }
+
+ const payload = await res.json().catch(() => ({}));
+ if (!res.ok) {
+ throw new SeeError(payload?.message || `look failed with HTTP ${res.status}`, {
+ code: payload?.error || 'see_failed',
+ status: res.status,
+ retryAfter: payload?.retry_after ?? null,
+ });
+ }
+
+ return {
+ modelUrl: payload.model_url ?? url,
+ size: payload.size ?? null,
+ views: (payload.views || []).map((v) => ({ view: v.view, theta: v.theta, phi: v.phi, imageUrl: v.image_url })),
+ missingViews: payload.missing_views || [],
+ stats: payload.stats ?? null,
+ notes: payload.notes || [],
+ viewerUrl: payload.viewer_url ?? null,
+ arUrl: payload.ar_url ?? null,
+ };
+}
+
+/**
+ * The same look, shaped as multimodal chat content: one text block naming each
+ * angle followed by the image itself. Drop it straight into an Anthropic or
+ * OpenAI message and the model sees the model.
+ *
+ * Images are referenced by URL rather than inlined, so this stays cheap to
+ * build; `fetchImages: true` downloads and base64-encodes them for APIs that
+ * will not fetch a URL themselves.
+ *
+ * @param {Awaited<ReturnType<see>>} look
+ * @param {object} [opts]
+ * @param {boolean} [opts.fetchImages] Inline the bytes as base64 instead of URLs.
+ * @param {typeof fetch} [opts.fetch]
+ */
+export async function toMessageContent(look, opts = {}) {
+ const doFetch = opts.fetch || globalThis.fetch;
+ const content = [];
+ if (look.notes?.length) content.push({ type: 'text', text: `Geometry: ${look.notes.join(' ')}` });
+ for (const v of look.views || []) {
+ content.push({ type: 'text', text: `View: ${v.view}` });
+ if (opts.fetchImages) {
+ const res = await doFetch(v.imageUrl);
+ const buf = Buffer.from(await res.arrayBuffer());
+ content.push({ type: 'image', source: { type: 'base64', media_type: 'image/png', data: buf.toString('base64') } });
+ } else {
+ content.push({ type: 'image', source: { type: 'url', url: v.imageUrl } });
+ }
+ }
+ return content;
+}
diff --git a/packages/see/test/see.test.js b/packages/see/test/see.test.js
new file mode 100644
index 000000000..b77800db7
--- /dev/null
+++ b/packages/see/test/see.test.js
@@ -0,0 +1,97 @@
+// @three-ws/see: the contract an agent depends on.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { see, toMessageContent, VIEWS, SeeError } from '../src/index.js';
+
+const OK = {
+ model_url: 'https://cdn.test/robot.glb',
+ size: 512,
+ views: [
+ { view: 'three-quarter', theta: 35, phi: 78, image_url: 'https://cdn.test/a.png' },
+ { view: 'back', theta: 180, phi: 80, image_url: 'https://cdn.test/b.png' },
+ ],
+ stats: { triangles: 12400, materials: 2 },
+ notes: ['12,400 triangles, a normal real-time budget for a hero prop or character.'],
+ viewer_url: 'https://three.ws/viewer?src=x',
+ ar_url: 'https://three.ws/api/ar?src=x',
+};
+
+const jsonRes = (status, body) => ({ ok: status < 400, status, json: async () => body });
+
+test('rejects a non-https model URL before any network call', async () => {
+ let called = false;
+ await assert.rejects(
+ () => see('ftp://example.com/x.glb', { fetch: async () => { called = true; } }),
+ (e) => e instanceof SeeError && e.code === 'invalid_url',
+ );
+ assert.equal(called, false);
+});
+
+test('returns camelCase views, stats and links from the service payload', async () => {
+ const look = await see('https://cdn.test/robot.glb', { fetch: async () => jsonRes(200, OK) });
+ assert.equal(look.modelUrl, 'https://cdn.test/robot.glb');
+ assert.deepEqual(look.views.map((v) => v.view), ['three-quarter', 'back']);
+ assert.equal(look.views[0].imageUrl, 'https://cdn.test/a.png');
+ assert.equal(look.stats.triangles, 12400);
+ assert.equal(look.viewerUrl, 'https://three.ws/viewer?src=x');
+ assert.deepEqual(look.missingViews, []);
+});
+
+test('sends only the options the caller set, so service defaults stand', async () => {
+ let sent;
+ await see('https://cdn.test/robot.glb', {
+ fetch: async (_u, init) => { sent = JSON.parse(init.body); return jsonRes(200, OK); },
+ });
+ assert.deepEqual(sent, { glb_url: 'https://cdn.test/robot.glb' });
+
+ await see('https://cdn.test/robot.glb', {
+ views: ['back'], size: 256, stats: false,
+ fetch: async (_u, init) => { sent = JSON.parse(init.body); return jsonRes(200, OK); },
+ });
+ assert.deepEqual(sent, { glb_url: 'https://cdn.test/robot.glb', views: ['back'], size: 256, stats: false });
+});
+
+test('surfaces a rate limit as a typed error carrying retryAfter', async () => {
+ await assert.rejects(
+ () => see('https://cdn.test/robot.glb', {
+ fetch: async () => jsonRes(429, { error: 'rate_limited', message: 'slow down', retry_after: 42 }),
+ }),
+ (e) => e instanceof SeeError && e.code === 'rate_limited' && e.status === 429 && e.retryAfter === 42,
+ );
+});
+
+test('reports a partial turntable rather than hiding it', async () => {
+ const look = await see('https://cdn.test/robot.glb', {
+ fetch: async () => jsonRes(200, { ...OK, missing_views: [{ view: 'top', error: 'render timed out' }] }),
+ });
+ assert.equal(look.missingViews.length, 1);
+ assert.equal(look.missingViews[0].view, 'top');
+});
+
+test('shapes a look into multimodal content, one labelled image per angle', async () => {
+ const look = await see('https://cdn.test/robot.glb', { fetch: async () => jsonRes(200, OK) });
+ const content = await toMessageContent(look);
+ assert.equal(content[0].type, 'text');
+ assert.match(content[0].text, /Geometry:/);
+ const images = content.filter((c) => c.type === 'image');
+ assert.equal(images.length, 2);
+ assert.equal(images[0].source.url, 'https://cdn.test/a.png');
+ assert.equal(content[1].text, 'View: three-quarter');
+});
+
+test('inlines base64 when the target API will not fetch a URL', async () => {
+ const look = await see('https://cdn.test/robot.glb', { fetch: async () => jsonRes(200, OK) });
+ const content = await toMessageContent(look, {
+ fetchImages: true,
+ fetch: async () => ({ arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer }),
+ });
+ const img = content.find((c) => c.type === 'image');
+ assert.equal(img.source.type, 'base64');
+ assert.equal(img.source.media_type, 'image/png');
+ assert.equal(img.source.data, Buffer.from([1, 2, 3]).toString('base64'));
+});
+
+test('publishes the angle vocabulary so a caller need not guess', () => {
+ assert.ok(VIEWS.includes('three-quarter') && VIEWS.includes('bottom'));
+ assert.equal(VIEWS.length, 6);
+});
diff --git a/public/changelog.json b/public/changelog.json
index 0a20832f4..c604cf947 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-28T03:09:16.869Z",
+ "generated_at": "2026-08-28T03:26:00.152Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -16,6 +16,16 @@
"launch"
]
},
+ {
+ "date": "2026-08-28",
+ "type": "launch",
+ "title": "Docs · 3D Vision: let an agent see the model",
+ "summary": "Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.",
+ "link": "/docs/3d-vision",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-08-28",
"type": "launch",
@@ -77,6 +87,17 @@
"infra"
]
},
+ {
+ "date": "2026-08-28",
+ "type": "update",
+ "title": "AI agents can now see the 3D models they make",
+ "summary": "Until today every 3D generator on the internet, ours included, answered with a link to a file an AI agent cannot open. A person clicks it; an agent is blind to it, which is why an agent that makes a 3D model has never been able to tell a clean one from a melted one. That changes now: ask to look at any model and it comes back rendered from four angles as actual pictures the agent sees, with the geometry explained in plain language. An agent can finally check its own work, spot that the back of the model was never finished, and try again saying exactly what was wrong. It works over MCP, over a plain web request, and through a new open-source package called @three-ws/see, and it is free, including for agents that bought a model from us and want to confirm they got what they paid for.",
+ "link": "/docs/3d-vision",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-08-28",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index ed713b2f8..5a6725e8c 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -14,6 +14,14 @@
<category>launch</category>
<description>A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.</description>
</item>
+ <item>
+ <title>Docs · 3D Vision: let an agent see the model</title>
+ <link>https://three.ws/docs/3d-vision</link>
+ <guid isPermaLink="false">2026-08-28:Docs · 3D Vision: let an agent see the model</guid>
+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.</description>
+ </item>
<item>
<title>Docs · Feedback</title>
<link>https://three.ws/docs/feedback</link>
@@ -62,6 +70,14 @@
<category>fix</category>
<description>The platform sponsors the network fee on every agent payment. When that wallet ran down to the point where it could not cover a single fee, the check meant to pause payments could not run, because it depended on a balance lookup and the network providers were rate-limited at the same moment. Payments kept being attempted for three hours and none of them could complete. The pause now reads its answer from the failure itself, which costs nothing and works exactly when the network is too busy to answer questions. The status page also names the real cause now, a wallet that needs funding, instead of pointing at the payment rail.</description>
</item>
+ <item>
+ <title>AI agents can now see the 3D models they make</title>
+ <link>https://three.ws/docs/3d-vision</link>
+ <guid isPermaLink="false">2026-08-28:AI agents can now see the 3D models they make</guid>
+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Until today every 3D generator on the internet, ours included, answered with a link to a file an AI agent cannot open. A person clicks it; an agent is blind to it, which is why an agent that makes a 3D model has never been able to tell a clean one from a melted one. That changes now: ask to look at any model and it comes back rendered from four angles as actual pictures the agent sees, with the geometry explained in plain language. An agent can finally check its own work, spot that the back of the model was never finished, and try again saying exactly what was wrong. It works over MCP, over a plain web request, and through a new open-source package called @three-ws/see, and it is free, including for agents that bought a model from us and want to confirm they got what they paid for.</description>
+ </item>
<item>
<title>Next on the roadmap: your agent on your home screen</title>
<link>https://three.ws/changelog</link>
diff --git a/public/features.json b/public/features.json
index 45a498ff4..2932537de 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-28T03:09:16.844Z",
+ "generated_at": "2026-08-28T03:26:00.137Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -5187,6 +5187,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/3d-vision",
+ "title": "Docs · 3D Vision: let an agent see the model",
+ "description": "Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.",
+ "added": "2026-08-28",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/3d-api",
"title": "Docs · The three.ws 3D API",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index a543aab3d..916356eae 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -3141,6 +3141,12 @@ URL: https://three.ws/tutorials/sell-a-skill-with-a-trial
List an agent skill for sale in $THREE, give buyers a metered free trial, and watch it expire into a real on-chain purchase. Covers choosing a trial length and the missing decrement that quietly makes a trialled skill impossible to sell.
+### Docs · 3D Vision: let an agent see the model
+
+URL: https://three.ws/docs/3d-vision
+
+Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.
+
### Docs · The three.ws 3D API
URL: https://three.ws/docs/3d-api
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 3c02797b8..a9392f23f 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -83,7 +83,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p>All 842 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
+ <p>All 843 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
<div class="sm-formats">
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
<a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
@@ -95,7 +95,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 842 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 843 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>
@@ -135,6 +135,14 @@
<span class="sm-desc">Telling the corner companion what broke: the proactive ask at the moment of failure, the route, build SHA, and console errors captured for you, the severity and clustering rules, the report API, and the boundary that keeps untrusted visitor text from ever reaching anything with write access.</span>
</a>
</li>
+ <li>
+ <a href="/docs/3d-vision">
+ <span class="sm-new-date">Aug 28, 2026</span>
+ <span class="sm-title">Docs · 3D Vision: let an agent see the model</span>
+ <span class="sm-path">/docs/3d-vision</span>
+ <span class="sm-desc">Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.</span>
+ </a>
+ </li>
<li>
<a href="/seeker">
<span class="sm-new-date">Aug 27, 2026</span>
@@ -167,14 +175,6 @@
<span class="sm-desc">100 stars on GitHub, and the complete map of the three.ws open-source developer ecosystem: every npm package, MCP server, contract, worker, skill, spec, integration, and registry where the code lives, with the number behind each.</span>
</a>
</li>
- <li>
- <a href="/docs/the-first-19-weeks">
- <span class="sm-new-date">Aug 25, 2026</span>
- <span class="sm-title">Docs · The First 19 Weeks</span>
- <span class="sm-path">/docs/the-first-19-weeks</span>
- <span class="sm-desc">The founding three.ws roundup: a week-by-week record of everything shipped from the first commit on 2026-04-14 through 2026-08-25, with every launch, partnership, announcement, and where $THREE fits.</span>
- </a>
- </li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
@@ -2283,7 +2283,7 @@
<section class="sm-section" id="learn">
<header>
- <h2>Learn<span class="sm-count" data-count>380</span></h2>
+ <h2>Learn<span class="sm-count" data-count>381</span></h2>
<p class="sm-section-desc">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
@@ -3841,6 +3841,13 @@
<span class="sm-desc">List an agent skill for sale in $THREE, give buyers a metered free trial, and watch it expire into a real on-chain purchase. Covers choosing a trial length and the missing decrement that quietly makes a trialled skill impossible to sell.</span>
</a>
</li>
+ <li>
+ <a href="/docs/3d-vision">
+ <span class="sm-title">Docs · 3D Vision: let an agent see the model</span>
+ <span class="sm-path">/docs/3d-vision</span>
+ <span class="sm-desc">Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.</span>
+ </a>
+ </li>
<li>
<a href="/docs/3d-api">
<span class="sm-title">Docs · The three.ws 3D API</span>
diff --git a/tests/3d-vision.test.js b/tests/3d-vision.test.js
new file mode 100644
index 000000000..001d1aa64
--- /dev/null
+++ b/tests/3d-vision.test.js
@@ -0,0 +1,186 @@
+/**
+ * Agent vision for 3D (api/_lib/3d-vision.js + api/3d/look.js).
+ *
+ * The point of this surface is that an agent can SEE a model instead of
+ * holding a link to it, so what is pinned here is the contract that makes that
+ * usable: a sane default turntable, honest partial results, and bounds that
+ * stop one caller from parking the shared headless browser.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Readable } from 'node:stream';
+
+process.env.PUBLIC_APP_ORIGIN = 'https://three.ws';
+
+const render = vi.hoisted(() => ({ calls: [], impl: null }));
+vi.mock('../api/_lib/avatar-render.js', () => ({
+ SCENE_PRESETS: { 'full-body': { id: 'full-body' }, 'upper-body': { id: 'upper-body' } },
+ renderAvatarScene: async (args) => {
+ render.calls.push(args);
+ if (render.impl) return render.impl(args);
+ return { png: Buffer.from([0x89, 0x50, 0x4e, 0x47, 1, 2, 3]) };
+ },
+}));
+vi.mock('../api/_lib/ssrf-guard.js', () => ({
+ assertSafePublicUrl: async (u) => {
+ if (String(u).includes('private')) throw Object.assign(new Error('blocked'), { code: 'invalid_url' });
+ },
+ SsrfBlockedError: class extends Error {},
+}));
+vi.mock('../api/_lib/image-persist.js', () => ({
+ persistImageBytes: async (b) => `https://cdn.test/${b.length}-${Math.min(...b)}.png`,
+ looksLikeImageBytes: () => true,
+}));
+vi.mock('../api/_lib/rate-limit.js', () => ({
+ limits: { renderIp: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })) },
+ clientIp: () => '203.0.113.1',
+}));
+
+const vision = await import('../api/_lib/3d-vision.js');
+const { default: handler } = await import('../api/3d/look.js');
+
+beforeEach(() => {
+ render.calls.length = 0;
+ render.impl = null;
+ globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({ stats: { triangles: 12400, materials: 2 } }), { status: 200, headers: { 'content-type': 'application/json' } }));
+});
+
+function makeRes() {
+ return {
+ statusCode: 200, headers: {}, body: null,
+ setHeader(n, v) { this.headers[String(n).toLowerCase()] = v; },
+ end(b) { this.body = b ?? null; },
+ };
+}
+function makeReq({ method = 'POST', url = '/api/3d/look', body = null } = {}) {
+ const payload = body == null ? '' : JSON.stringify(body);
+ const req = Readable.from(payload ? [Buffer.from(payload)] : []);
+ req.method = method; req.url = url; req.query = {};
+ req.headers = { 'content-type': 'application/json', host: 'three.ws', 'x-forwarded-proto': 'https' };
+ return req;
+}
+const post = async (body) => { const res = makeRes(); await handler(makeReq({ body }), res); return res; };
+
+describe('the default turntable is the smallest set that answers "is this good"', () => {
+ it('renders three-quarter, front, side and back when the caller says nothing', async () => {
+ const out = await vision.renderTurntable({ glbUrl: 'https://cdn.test/a.glb' });
+ expect(out.frames.map((f) => f.view)).toEqual(['three-quarter', 'front', 'side', 'back']);
+ });
+
+ it('frames the whole bounding box, never a humanoid crop that would cut a prop in half', async () => {
+ await vision.renderTurntable({ glbUrl: 'https://cdn.test/a.glb', views: ['front'] });
+ expect(render.calls[0].scenePreset.id).toBe('full-body');
+ });
+
+ it('renders one frame at a time: the shared browser dies if four pages are opened at once', async () => {
+ let concurrent = 0;
+ let peak = 0;
+ render.impl = async () => {
+ peak = Math.max(peak, ++concurrent);
+ await new Promise((r) => setTimeout(r, 5));
+ concurrent--;
+ return { png: Buffer.from([0x89, 0x50, 0x4e, 0x47]) };
+ };
+ await vision.renderTurntable({ glbUrl: 'https://cdn.test/a.glb' });
+ expect(peak).toBe(1);
+ });
+});
+
+describe('a caller cannot park the renderer', () => {
+ it('drops unknown angles instead of failing, and collapses duplicates', () => {
+ expect(vision.normalizeViews(['left', 'FRONT', 'front', 'side'])).toEqual(['front', 'side']);
+ });
+
+ it('falls back to the default set rather than rendering nothing', () => {
+ expect(vision.normalizeViews([])).toEqual([...vision.DEFAULT_VIEWS]);
+ expect(vision.normalizeViews(['nope'])).toEqual([...vision.DEFAULT_VIEWS]);
+ });
+
+ it('caps the view count and the frame size', () => {
+ expect(vision.normalizeViews(Object.keys(vision.VIEW_ANGLES)).length).toBeLessThanOrEqual(vision.MAX_VIEWS);
+ expect(vision.normalizeSize(99_999)).toBe(vision.MAX_SIZE);
+ expect(vision.normalizeSize(1)).toBe(vision.MIN_SIZE);
+ expect(vision.normalizeSize('nonsense')).toBe(vision.DEFAULT_SIZE);
+ });
+
+ it('refuses a URL the SSRF guard rejects, before any render runs', async () => {
+ await expect(vision.renderTurntable({ glbUrl: 'https://private.internal/a.glb' })).rejects.toThrow();
+ expect(render.calls).toHaveLength(0);
+ });
+});
+
+describe('partial results are reported, not hidden', () => {
+ it('keeps the frames that rendered and names the angles that did not', async () => {
+ render.impl = async ({ cameraOrbit }) => {
+ if (cameraOrbit.theta === 180) throw new Error('gpu hiccup');
+ return { png: Buffer.from([0x89, 0x50, 0x4e, 0x47]) };
+ };
+ const out = await vision.renderTurntable({ glbUrl: 'https://cdn.test/a.glb' });
+ expect(out.frames).toHaveLength(3);
+ expect(out.failed).toEqual([{ view: 'back', error: 'gpu hiccup' }]);
+ });
+
+ it('fails loudly only when nothing at all could be drawn', async () => {
+ render.impl = async () => { throw new Error('not a glb'); };
+ await expect(vision.renderTurntable({ glbUrl: 'https://cdn.test/a.glb' })).rejects.toThrow(/could not render/);
+ });
+});
+
+describe('the geometry reading turns numbers into judgement', () => {
+ it('bands the triangle count into advice a caller can act on', () => {
+ expect(vision.describeGeometry({ triangles: 900 })[0]).toMatch(/very light/);
+ expect(vision.describeGeometry({ triangles: 12_000 })[0]).toMatch(/normal real-time budget/);
+ expect(vision.describeGeometry({ triangles: 500_000 })[0]).toMatch(/render or print asset/);
+ });
+
+ it('says nothing it cannot measure', () => {
+ expect(vision.describeGeometry(null)).toEqual([]);
+ expect(vision.describeGeometry({})).toEqual([]);
+ });
+});
+
+describe('POST /api/3d/look', () => {
+ it('answers with a frame URL per angle, the stats and the reading', async () => {
+ const res = await post({ glb_url: 'https://cdn.test/robot.glb' });
+ expect(res.statusCode).toBe(200);
+ const body = JSON.parse(res.body);
+ expect(body.views).toHaveLength(4);
+ expect(body.views[0].image_url).toMatch(/^https:\/\/cdn\.test\//);
+ expect(body.stats.triangles).toBe(12400);
+ expect(body.notes[0]).toMatch(/triangles/);
+ expect(body.viewer_url).toContain('/viewer?src=');
+ expect(body.ar_url).toContain('/api/ar?src=');
+ });
+
+ it('rejects a non-https model URL without touching the renderer', async () => {
+ const res = await post({ glb_url: 'http://cdn.test/robot.glb' });
+ expect(res.statusCode).toBe(400);
+ expect(JSON.parse(res.body).error).toBe('invalid_url');
+ expect(render.calls).toHaveLength(0);
+ });
+
+ it('still returns frames when the inspector is down: the pictures are the irreplaceable part', async () => {
+ globalThis.fetch = vi.fn(async () => new Response('nope', { status: 503 }));
+ const res = await post({ glb_url: 'https://cdn.test/robot.glb' });
+ expect(res.statusCode).toBe(200);
+ const body = JSON.parse(res.body);
+ expect(body.views.length).toBeGreaterThan(0);
+ expect(body.stats).toBeUndefined();
+ });
+
+ it('answers 422 when the model itself cannot be drawn', async () => {
+ render.impl = async () => { throw new Error('corrupt glb'); };
+ const res = await post({ glb_url: 'https://cdn.test/broken.glb' });
+ expect(res.statusCode).toBe(422);
+ expect(JSON.parse(res.body).error).toBe('render_failed');
+ });
+
+ it('serves a discovery doc on GET so an agent can learn the angles', async () => {
+ const res = makeRes();
+ await handler(makeReq({ method: 'GET', body: null }), res);
+ expect(res.statusCode).toBe(200);
+ const body = JSON.parse(res.body);
+ expect(body.free).toBe(true);
+ expect(Object.keys(body.views)).toContain('three-quarter');
+ expect(body.mcp_equivalent.tool).toBe('look_at_model');
+ });
+});
diff --git a/tests/api/okx-forge.test.js b/tests/api/okx-forge.test.js
index 3b0984afc..f0182167d 100644
--- a/tests/api/okx-forge.test.js
+++ b/tests/api/okx-forge.test.js
@@ -158,6 +158,18 @@ describe('the listed line-up is the forge', () => {
expect(forgeSurface('forge-status').x402Amount(FORGE_TOOL)).toBe(null);
});
+ // A buyer that pays for a model receives a URL it cannot open. look_at_model
+ // renders it into MCP image blocks, free, on every endpoint: the buyer sees
+ // what it bought. No other seller on this marketplace can do that.
+ it('gives every endpoint the free look_at_model tool, priced at nothing', () => {
+ for (const id of FORGE_SERVICE_IDS) {
+ const surface = forgeSurface(id);
+ expect(surface.TOOL_CATALOG.map((t) => t.name)).toContain('look_at_model');
+ expect(surface.isPublicTool('look_at_model')).toBe(true);
+ expect(surface.x402Amount('look_at_model')).toBe(null);
+ }
+ });
+
it('exposes one client shape: the same tool names on every endpoint', () => {
for (const [id] of PAID_FORGE) {
const names = forgeSurface(id).TOOL_CATALOG.map((t) => t.name);
diff --git a/tests/mcp-studio.test.js b/tests/mcp-studio.test.js
index 2e4efdce5..dda81fb0c 100644
--- a/tests/mcp-studio.test.js
+++ b/tests/mcp-studio.test.js
@@ -8,7 +8,7 @@ import { COMPONENT_URI, PERSONA_COMPONENT_URI, componentCsp } from '../api/_mcp-
// The generation tools (render the model-viewer widget) + check_job (collects a
// pending generation) + the three embodiment / persona tools (render the
// living-body embed).
-const ALLOWED = ['forge_free', 'text_to_avatar', 'mesh_forge', 'rig_mesh', 'forge_avatar', 'refine_model', 'check_job'];
+const ALLOWED = ['forge_free', 'text_to_avatar', 'mesh_forge', 'rig_mesh', 'forge_avatar', 'refine_model', 'check_job', 'look_at_model'];
const PERSONA = ['create_agent_persona', 'get_agent_persona', 'persona_say'];
const ALL = [...ALLOWED, ...PERSONA];
@@ -33,10 +33,12 @@ describe('mcp-studio catalog', () => {
for (const t of TOOL_CATALOG) {
expect(typeof t.title).toBe('string');
expect(t.title.length).toBeGreaterThan(0);
- // check_job is a status probe (read-only, idempotent); every generator
- // creates a fresh asset per call.
+ // check_job is a status probe and look_at_model draws a picture of a
+ // model that already exists: both read-only and idempotent. Every
+ // generator creates a fresh asset per call.
+ const readOnly = t.name === 'check_job' || t.name === 'look_at_model';
expect(t.annotations).toMatchObject(
- t.name === 'check_job'
+ readOnly
? { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
);