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.

4.4 KB
Raw Blame
// POST /api/v1/ai/text-to-3d — the flagship FREE text→3D endpoint of the
// three.ws AI package.
//
// three.ws runs the only text→mesh lane in the x402 / agent-payments ecosystem.
// Its draft tier is genuinely free: a prompt goes to the NVIDIA NIM TRELLIS lane
// (backend `nvidia`, path `image`, draft tier) via the SAME submit pipeline that
// backs the `forge_free` MCP tool and /forge — no key, no wallet. This route
// gives that lane a clean, versioned front door instead of leaving it buried
// under forge job plumbing.
//
// Semantics mirror the draft lane exactly (zero duplicated generation logic):
//   • The NIM often finishes inside the submit window → { status:'done', glb_url,
//     viewer_url }.
//   • Otherwise the job is queued → { status:'pending', job:<token>, poll_url }
//     and the caller polls the EXISTING free endpoint GET /api/forge?job=<token>.
//
// Free with a per-IP daily quota (10/day — the GPU quota is real). Above the
// quota we do NOT paywall silently: 429 with X-RateLimit-Reset AND a pointer to
// the paid /api/x402/forge tiers, which have no daily cap. The free lane is the
// funnel; the paid forge is the upsell.

import { defineEndpoint, fail } from '../../_lib/gateway.js';
import { json } from '../../_lib/http.js';
import { limits } from '../../_lib/rate-limit.js';
import { backendIsConfigured } from '../../_lib/forge-tiers.js';
import { startForge, originFromReq } from '../../_mcp-studio/forge-client.js';
import { shapeResult, quotaBody, resetSeconds, DAILY_QUOTA, PROMPT_MIN, PROMPT_MAX } from './_text-to-3d-lane.js';

export { shapeResult } from './_text-to-3d-lane.js';

// The NVIDIA NIM lane can't serve without its key. Throw the platform's canonical
// missing-env error so the gateway's `wrap` renders the standard 503
// not_configured envelope and names the exact var to the operator (logs + ops
// alert) — which secrets are unset is operator information, never leaked to the
// client (see api/_lib/http.js `wrap`).
function throwNotConfigured() {
	throw new Error('Missing required env var: NVIDIA_API_KEY');
}

// Map a startForge lane failure to an honest boundary error. The buyer/user is
// never left with a silent failure — every code has a designed status + message.
function failFromLane(err) {
	const code = err?.code;
	if (code === 'not_configured') {
		// The nvidia backend's not_configured is precisely a missing NVIDIA env —
		// route it through the same canonical 503 not_configured path.
		throwNotConfigured();
	}
	if (code === 'busy') {
		fail(429, 'rate_limited', err.message || 'The free text→3D lane is momentarily busy — try again shortly.');
	}
	if (code === 'timeout') {
		fail(504, 'lane_timeout', err.message || 'The text→3D lane took too long to accept the job — try again.');
	}
	fail(502, 'lane_error', err?.message || 'The text→3D lane failed to accept the job.');
}

export default defineEndpoint({
	name: 'v1.ai.text_to_3d',
	method: 'POST',
	auth: 'public',
	handler: async ({ req, res, body, ip }) => {
		const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
		if (prompt.length < PROMPT_MIN) {
			fail(400, 'validation_error', `"prompt" must be a non-empty string of at least ${PROMPT_MIN} characters`);
		}
		if (prompt.length > PROMPT_MAX) {
			fail(400, 'validation_error', `"prompt" must be ${PROMPT_MAX} characters or fewer`);
		}

		// The free draft lane pins the NVIDIA NIM TRELLIS backend. If its key isn't
		// present the lane can't serve — surface the platform's clean 503
		// not_configured (the missing var is named to the operator, not the client).
		if (!backendIsConfigured('nvidia')) {
			throwNotConfigured();
		}

		// Per-IP daily GPU quota. Above it: 429 with reset + paid upsell, never a
		// silent paywall. Consumed before submit so a burst can't outrun the meter.
		const rl = await limits.aiTextTo3d(ip);
		if (!rl.success) {
			const resetSec = resetSeconds(rl, Date.now());
			res.setHeader('X-RateLimit-Limit', String(rl.limit ?? DAILY_QUOTA));
			res.setHeader('X-RateLimit-Remaining', '0');
			res.setHeader('X-RateLimit-Reset', String(resetSec));
			res.setHeader('Retry-After', String(resetSec));
			return json(res, 429, quotaBody(rl, resetSec));
		}

		const base = originFromReq(req);
		let job;
		try {
			job = await startForge(base, { prompt, backend: 'nvidia', path: 'image', tier: 'draft' });
		} catch (err) {
			failFromLane(err);
		}

		return shapeResult(job, base);
	},
});