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/forge-quality-check - score a generated 3D model's realism / quality.
//
// A thin HTTP surface over the reusable gate in api/_lib/forge-quality-gate.js.
// All provider policy (Vertex Gemini first, free NVIDIA NIM vision backup),
// rendering, the subject-aware rubric, fail-open behavior, and the retry-directive
// logic live in the lib - this file only reads the request, meters it, and shapes
// the response. The generation router (api/forge.js) imports the lib directly; this
// endpoint exists so a client, an external agent, or an ops probe can score any
// GLB (or an existing render) on demand.
//
// Request (JSON body):
// { glbUrl?, renderUrl?, image?, imageType?, prompt?, subject?, passScore?,
// tier?, path?, attempt? }
// Supply ONE of glbUrl (rendered here), renderUrl (public image URL), or image
// (base64 / data URI of a render). prompt steers the rubric + the retry hint.
// tier/path/attempt (optional) let the response include a ready-to-run retry
// directive when the model fails the gate.
// Response:
// { verdict, retry } where verdict is the structured gate result and retry is a
// buildRetryDirective() object (or null). A GET returns a capability probe.
//
// Fail-open: a scoring/render/provider outage returns 200 with
// verdict.qa_available:false and verdict.pass:true - the gate never blocks a
// generation, and neither does this endpoint.
import { cors, method, readJson, error, json, wrap, rateLimited } from './_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer } from './_lib/auth.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import {
runQualityGate,
buildRetryDirective,
qualityGateConfigured,
vertexQualityConfigured,
QUALITY_GATE_DEFAULTS,
} from './_lib/forge-quality-gate.js';
export const maxDuration = 60;
// base64 render inflates ~33%; a 640px PNG is well under this even before that.
const MAX_BODY_BYTES = 20 * 1024 * 1024;
export default wrap(async function handler(req, res) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
if (!method(req, res, ['GET', 'POST'])) return;
// Capability probe - lets a UI decide whether to surface a "check quality"
// affordance, and reports which lane will serve.
// method() above already normalized an incoming HEAD to GET, so this one
// check covers both verbs.
if (req.method === 'GET') {
return json(
res,
200,
{
configured: qualityGateConfigured(),
provider: vertexQualityConfigured() ? 'vertex' : (qualityGateConfigured() ? 'platform-vision' : null),
model: vertexQualityConfigured() ? QUALITY_GATE_DEFAULTS.model : null,
passScore: QUALITY_GATE_DEFAULTS.passScore,
maxRetries: QUALITY_GATE_DEFAULTS.maxRetries,
},
{ 'cache-control': 'public, max-age=60' },
);
}
// Metered like the other free vision lanes (this can burn a Vertex call).
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
const userId = session?.id ?? bearer?.userId ?? null;
if (userId) {
const rl = await limits.visionUser(userId);
if (!rl.success) return rateLimited(res, rl, 'Quality-check rate limit exceeded, try again later');
} else {
const rl = await limits.visionIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl, 'Quality-check rate limit exceeded, sign in for a higher limit');
}
let body;
try {
body = await readJson(req, MAX_BODY_BYTES);
} catch (e) {
if (e?.status === 413) return error(res, 413, 'payload_too_large', 'request body exceeds the 20 MB limit');
return error(res, 400, 'bad_request', e?.message || 'could not read JSON body');
}
const glbUrl = typeof body?.glbUrl === 'string' && body.glbUrl.trim() ? body.glbUrl.trim() : null;
const renderUrl = typeof body?.renderUrl === 'string' && body.renderUrl.trim() ? body.renderUrl.trim() : null;
const renderBase64 = typeof body?.image === 'string' && body.image ? body.image : null;
if (!glbUrl && !renderUrl && !renderBase64) {
return error(res, 400, 'bad_request', 'supply one of glbUrl, renderUrl, or image (base64 / data URI)');
}
const prompt = typeof body?.prompt === 'string' ? body.prompt.slice(0, 2000) : null;
const subject = typeof body?.subject === 'string' ? body.subject : null;
const passScore = Number.isFinite(Number(body?.passScore)) ? Number(body.passScore) : QUALITY_GATE_DEFAULTS.passScore;
const mimeType = typeof body?.imageType === 'string' ? body.imageType : 'image/png';
const verdict = await runQualityGate({
glbUrl,
renderUrl,
renderBase64,
mimeType,
prompt,
subject,
passScore,
track: { userId, tool: 'api/forge-quality-check' },
});
// When the model failed the gate (and QA is available), hand back a concrete
// retry directive the caller can feed straight into a regeneration. tier/path/
// attempt come from the request so the caller can drive a real retry loop.
const retry = !verdict.pass && verdict.qa_available
? buildRetryDirective(verdict, {
prompt: prompt || '',
tier: typeof body?.tier === 'string' ? body.tier : 'standard',
path: typeof body?.path === 'string' ? body.path : 'image',
attempt: Number.isFinite(Number(body?.attempt)) ? Number(body.attempt) : 0,
maxRetries: QUALITY_GATE_DEFAULTS.maxRetries,
})
: null;
return json(res, 200, { verdict, retry }, { 'cache-control': 'no-store' });
});