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/studio + GET /api/3d/studio?job=<id>
//
// The ChatGPT Actions surface for free text→3D — the REST contract behind the
// "three.ws 3D Studio" custom GPT (prompts/store-submissions/_generated/
// openai-actions.yaml). It exists as a separate route from /api/3d/generate
// because a GPT Store listing has stricter response rules than the agent lane:
// responses may carry ONLY the model URLs and job state — no upsell block, no
// pricing paths, no internal identifiers — and every prompt must pass the
// age-13+ content-safety gate before any GPU work starts.
//
// It is a thin shaper, not a second pipeline: generation runs through the
// gpt-forge-client → /api/gpt-forge free-first router (the ChatGPT-dedicated
// clone of /api/forge) with no pinned backend, and draws from the SAME per-IP
// quota buckets as /api/3d/generate, so adding this surface creates no new
// capacity and no new limiter. High tier rides the async self-host lanes
// operator-funded (internal seed) through the pending/poll contract.
//
// POST { prompt, tier? } (tier: draft | standard (default) | high)
// → 200 { status:'done', glbUrl, viewerUrl, arUrl, format, previewImageUrl?, tier? }
// → 200 { status:'pending', job, poll, watchUrl, format, previewImageUrl?, tier?, etaSeconds? }
// → 400 { error:'prompt_rejected', message } (safety gate refusal)
//
// GET ?job=<id>&title=<prompt> (title optional — labels the AR/viewer pages)
// → 200 { status:'pending', job, poll, watchUrl, previewImageUrl?, tier? }
// → 200 { status:'done', glbUrl, viewerUrl, arUrl, format, previewImageUrl?, tier? }
// → 200 { status:'error', error } (upstream failed — retry is free)
//
// watchUrl is the live progress page (public/watch.html): a three.ws link the
// GPT hands the user on pending states so they can watch the countdown and the
// concept image in a real browser tab instead of waiting inside the chat. When
// the job finishes, that page forwards itself into the /viewer funnel.
//
// previewImageUrl is the forge's painted concept view — the image-generation
// first step of the text path — surfaced on pending states so the GPT can show
// the user what is being sculpted while the mesh is still generating.
//
// arUrl is the flagship link: the device-aware AR launch (api/ar.js) that puts
// the model in the user's real room — Scene Viewer on Android, Quick Look on
// iOS (GLB→USDZ converted in-page), WebGL viewer on desktop. It is the same
// place-in-your-space lane the /forge and /ar pages use, surfaced first-class
// so the GPT can offer "put it in your room" on every generation.
//
// ChatGPT Actions time out at ~45s; the forge lane bounds its synchronous hold
// to 30s (NVCF_POLL_SECONDS in api/_providers/nvidia.js), so a slow job always
// returns 'pending' + a poll handle before the Action deadline instead of dying
// on the socket.
import { cors, wrap, method, json, readJson, setRateLimitHeaders } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { startForge, originFromReq } from '../_mcp-studio/gpt-forge-client.js';
// Response shaping is shared with the OKX.AI A2MCP forge services so the two
// fronts over this lane cannot drift; re-exported here because the Actions
// contract tests pin the boundary through this route's module.
import { shapeSubmit, shapePoll } from '../_mcp-studio/studio-shape.js';
import { checkPromptSafety } from '../_mcp-studio/safety.js';
import { resolveLogoPrompt } from '../_lib/forge-director-prompts.js';
export { shapeSubmit, shapePoll };
const PROMPT_MIN = 3; // the generation lane needs a subject to condition on
const PROMPT_MAX = 1000; // matches /api/gpt-forge's own prompt ceiling
const MAX_BODY_BYTES = 8_000;
// A forge job handle is either a signed f1.<b64url>.<b64url> string or a bare
// prediction id. Bound the poll param to that shape before forwarding —
// /api/gpt-forge does the authoritative validation, this just keeps junk off the wire.
const JOB_HANDLE_RE = /^[A-Za-z0-9._-]{8,1024}$/;
// Every error body on this route is an ErrorResponse from the published Actions
// schema: { error, message, retry_after? }. The generic http.js helpers emit
// `error_description` instead of `message`, which the custom GPT has no field
// for, so the two limiter paths shape their own body while still setting the
// RateLimit-* / Retry-After headers a polling client backs off on.
function limitReached(res, result, message) {
const retryAfter = Math.max(1, setRateLimitHeaders(res, result));
res.setHeader('retry-after', String(retryAfter));
return json(res, 429, { error: 'rate_limited', message, retry_after: retryAfter });
}
// 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: '3D generation is temporarily unavailable on this deployment — try again later.',
});
case 'busy':
if (err.retryAfter) res.setHeader('retry-after', String(err.retryAfter));
return json(res, 429, {
error: 'rate_limited',
message: err.message || 'The free 3D generator 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 generator took too long to accept the job — try again.',
retry_after: 10,
});
default:
return json(res, 502, {
error: 'generation_failed',
message: err?.message || 'The 3D generator 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.`,
});
}
// Optional quality tier. High runs operator-funded (internal seed) on the
// async self-host lanes and simply takes longer through the pending/poll
// contract — no payment surface exists on this endpoint.
const rawTier = body?.tier === undefined ? 'standard' : body.tier;
const tier = rawTier === 'draft' || rawTier === 'standard' || rawTier === 'high' ? rawTier : null;
if (!tier) {
return json(res, 400, {
error: 'invalid_tier',
message: '"tier" must be "draft", "standard", or "high" (default "standard").',
});
}
// Age-13+ content gate BEFORE any quota spend or GPU work. The category
// message is the user-facing refusal the GPT relays verbatim.
const safety = checkPromptSafety(prompt);
if (!safety.allowed) {
return json(res, 400, { error: 'prompt_rejected', message: safety.message });
}
// Per-IP guard on the free GPU lane — the SAME bucket /api/3d/generate and
// /api/gpt-forge draw from, so this surface adds no new unmetered capacity.
const rl = await limits.mcp3dGenerateFree(ip);
if (!rl.success) {
return limitReached(res, rl, 'Free 3D generation limit reached. Try again in a little while.');
}
const base = originFromReq(req);
// Known brand-mark prompts ("<brand name> logo") resolve to a deterministic
// geometric spec of the real mark. This lane runs no LLM director (the ~45s
// Actions deadline leaves no headroom), so without the lexicon a raw brand
// name reconstructs as a generic badge covered in garbled lettering.
const knownMark = resolveLogoPrompt(prompt);
const subject = knownMark ? knownMark.prompt : prompt;
let job;
try {
// No pinned backend: the health-aware free-first router picks the best
// healthy lane for the prompt exactly as the /forge page does (the fast
// NIM lane is its own named default for standard text, so the happy path
// is unchanged). Slow/async lanes return a poll handle, which the
// pending/poll contract absorbs — ChatGPT Actions' ~45s deadline only
// bounds the submit, never the generation. High rides the async
// self-host lanes with the internal seed; startForge degrades a high
// submit to standard on 402/timeout rather than dead-ending.
job = await startForge(
base,
knownMark?.imagePath
? { prompt: subject, imageUrls: [`${base}${knownMark.imagePath}`], tier }
: { prompt: subject, path: 'image', tier, ...(tier === 'high' ? { internal: true } : {}) },
);
} catch (err) {
return failFromLane(res, err);
}
return json(res, 200, shapeSubmit(job, base, prompt));
}
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 limitReached(res, rl, 'Polling too fast. Slow down and retry.');
const base = originFromReq(req);
let upstream;
try {
upstream = await fetch(`${base}/api/gpt-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 json(res, 200, 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: 'pending' would leave the GPT polling a job that can never finish. The
// published Actions contract has no 503 on this operation, so answer with its
// documented terminal state instead.
if (
(upstream.status === 503 || upstream.status === 501) &&
(data?.error === 'unconfigured' || data?.error === 'backend_unconfigured')
) {
return json(res, 200, {
status: 'error',
job: jobId,
error: '3D generation is temporarily unavailable, so this job cannot be checked right now.',
});
}
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 json(res, 200, shapePoll({ status: 'running' }, base, jobId, title));
}
return json(res, 200, shapePoll(data, base, jobId, title));
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', payments: false })) 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 json(res, 400, {
error: 'missing_job',
message: '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 90s for that inline completion. Give the function headroom beyond the default
// so a fast draft returns done in one call instead of forcing a poll.
export const config = { maxDuration: 120 };