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.

12.2 KB
Raw Blame
// 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 };