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
// Tests for POST /api/3d/generate + GET /api/3d/generate?job=<id> — the free,
// keyless, agent-first text→3D front door that wraps the /api/forge draft lane.
//
// The rate limiter is mocked (switchable per test) and the network is stubbed via
// global fetch, so the suite runs fully offline while exercising the real handler,
// real originFromReq, real viewerUrl, and the real shape helpers against the REAL
// captured /api/forge draft-lane shapes (inline-done, queued, poll-done, failed).
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { Readable } from 'node:stream';
// Switchable free-lane quota — flip `freeOk` per test. mcp3dStatus (poll flood
// guard) always passes; it isn't the thing under test.
let freeOk = true;
let freeResult = { success: true, limit: 60, remaining: 59, reset: Date.now() + 3_600_000 };
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
mcp3dGenerateFree: async () =>
freeOk
? { success: true, limit: 60, remaining: 59, reset: Date.now() + 3_600_000 }
: freeResult,
mcp3dStatus: async () => ({
success: true,
limit: 240,
remaining: 239,
reset: Date.now() + 60_000,
}),
},
clientIp: () => '203.0.113.7',
}));
const ORIGINAL_FETCH = globalThis.fetch;
const ENV_KEYS = ['STUDIO_API_BASE', 'PUBLIC_APP_ORIGIN', 'APP_ORIGIN'];
const saved = {};
beforeEach(() => {
freeOk = true;
for (const k of ENV_KEYS) {
saved[k] = process.env[k];
delete process.env[k];
}
});
afterEach(() => {
for (const k of ENV_KEYS) {
if (saved[k] === undefined) delete process.env[k];
else process.env[k] = saved[k];
}
globalThis.fetch = ORIGINAL_FETCH;
vi.restoreAllMocks();
});
function makeReq({
method = 'POST',
url = '/api/3d/generate',
body = null,
host = 'three.ws',
} = {}) {
const raw = body == null ? '' : JSON.stringify(body);
const stream = Readable.from(raw ? [Buffer.from(raw)] : []);
stream.method = method;
stream.url = url;
stream.headers = { 'content-type': 'application/json', host };
return stream;
}
function makeRes() {
return {
statusCode: 200,
_h: {},
writableEnded: false,
headersSent: false,
setHeader(k, v) {
this._h[k.toLowerCase()] = v;
},
getHeader(k) {
return this._h[k.toLowerCase()];
},
end(body) {
this._body = body;
this.writableEnded = true;
},
};
}
async function dispatch(req, res) {
const mod = await import('../../api/3d/generate.js');
await mod.default(req, res);
return { res, body: res._body ? JSON.parse(res._body) : null };
}
function jsonResponse(obj, { status = 200 } = {}) {
return {
ok: status >= 200 && status < 300,
status,
headers: { get: () => 'application/json' },
json: async () => obj,
text: async () => JSON.stringify(obj),
};
}
// ── Real captured /api/forge draft-lane shapes (NVIDIA NIM TRELLIS) ───────────
const SUBMIT_DONE = {
job_id: null,
creation_id: 'a1b2c3d4-0000-4000-8000-000000000001',
status: 'done',
glb_url: 'https://three.ws/cdn/forge/anon/a1b2c3d4.glb',
durable: true,
backend: 'nvidia',
tier: 'draft',
path: 'image',
};
const SUBMIT_QUEUED = {
job_id: 'f1.eyJwIjoibnZpZGlhIiwiayI6InRleHQiLCJ0IjoibmltLXRhc2stMTIzIn0.c2lnbmF0dXJl',
creation_id: 'a1b2c3d4-0000-4000-8000-000000000002',
status: 'queued',
// forge's queued response spreads its provenance, which carries the lane ETA.
eta_seconds: 20,
};
const POLL_DONE = {
job_id: SUBMIT_QUEUED.job_id,
status: 'done',
glb_url: 'https://three.ws/cdn/forge/anon/done.glb',
durable: true,
};
const POLL_RUNNING = { job_id: SUBMIT_QUEUED.job_id, status: 'running' };
const POLL_FAILED = {
job_id: SUBMIT_QUEUED.job_id,
status: 'failed',
error: 'the generator hit a snag',
};
describe('shape helpers — lane boundary contract', () => {
it('shapeSubmit maps the inline-done shape to a done payload with a viewer URL', async () => {
const { shapeSubmit } = await import('../../api/3d/generate.js');
const out = shapeSubmit(SUBMIT_DONE, 'https://three.ws');
expect(out.status).toBe('done');
expect(out.glbUrl).toBe(SUBMIT_DONE.glb_url);
expect(out.viewerUrl).toBe(
'https://three.ws/viewer?src=' + encodeURIComponent(SUBMIT_DONE.glb_url),
);
expect(out.format).toBe('glb');
expect(out.tier).toBe('draft');
expect(out.free).toBe(true);
});
it('shapeSubmit maps the queued shape to a pending payload with the poll URL', async () => {
const { shapeSubmit } = await import('../../api/3d/generate.js');
const out = shapeSubmit(SUBMIT_QUEUED, 'https://three.ws');
expect(out.status).toBe('pending');
expect(out.job).toBe(SUBMIT_QUEUED.job_id);
expect(out.poll).toBe('/api/3d/generate?job=' + encodeURIComponent(SUBMIT_QUEUED.job_id));
expect(out.free).toBe(true);
});
it('shapeSubmit surfaces creationId, etaSeconds, and an ETA-derived retryAfter on pending', async () => {
const { shapeSubmit } = await import('../../api/3d/generate.js');
const out = shapeSubmit(SUBMIT_QUEUED, 'https://three.ws');
expect(out.creationId).toBe(SUBMIT_QUEUED.creation_id);
expect(out.etaSeconds).toBe(20);
expect(out.retryAfter).toBe(5); // round(20 / 4)
});
it('shapeSubmit surfaces creationId on the inline-done shape', async () => {
const { shapeSubmit } = await import('../../api/3d/generate.js');
const out = shapeSubmit(SUBMIT_DONE, 'https://three.ws');
expect(out.creationId).toBe(SUBMIT_DONE.creation_id);
expect(out.retryAfter).toBeUndefined(); // done carries no poll cadence
});
it('shapeSubmit defaults retryAfter to 3s when the lane reports no ETA', async () => {
const { shapeSubmit } = await import('../../api/3d/generate.js');
const out = shapeSubmit({ job_id: 'f1.abc.def', status: 'queued' }, 'https://three.ws');
expect(out.retryAfter).toBe(3);
expect(out.etaSeconds).toBeUndefined();
expect(out.creationId).toBeUndefined();
});
it('pollIntervalFromEta clamps to [2s, 10s] and defaults on junk input', async () => {
const { pollIntervalFromEta } = await import('../../api/3d/generate.js');
expect(pollIntervalFromEta(20)).toBe(5);
expect(pollIntervalFromEta(4)).toBe(2); // round(1) floored to min
expect(pollIntervalFromEta(200)).toBe(10); // clamped to max
expect(pollIntervalFromEta(0)).toBe(3);
expect(pollIntervalFromEta(NaN)).toBe(3);
expect(pollIntervalFromEta(undefined)).toBe(3);
});
it('shapePoll maps done/running/failed forge poll shapes', async () => {
const { shapePoll } = await import('../../api/3d/generate.js');
const done = shapePoll(POLL_DONE, 'https://three.ws', SUBMIT_QUEUED.job_id);
expect(done.status).toBe('done');
expect(done.glbUrl).toBe(POLL_DONE.glb_url);
expect(done.viewerUrl).toContain('/viewer?src=');
const pending = shapePoll(POLL_RUNNING, 'https://three.ws', SUBMIT_QUEUED.job_id);
expect(pending.status).toBe('pending');
expect(pending.poll).toContain('/api/3d/generate?job=');
expect(pending.retryAfter).toBe(3); // no ETA on the running poll shape → default cadence
const err = shapePoll(POLL_FAILED, 'https://three.ws', SUBMIT_QUEUED.job_id);
expect(err.status).toBe('error');
expect(err.error).toBe(POLL_FAILED.error);
expect(err.free).toBe(true);
});
});
describe('POST /api/3d/generate — validation', () => {
it('rejects an empty prompt with 400', async () => {
const { res, body } = await dispatch(makeReq({ body: { prompt: '' } }), makeRes());
expect(res.statusCode).toBe(400);
expect(body.error).toBe('invalid_prompt');
});
it('rejects a too-short prompt with 400', async () => {
const { res, body } = await dispatch(makeReq({ body: { prompt: 'ab' } }), makeRes());
expect(res.statusCode).toBe(400);
expect(body.error).toBe('invalid_prompt');
});
it('rejects an oversized prompt with 400', async () => {
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'x'.repeat(1001) } }),
makeRes(),
);
expect(res.statusCode).toBe(400);
expect(body.error).toBe('invalid_prompt');
});
it('rejects an unsupported format with 400', async () => {
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine', format: 'obj' } }),
makeRes(),
);
expect(res.statusCode).toBe(400);
expect(body.error).toBe('unsupported_format');
});
});
describe('POST /api/3d/generate — rate limit', () => {
it('returns 429 with an upgrade pointer when the free lane cap is hit', async () => {
freeOk = false;
freeResult = { success: false, limit: 60, remaining: 0, reset: Date.now() + 600_000 };
globalThis.fetch = vi.fn(async () => {
throw new Error('lane should not be called when rate-limited');
});
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine' } }),
makeRes(),
);
expect(res.statusCode).toBe(429);
expect(body.error).toBe('rate_limited');
expect(res.getHeader('retry-after')).toBeTruthy();
expect(body.upgrade.forgePro).toBe('/api/x402/forge');
expect(globalThis.fetch).not.toHaveBeenCalled();
});
});
describe('POST /api/3d/generate — response contract', () => {
it('returns { status: done, glbUrl, viewerUrl } when the lane finishes inline', async () => {
globalThis.fetch = vi.fn(async () => jsonResponse(SUBMIT_DONE));
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine' } }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('done');
expect(body.glbUrl).toBe(SUBMIT_DONE.glb_url);
expect(body.viewerUrl).toBe(
'https://three.ws/viewer?src=' + encodeURIComponent(SUBMIT_DONE.glb_url),
);
// The place-in-your-room AR link rides along, labeled with the prompt.
expect(body.arUrl).toBe(
'https://three.ws/api/ar?src=' +
encodeURIComponent(SUBMIT_DONE.glb_url) +
'&title=' +
encodeURIComponent('a small ceramic robot figurine'),
);
// The lane was submitted with the pinned free NVIDIA draft params.
const [, opts] = globalThis.fetch.mock.calls[0];
expect(JSON.parse(opts.body)).toMatchObject({
prompt: 'a small ceramic robot figurine',
backend: 'nvidia',
path: 'image',
tier: 'draft',
});
});
it('returns { status: pending, job, poll } when the lane queues the job, carrying the AR title', async () => {
globalThis.fetch = vi.fn(async () => jsonResponse(SUBMIT_QUEUED));
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine' } }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('pending');
expect(body.job).toBe(SUBMIT_QUEUED.job_id);
expect(body.poll).toBe(
'/api/3d/generate?job=' +
encodeURIComponent(SUBMIT_QUEUED.job_id) +
'&title=' +
encodeURIComponent('a small ceramic robot figurine'),
);
// Poll-cadence hint rides in both the body and the standard Retry-After header.
expect(body.retryAfter).toBe(5);
expect(body.etaSeconds).toBe(20);
expect(body.creationId).toBe(SUBMIT_QUEUED.creation_id);
expect(res.getHeader('retry-after')).toBe('5');
});
it('surfaces a 503 not_configured when the lane is unconfigured', async () => {
globalThis.fetch = vi.fn(async () =>
jsonResponse({ message: '3D generation is not configured' }, { status: 503 }),
);
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine' } }),
makeRes(),
);
expect(res.statusCode).toBe(503);
expect(body.error).toBe('not_configured');
});
it('maps an upstream 429 (GPU lane saturated) to 429 + retry-after', async () => {
globalThis.fetch = vi.fn(async () =>
jsonResponse({ message: 'busy', retry_after: 12 }, { status: 429 }),
);
const { res, body } = await dispatch(
makeReq({ body: { prompt: 'a small ceramic robot figurine' } }),
makeRes(),
);
expect(res.statusCode).toBe(429);
expect(body.error).toBe('rate_limited');
expect(res.getHeader('retry-after')).toBe('12');
});
});
describe('GET /api/3d/generate?job= — poll lifecycle', () => {
it('400s when no job param is present', async () => {
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: '/api/3d/generate' }),
makeRes(),
);
expect(res.statusCode).toBe(400);
expect(body.error).toBe('missing_job');
});
it('treats a whitespace-only job param as missing', async () => {
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: '/api/3d/generate?job=%20%20' }),
makeRes(),
);
expect(res.statusCode).toBe(400);
expect(body.error).toBe('missing_job');
});
it('400s on a malformed job handle', async () => {
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: '/api/3d/generate?job=bad*job*id' }),
makeRes(),
);
expect(res.statusCode).toBe(400);
expect(body.error).toBe('invalid_job');
});
it('returns pending while the job runs', async () => {
globalThis.fetch = vi.fn(async () => jsonResponse(POLL_RUNNING));
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('pending');
expect(body.poll).toContain('/api/3d/generate?job=');
expect(body.retryAfter).toBe(3);
expect(res.getHeader('retry-after')).toBe('3');
});
it('returns done with glbUrl + viewerUrl when the job finishes', async () => {
globalThis.fetch = vi.fn(async () => jsonResponse(POLL_DONE));
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('done');
expect(body.glbUrl).toBe(POLL_DONE.glb_url);
expect(body.viewerUrl).toContain('/viewer?src=');
});
it('returns status:error (no charge) when the job failed upstream', async () => {
globalThis.fetch = vi.fn(async () => jsonResponse(POLL_FAILED));
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('error');
expect(body.error).toBe(POLL_FAILED.error);
expect(body.free).toBe(true);
});
it('treats a transient poll network error as pending', async () => {
globalThis.fetch = vi.fn(async () => {
throw new Error('network blip');
});
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('pending');
});
it('503s instead of looping forever when the lane is unconfigured here', async () => {
// A deployment with no 3D lane answers the poll 503 unconfigured. Reporting
// that as 'pending' would hand the agent a poll loop that can never finish,
// so it has to surface as the same terminal not_configured the submit path
// returns.
globalThis.fetch = vi.fn(async () =>
jsonResponse({ error: 'unconfigured', message: 'Set NVIDIA_API_KEY.' }, { status: 503 }),
);
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(503);
expect(body.error).toBe('not_configured');
expect(body.status).toBeUndefined();
});
it('501 backend_unconfigured is terminal too, not pending', async () => {
globalThis.fetch = vi.fn(async () =>
jsonResponse(
{ error: 'backend_unconfigured', message: 'no NIM lane here' },
{ status: 501 },
),
);
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(503);
expect(body.error).toBe('not_configured');
});
it('keeps an unlabelled upstream 5xx as pending so the loop retries', async () => {
// Only an explicit unconfigured verdict is terminal; a bare 502 stays a blip.
globalThis.fetch = vi.fn(async () => jsonResponse({ error: 'boom' }, { status: 502 }));
const { res, body } = await dispatch(
makeReq({ method: 'GET', url: `/api/3d/generate?job=${SUBMIT_QUEUED.job_id}` }),
makeRes(),
);
expect(res.statusCode).toBe(200);
expect(body.status).toBe('pending');
});
});
describe('catalog entry', () => {
it('exports a well-formed entry the /api/3d index can merge', async () => {
const entry = (await import('../../api/_lib/3d-catalog/generate.js')).default;
expect(entry.slug).toBe('generate');
expect(entry.method).toBe('POST');
expect(entry.path).toBe('/api/3d/generate');
expect(entry.free).toBe(true);
expect(entry.inputSchema.required).toContain('prompt');
expect(entry.example.request.path).toBe('/api/3d/generate');
});
});