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
// POST /api/3d/generate + GET /api/3d/generate?job=<id>
//
// The FREE, keyless, agent-first front door to three.ws text→3D. An autonomous
// agent building a game, a scene, an NFT, or any visual can turn a text prompt
// into a real textured GLB in one call — no key, no account, no wallet. No other
// agent-payments platform gives away 3D generation; this is the magnet that
// funnels to paid Forge Pro (quality tiers) and Rigged Avatars.
//
// This route does NOT re-implement generation. It wraps the existing free draft
// lane (NVIDIA NIM TRELLIS → self-host TRELLIS/Hunyuan3D → HuggingFace Spaces)
// through the SAME /api/forge submit/poll pipeline the forge_free MCP tool and
// /api/v1/ai/text-to-3d already use (api/_mcp-studio/forge-client.js). Only the
// wire contract is new: a clean, minimal agent shape.
//
// POST { prompt, format?:'glb' }
// → 200 { status:'done', glbUrl, viewerUrl, arUrl, creationId, ... } (draft finished inline)
// → 200 { status:'pending', job, poll, etaSeconds, retryAfter, creationId, ... } (queued — poll below)
//
// GET ?job=<id>&title=<prompt> (title optional — labels the AR/viewer pages)
// → 200 { status:'pending', retryAfter } (still generating — wait retryAfter s, then poll)
// → 200 { status:'done', glbUrl, viewerUrl, arUrl } (GLB ready)
// → 200 { status:'error', error } (upstream failed; free = no charge)
// → 503 { error:'not_configured' } (no 3D lane here; polling can never finish)
//
// Every pending/queued response carries a `retryAfter` (seconds) poll-cadence hint
// — ETA-derived on submit, echoed on each poll — and sets the standard Retry-After
// header. A well-behaved agent that honors it stays under the poll flood-guard
// (limits.mcp3dStatus) instead of tripping its 429, and spares the shared free GPU
// lane needless status traffic. `creationId` is the stable forge creation handle
// for correlating logs, dedup, and referencing the generation across calls.
//
// arUrl is the device-aware AR launch (api/ar.js): opened on a phone it places
// the model in the caller's real room (Scene Viewer on Android, Quick Look on
// iOS); on desktop it falls back to the WebGL viewer. Same lane as /forge and
// /ar — surface it to end users as "place it in your room".
//
// Free = the draft/NIM tier only, and we say so honestly: single-subject prompts,
// ~draft-fidelity geometry, no rigging. Higher quality + rigging live behind the
// paid Forge (/api/x402/forge) and Rigged Avatars, linked in every response.
import { cors, wrap, method, json, error, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { startForge, originFromReq, viewerUrl, arLaunchUrl } from '../_mcp-studio/forge-client.js';
const PROMPT_MIN = 3; // the draft lane needs a subject to condition on
const PROMPT_MAX = 1000; // matches /api/forge's own prompt ceiling
const MAX_BODY_BYTES = 8_000;
// A forge job handle is either a signed f1.<b64url>.<b64url> token or a bare
// Replicate prediction id ([a-z0-9]{16,64}). Bound the poll param to that shape
// before forwarding — /api/forge does the authoritative validation, this just
// keeps obvious junk off the wire.
const JOB_HANDLE_RE = /^[A-Za-z0-9._-]{8,1024}$/;
// The upsell ladder every response carries: free draft here → paid Forge Pro
// quality tiers → rigged, animation-ready avatars. Not a paywall — a doorway.
const UPGRADE = Object.freeze({
message:
'This is the free draft tier (NVIDIA NIM TRELLIS): single-subject, draft-fidelity geometry, no rigging. ' +
'For higher polygon budgets + PBR textures use paid Forge Pro; for animation-ready rigged characters use Rigged Avatars.',
forgePro: '/api/x402/forge',
riggedAvatars: '/api/forge?action=rig',
docs: '/docs/3d-api',
});
// Derive a stable, opaque per-caller handle so the free-API lane stops writing
// anonymous rows into the forge_creations flywheel — its highest-growth surface.
// Two sources, in order of durability:
// 1) a caller-supplied stable id (x-forge-client, or x-agent-id for agent
// frameworks) — lets a repeat agent accrue a real, later-claimable body of
// work under one handle, unifying with any direct /api/forge or SDK usage;
// 2) else the caller's own IP, so even fully anonymous traffic segments per
// client instead of collapsing to a single 'anon' bucket.
// The raw value is forwarded only as x-forge-client (see startForge): forge
// salts+sha256s it into client_key, so nothing here reaches the DB in the clear,
// and the real IP never rides x-forwarded-for into forge's own per-IP limiter.
function pickHeader(req, name) {
const raw = req.headers?.[name];
const v = Array.isArray(raw) ? raw[0] : raw;
return typeof v === 'string' ? v.trim() : '';
}
export function agentClientId(req, ip) {
const supplied = pickHeader(req, 'x-forge-client') || pickHeader(req, 'x-agent-id');
if (supplied) return supplied.slice(0, 200);
return ip && ip !== '0.0.0.0' ? `ip:${ip}` : '';
}
// Recommended seconds a polling agent should wait between polls. Derived from the
// lane's ETA so a fast draft is polled promptly and a slow job sparingly: a
// well-behaved agent that honors this stays under the poll flood-guard
// (limits.mcp3dStatus) rather than tripping its 429, and the shared free GPU lane
// carries less status traffic. Bounded to [POLL_MIN_S, POLL_MAX_S]; falls back to
// the platform's own 3s cadence (forge-client DEFAULT_POLL_MS) when no ETA is known.
const POLL_MIN_S = 2;
const POLL_MAX_S = 10;
const POLL_DEFAULT_S = 3;
export function pollIntervalFromEta(etaSeconds) {
if (!Number.isFinite(etaSeconds) || etaSeconds <= 0) return POLL_DEFAULT_S;
return Math.max(POLL_MIN_S, Math.min(POLL_MAX_S, Math.round(etaSeconds / 4)));
}
// Shape a /api/forge draft-lane submit response into this route's agent contract.
// Pure + exported so the boundary is pinned in tests against real captured forge
// shapes (inline-done vs queued) without any network.
export function shapeSubmit(job, base, prompt) {
const glbUrl = typeof job?.glb_url === 'string' ? job.glb_url : '';
// forge stamps a durable creation handle on both the inline-done and queued
// shapes; surface it so an agent can correlate, dedup, and reference the run.
const creationId = typeof job?.creation_id === 'string' ? job.creation_id : null;
if (job?.status === 'done' && glbUrl) {
return {
status: 'done',
glbUrl,
viewerUrl: viewerUrl(base, glbUrl),
arUrl: arLaunchUrl(base, glbUrl, prompt),
format: 'glb',
tier: 'draft',
free: true,
...(creationId ? { creationId } : {}),
upgrade: UPGRADE,
};
}
const token = job?.job_id ?? null;
// forge's queued response spreads its provenance, which carries the lane ETA;
// turn it into a concrete poll-cadence hint (and echo the raw ETA for display).
const etaSeconds = Number.isFinite(job?.eta_seconds) ? job.eta_seconds : null;
// The poll URL carries the prompt as `title` so the eventual done response
// labels the AR/viewer pages without the caller resending anything.
const t =
typeof prompt === 'string' && prompt.trim()
? `&title=${encodeURIComponent(prompt.trim().slice(0, 80))}`
: '';
return {
status: 'pending',
job: token,
poll: token ? `/api/3d/generate?job=${encodeURIComponent(token)}${t}` : null,
retryAfter: pollIntervalFromEta(etaSeconds),
...(etaSeconds != null ? { etaSeconds } : {}),
...(creationId ? { creationId } : {}),
format: 'glb',
tier: 'draft',
free: true,
upgrade: UPGRADE,
};
}
// Shape a /api/forge poll response into { status:'pending'|'done'|'error', ... }.
// Pure + exported for the same reason as shapeSubmit.
export function shapePoll(data, base, jobId, title) {
const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';
const creationId = typeof data?.creation_id === 'string' ? data.creation_id : null;
if (data?.status === 'done' && glbUrl) {
return {
status: 'done',
job: jobId,
glbUrl,
viewerUrl: viewerUrl(base, glbUrl),
arUrl: arLaunchUrl(base, glbUrl, title),
format: 'glb',
tier: 'draft',
free: true,
...(creationId ? { creationId } : {}),
};
}
if (data?.status === 'failed') {
return {
status: 'error',
job: jobId,
// Free lane: an upstream failure costs the caller nothing, so say so and let
// them simply retry. The message is already sanitized by /api/forge.
error: data?.error || '3D generation hit a snag upstream, no charge; try again.',
free: true,
upgrade: UPGRADE,
};
}
// queued / running / anything transient → still pending; keep the title on the
// poll URL so it survives to the done response, and echo the poll-cadence hint
// (ETA-derived when forge's poll shape carries one, else the default cadence).
const etaSeconds = Number.isFinite(data?.eta_seconds) ? data.eta_seconds : null;
const t =
typeof title === 'string' && title.trim()
? `&title=${encodeURIComponent(title.trim().slice(0, 80))}`
: '';
return {
status: 'pending',
job: jobId,
poll: `/api/3d/generate?job=${encodeURIComponent(jobId)}${t}`,
retryAfter: pollIntervalFromEta(etaSeconds),
...(etaSeconds != null ? { etaSeconds } : {}),
...(creationId ? { creationId } : {}),
free: true,
};
}
// Map a startForge lane failure to an honest boundary response. A well-formed
// prompt must NEVER 500: every code has a designed status + actionable message.
function failFromLane(res, err) {
switch (err?.code) {
case 'not_configured':
return json(res, 503, {
error: 'not_configured',
message:
err.message ||
'Free text→3D is not configured on this deployment — set NVIDIA_API_KEY (or a self-host TRELLIS / HuggingFace lane).',
});
case 'busy':
// GPU lane saturated upstream — surface the retry hint the lane handed back.
if (err.retryAfter) res.setHeader('retry-after', String(err.retryAfter));
return json(res, 429, {
error: 'rate_limited',
message:
err.message ||
'The free 3D GPU lane is momentarily saturated — try again shortly.',
retry_after: err.retryAfter || 10,
});
case 'timeout':
res.setHeader('retry-after', '10');
return json(res, 503, {
error: 'lane_timeout',
message: err.message || 'The 3D lane took too long to accept the job — try again.',
retry_after: 10,
});
default:
// Upstream provider blip — a free-lane failure, not a server fault. Answer
// with a designed 502 (never a raw 500) so the agent can retry.
return json(res, 502, {
error: 'generation_failed',
message: err?.message || 'The 3D lane could not start this job — try again.',
});
}
}
async function generate(req, res) {
const ip = clientIp(req);
let body;
try {
body = await readJson(req, MAX_BODY_BYTES);
} catch (err) {
return json(res, err?.status === 413 ? 413 : 400, {
error: 'bad_request',
message:
err?.status === 413
? 'Request body too large.'
: 'Send a JSON body: { "prompt": "..." }.',
});
}
const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
if (prompt.length < PROMPT_MIN) {
return json(res, 400, {
error: 'invalid_prompt',
message: `"prompt" is required — describe one subject in ${PROMPT_MIN}–${PROMPT_MAX} characters, e.g. "a small ceramic robot figurine".`,
});
}
if (prompt.length > PROMPT_MAX) {
return json(res, 400, {
error: 'invalid_prompt',
message: `"prompt" must be ${PROMPT_MAX} characters or fewer.`,
});
}
// Only GLB is offered on the free lane. Accept the default and an explicit
// 'glb'; reject anything else plainly rather than silently ignoring it.
const format = body?.format == null ? 'glb' : String(body.format).toLowerCase();
if (format !== 'glb') {
return json(res, 400, {
error: 'unsupported_format',
message: 'The free lane returns GLB only. Omit "format" or pass "glb".',
});
}
// Per-IP guard on the free GPU lane. Reuses the existing free-lane bucket
// (mcp3d:generate:free) — the SAME counter /api/forge draws from — so this is a
// generous shared ceiling protecting one GPU allocation, and the check here
// rejects a flood before the self-call round-trip. The GLOBAL concurrency guard
// (HuggingFace slot lease + platform submit throttle) lives inside /api/forge and
// is inherited automatically by routing through it — no new limiter invented.
const rl = await limits.mcp3dGenerateFree(ip);
if (!rl.success) {
return rateLimited(
res,
rl,
'Free 3D generation limit reached — try again shortly, or use paid Forge Pro (no per-IP cap).',
{
upgrade: UPGRADE,
},
);
}
const base = originFromReq(req);
let job;
try {
// Pin the free draft lane exactly: NVIDIA NIM TRELLIS, image path, draft tier.
// Wide submit window (240s vs the 90s default): when NIM is degraded the
// draft falls to the blocking HF Spaces lane, whose queue + inference can
// legitimately run past 90s. Consumers of this endpoint poll anyway, so a
// slower inline completion strictly beats aborting the self-call at 90s,
// 503ing the caller, and finishing the GPU work for nobody (the 2026-07-18
// lane_timeout window: every one of those 503s was exactly 90s old).
job = await startForge(base, {
prompt,
backend: 'nvidia',
path: 'image',
tier: 'draft',
submitTimeoutMs: 240_000,
// Attribute the durable creation to this caller so the flywheel isn't
// blind on the free lane (and a repeat agent can later claim its work).
clientKey: agentClientId(req, ip),
});
} catch (err) {
return failFromLane(res, err);
}
return sendShaped(res, shapeSubmit(job, base, prompt));
}
// Emit a shaped response, attaching the standard Retry-After header whenever the
// body carries a poll-cadence hint so HTTP-aware clients honor it without parsing
// the JSON. Non-pending shapes (done/error) carry no retryAfter and pass through.
function sendShaped(res, shaped) {
if (shaped?.status === 'pending' && shaped.retryAfter)
res.setHeader('retry-after', String(shaped.retryAfter));
return json(res, 200, shaped);
}
async function poll(req, res, jobId, title) {
if (!JOB_HANDLE_RE.test(jobId)) {
return json(res, 400, {
error: 'invalid_job',
message: 'Malformed job id. Pass the "job" value from the generate response.',
});
}
// Cheap, high-frequency poll — reuse the forge status limiter (per-instance,
// flood-guard only) so a polling loop can't be turned into a hammer.
const rl = await limits.mcp3dStatus(clientIp(req));
if (!rl.success) return rateLimited(res, rl, 'Polling too fast — slow down and retry.');
const base = originFromReq(req);
let upstream;
try {
upstream = await fetch(`${base}/api/forge?job=${encodeURIComponent(jobId)}`, {
headers: { accept: 'application/json' },
signal: AbortSignal.timeout(15_000),
});
} catch {
// A transient network blip on the self-call is not a job failure — tell the
// caller it's still pending so its poll loop retries.
return sendShaped(res, shapePoll({ status: 'running' }, base, jobId, title));
}
const data = await upstream.json().catch(() => ({}));
if (upstream.status === 400) {
return json(res, 400, {
error: 'invalid_job',
message: data?.message || 'Unknown or malformed job id.',
});
}
// A deployment that cannot serve this job AT ALL (the lane behind the handle is
// unconfigured here) is not the transient blip the pending fallback below is
// for: answering 'pending' would hand the agent a poll loop that can never
// finish. Surface the same designed not_configured the submit path returns.
if (
(upstream.status === 503 || upstream.status === 501) &&
(data?.error === 'unconfigured' || data?.error === 'backend_unconfigured')
) {
return json(res, 503, {
error: 'not_configured',
message:
'Free text-to-3D is not configured on this deployment, so this job cannot be polled here.',
});
}
if (upstream.status === 429) {
const retryAfter = Number(data?.retry_after) || 5;
res.setHeader('retry-after', String(retryAfter));
return json(res, 429, {
error: 'rate_limited',
message: 'Polling is rate-limited — retry shortly.',
retry_after: retryAfter,
});
}
if (!upstream.ok) {
// Upstream hiccup mid-poll — keep the job alive as pending so the loop retries.
return sendShaped(res, shapePoll({ status: 'running' }, base, jobId, title));
}
return sendShaped(res, shapePoll(data, base, jobId, title));
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
if (!method(req, res, ['GET', 'POST'])) return;
if (req.method === 'POST') return generate(req, res);
const url = new URL(req.url, 'http://localhost');
const jobId = (url.searchParams.get('job') || '').trim();
if (!jobId) {
return error(
res,
400,
'missing_job',
'Pass ?job=<id> to poll a generation, or POST { prompt } to start one.',
);
}
const title = (url.searchParams.get('title') || '').trim().slice(0, 120);
return poll(req, res, jobId, title);
});
// The free NIM draft often finishes inside the submit window; startForge waits
// up to 240s for that inline completion (wide enough for the blocking HF
// fallback lane's queue). Give the function headroom beyond that window so a
// slow draft returns done in one call instead of a gateway timeout.
export const config = { maxDuration: 300 };