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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// GET/POST /api/3d/inspect — FREE, keyless glTF/GLB inspection + validation.
//
// The agent use-case: an autonomous agent has a 3D asset (from any source — a
// marketplace, a generation API, a user upload) and, before it commits to using
// it, needs to answer three questions cheaply: is this a spec-valid glTF/GLB,
// how heavy is it (vertices / triangles / materials / textures / animations /
// extensions), and what's the shortest path to making it smaller and faster for
// web/mobile delivery? This endpoint answers all three in one call. It is free
// on purpose — a validation utility drives trust and funnels callers to the paid
// pipelines (Forge Pro quality tiers, Rigged Avatars, mesh optimization).
//
// Input:
// GET /api/3d/inspect?url=<https url of a .glb/.gltf>
// POST /api/3d/inspect body { "url": "<https url>" } (application/json)
// POST /api/3d/inspect raw .glb/.gltf bytes as the request body
//
// Output:
// { url, valid, stats:{ vertices, triangles, materials, textures, animations,
// extensions[], … }, sizeBytes, recommendations:[{ severity, issue, fix }],
// validation:{ valid, numErrors, numWarnings, …,
// issues:[{ code, message, severity, pointer? }] }, ts }
//
// `validation.issues` carries the actual glTF-Validator findings (capped at 10;
// the counts beside it are the true totals). Without them a caller that gates on
// `valid` knows only that an asset failed, never why.
//
// Reuses the same inspection core the paid /api/x402/model-check route uses
// (api/_lib/model-inspect.js → src/gltf-inspect.js) plus the official Khronos
// glTF-Validator (gltf-validator npm) for the spec-compliance verdict, and the
// SSRF-hardened, size-capped fetcher (api/_lib/fetch-model.js). Never returns a
// 500 on a well-formed request: every failure maps to a specific 4xx/502.
import { cors, wrap, error, json, rateLimited, readJson, readBody } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { fetchModel, FetchModelError } from '../_lib/fetch-model.js';
import { inspectModel, suggestOptimizations } from '../_lib/model-inspect.js';
import { validateBytes } from 'gltf-validator';
// Free-tier size cap. A generous ceiling for real avatars/props while bounding
// the memory + compute a single anonymous call can spend. GLBs above this are
// almost always un-optimized source assets that the recommendations below would
// tell you to shrink anyway.
const MAX_BYTES = 32 * 1024 * 1024;
// Rank for ordering the recommendations list: most severe first. `suggestOptimizations`
// emits severities but does not order them, so we sort here.
const SEVERITY_RANK = { critical: 0, warn: 1, info: 2 };
// Map each optimization-suggestion id (from suggestOptimizations) to a concise,
// actionable fix. The suggestion's own `message` becomes the `issue` (what's
// wrong); this is the `fix` (what to do about it). Reusing the detector keeps the
// "which suggestions fire" logic in one place (shared with the paid route + the
// MCP tools) — this layer only reshapes it into the { severity, issue, fix }
// contract this endpoint advertises.
const RECOMMENDATION_FIX = {
tri_budget:
'Decimate the mesh (gltf-transform simplify) or author LODs before shipping to the web.',
draco: 'Apply KHR_draco_mesh_compression to the geometry buffers.',
meshopt: 'Apply EXT_meshopt_compression to the vertex + index buffers (faster decode than Draco).',
texture_oversized: 'Resize the flagged textures to ≤2048px unless hero-level detail is required.',
texture_basisu:
'Transcode PNG/JPEG textures to KTX2 / Basis Universal (KHR_texture_basisu) for GPU-direct upload.',
non_indexed: 'Re-index the primitives (gltf-transform weld) to remove duplicate vertices.',
too_many_materials: 'Merge identical materials to cut draw calls.',
texture_weight: 'Compress textures to KTX2 and resize them for web delivery.',
file_size: 'Compress geometry (Draco/meshopt) and textures (KTX2); target under 10 MB.',
anim_without_skin:
'Confirm the node-level animations are intentional; strip any orphan animation data.',
ok: 'No action needed — the model is already well-suited for web delivery.',
};
// Reshape the raw inspectModel output into the advertised `stats` block. Keeps the
// prompt-13 core fields (vertices/triangles/materials/textures/animations/extensions)
// and adds a few more the agent almost always wants next (meshes, nodes, skins,
// bone/joint count, required extensions, container, generator).
export function buildStats(info) {
const c = info.counts;
return {
vertices: c.totalVertices,
triangles: c.totalTriangles,
materials: c.materials,
textures: c.textures,
animations: c.animations,
extensions: info.extensionsUsed,
// Extra context — cheap to include, saves the caller a second call.
meshes: c.meshes,
nodes: c.nodes,
scenes: c.scenes,
skins: c.skins,
joints: c.totalJoints,
indexedPrimitives: c.indexedPrimitives,
nonIndexedPrimitives: c.nonIndexedPrimitives,
extensionsRequired: info.extensionsRequired,
container: info.container,
generator: info.generator,
};
}
// Build the prioritized { severity, issue, fix } recommendation list, ordered most
// severe first. Reuses suggestOptimizations for detection.
export function buildRecommendations(info) {
const suggestions = suggestOptimizations(info);
return suggestions
.map((s) => ({
severity: s.severity,
issue: s.estimate ? `${s.message} (${s.estimate})` : s.message,
fix: RECOMMENDATION_FIX[s.id] || s.message,
}))
.sort((a, b) => (SEVERITY_RANK[a.severity] ?? 3) - (SEVERITY_RANK[b.severity] ?? 3));
}
// The validator reports severity as an integer; callers want a word they can
// branch on without memorizing the enum.
const VALIDATOR_SEVERITY = ['error', 'warning', 'info', 'hint'];
// How many individual issues ride along in the response. The validator itself is
// capped at 100 below; a caller needs the first handful to act, not a wall of
// repeats of the same code, and the counts above already carry the true totals.
const MAX_REPORTED_ISSUES = 10;
// Reshape the validator's raw message list into the wire contract: what is wrong,
// where, and how severe. Exported so the shape is pinned in tests without running
// the validator over real bytes.
export function shapeIssues(messages) {
if (!Array.isArray(messages)) return [];
return messages.slice(0, MAX_REPORTED_ISSUES).map((m) => ({
code: typeof m?.code === 'string' ? m.code : 'UNKNOWN',
message: typeof m?.message === 'string' ? m.message : '',
severity: VALIDATOR_SEVERITY[m?.severity] || 'error',
// The JSON pointer into the asset (e.g. /images/0/bufferView). Absent on
// whole-file issues, so it is omitted rather than sent as an empty string.
...(typeof m?.pointer === 'string' && m.pointer ? { pointer: m.pointer } : {}),
}));
}
// Run the Khronos glTF-Validator for the authoritative spec-compliance verdict.
// External resources (a .gltf's side-car .bin/textures) are NOT fetched — GLBs
// are self-contained, and fetching arbitrary side files would reopen the SSRF
// surface fetch-model.js closes. A validator failure never fails the whole call:
// inspectModel already proved the bytes parse, so we degrade to valid:true with a
// note rather than 500. Returns { valid, ...counts, issues[] } or null when
// unavailable.
//
// The `issues` array is the difference between a usable verdict and an unusable
// one. Counts alone tell a caller that the asset failed and nothing about why:
// a CI gate keyed on `valid` can only print "1 error" and stop. Carrying the
// codes and pointers means the same gate can say IMAGE_MIME_TYPE_INVALID at
// /images/0/bufferView, which is a fix, not a mystery.
async function runValidator(bytes, filename) {
try {
const report = await validateBytes(bytes, {
maxIssues: 100,
uri: filename || 'model.glb',
externalResourceFunction: (uri) =>
Promise.reject(new Error(`external resource not fetched: ${uri}`)),
});
const issues = report?.issues || {};
return {
valid: (issues.numErrors ?? 0) === 0,
validatorVersion: report?.validatorVersion || null,
numErrors: issues.numErrors ?? 0,
numWarnings: issues.numWarnings ?? 0,
numInfos: issues.numInfos ?? 0,
numHints: issues.numHints ?? 0,
issues: shapeIssues(issues.messages),
truncated: Boolean(issues.truncated),
};
} catch {
return null;
}
}
// Fetch a model by URL through the SSRF-hardened, size-capped fetcher and translate
// its typed errors into this endpoint's HTTP contract. Blocked/private/invalid URLs
// are the caller's fault → 400; upstream problems → 502 with a retry hint; oversize
// → 413.
async function fetchByUrl(url) {
try {
const { bytes, url: finalUrl } = await fetchModel(url, {
maxBytes: MAX_BYTES,
timeoutMs: 20_000,
});
return { bytes, url: finalUrl };
} catch (err) {
if (err instanceof FetchModelError) {
if (err.code === 'file_too_large') {
throw httpError(413, 'too_large', `model exceeds the ${MAX_BYTES}-byte free-tier cap`);
}
if (['invalid_url', 'scheme_not_allowed', 'private_address', 'host_pin_mismatch'].includes(err.code)) {
throw httpError(400, 'invalid_url', err.message);
}
// upstream_error, too_many_redirects, dns_failed, dns_timeout, no_body, fetch_failed
throw httpError(502, 'fetch_failed', `could not fetch model: ${err.message}`, {
retry: 'the source URL did not return the model — check it is public and try again',
});
}
throw httpError(502, 'fetch_failed', `could not fetch model: ${err?.message || err}`);
}
}
function httpError(status, code, message, extra = {}) {
const e = new Error(message);
e.status = status;
e.code = code;
e.extra = extra;
return e;
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
if (req.method !== 'GET' && req.method !== 'POST') {
res.setHeader('allow', 'GET, POST');
return error(res, 405, 'method_not_allowed', 'use GET (?url=) or POST ({ url } or a raw model body)');
}
// Generous per-IP budget — this is a free, keyless utility. Reuses the generic
// api:ip limiter with an explicit 60/min override, which getLimiter keys into
// its own isolated bucket (no dedicated limiter needed, no shared-file edit).
const ip = clientIp(req);
const rl = await limits.apiIp(ip, { limit: 60, window: '1 m' });
if (!rl.success) return rateLimited(res, rl, 'too many inspect requests');
// Resolve the model bytes from one of the three accepted inputs.
let bytes;
let sourceUrl = null;
let filename = 'model.glb';
try {
if (req.method === 'GET') {
const url = String(req.query?.url || '').trim();
if (!url) {
return error(res, 400, 'missing_url', 'query param "url" is required (or POST a model body)');
}
const fetched = await fetchByUrl(url);
bytes = fetched.bytes;
sourceUrl = fetched.url;
filename = urlFilename(sourceUrl);
} else {
const ct = String(req.headers['content-type'] || '').toLowerCase();
if (ct.includes('application/json')) {
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e.status === 415 ? 415 : 400, 'invalid_json', e.message || 'invalid JSON body');
}
const url = String(body?.url || '').trim();
if (!url) {
return error(res, 400, 'missing_url', 'POST JSON must include "url", or upload raw model bytes');
}
const fetched = await fetchByUrl(url);
bytes = fetched.bytes;
sourceUrl = fetched.url;
filename = urlFilename(sourceUrl);
} else {
// Raw upload: the request body IS the model.
let raw;
try {
raw = await readBody(req, MAX_BYTES);
} catch (e) {
if (e.status === 413) {
return error(res, 413, 'too_large', `upload exceeds the ${MAX_BYTES}-byte free-tier cap`);
}
return error(res, 400, 'bad_body', e.message || 'could not read request body');
}
if (!raw || raw.byteLength === 0) {
return error(res, 400, 'empty_body', 'no model bytes uploaded — send a .glb/.gltf body or a "url"');
}
// Copy into a tight, zero-offset buffer — `raw` is a Buffer backed by a
// shared pool, and downstream parsers (glTF-Transform readBinary, the
// validator) are happiest with a standalone Uint8Array.
bytes = Uint8Array.from(raw);
}
}
} catch (e) {
// Typed errors from fetchByUrl (400/413/502) — never a 500.
return error(res, e.status || 502, e.code || 'fetch_failed', e.message, e.extra || {});
}
// Parse structure. A parse failure here means the bytes are not a real glTF/GLB.
let info;
try {
info = await inspectModel(bytes, { fileSize: bytes.byteLength });
} catch (e) {
return error(res, 400, 'invalid_model', `not a valid glTF/GLB: ${e.message || 'could not parse model'}`);
}
const validation = await runValidator(bytes, filename);
const stats = buildStats(info);
const recommendations = buildRecommendations(info);
const payload = {
url: sourceUrl,
// `valid` reflects the Khronos validator's error count when it ran; when the
// validator is unavailable the bytes still parsed, so it's structurally usable.
valid: validation ? validation.valid : true,
stats,
sizeBytes: bytes.byteLength,
recommendations,
validation: validation || { valid: true, note: 'validator unavailable — structural parse succeeded' },
ts: new Date().toISOString(),
};
// URL-sourced GETs are deterministic — let the CDN cache them briefly. Raw
// uploads and POSTs are never cached.
if (req.method === 'GET' && sourceUrl) {
res.setHeader('cache-control', 'public, max-age=60, s-maxage=300');
} else {
res.setHeader('cache-control', 'no-store');
}
return json(res, 200, payload);
});
function urlFilename(u) {
try {
return new URL(u).pathname.split('/').pop() || 'model.glb';
} catch {
return 'model.glb';
}
}