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
// Self-hosted TRELLIS image→3D lane — registration, env-gated config, routing
// precedence, and the gcp provider's `trellis` mode wire contract.
//
// This lane wires our own Microsoft TRELLIS worker (workers/model-trellis) into
// /forge as a NATIVE single-hop image→3D engine: image → TRELLIS → GLB, no FLUX
// intermediate, no vendor cost. Unlike NVIDIA's hosted preview (text-only), a
// self-deployed NIM accepts real user photos, so this is the preferred free image
// lane when MODEL_TRELLIS_URL is configured. The worker speaks the standard task
// shape (POST /infer → GET /tasks/:id → result_gcs_url), distinct from the avatar
// pipeline's face-only `reconstruct` (/reconstruct + /jobs/:id).
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import {
BACKENDS,
resolveBackendId,
backendIsConfigured,
buildCatalog,
} from '../../api/_lib/forge-tiers.js';
import { createRegenProvider } from '../../api/_providers/gcp.js';
const VARS = [
'MODEL_TRELLIS_URL',
'MODEL_TRELLIS2_URL',
'GCP_RECONSTRUCTION_KEY',
'NVIDIA_API_KEY',
'HF_TOKEN',
];
const saved = {};
const ORIGINAL_FETCH = globalThis.fetch;
beforeEach(() => {
for (const v of VARS) {
saved[v] = process.env[v];
delete process.env[v];
}
});
afterEach(() => {
for (const v of VARS) {
if (saved[v] === undefined) delete process.env[v];
else process.env[v] = saved[v];
}
globalThis.fetch = ORIGINAL_FETCH;
vi.restoreAllMocks();
});
describe('forge-tiers — self-hosted TRELLIS backend registration', () => {
it('registers a free, platform-keyed image backend that accepts user photos', () => {
const b = BACKENDS.trellis_selfhost;
expect(b).toBeTruthy();
expect(b.provider).toBe('gcp');
expect(b.byok).toBe(false);
expect(b.paths).toEqual(['image']);
expect(b.requiresEnv).toEqual(['MODEL_TRELLIS_URL', 'GCP_RECONSTRUCTION_KEY']);
expect(b.free).toBe(true);
expect(b.userImages).toBe(true);
expect(b.credits).toBeNull();
expect(b.baseEta).toBeGreaterThan(0);
});
it('is configured only when BOTH the worker URL and the shared key are present', () => {
expect(backendIsConfigured('trellis_selfhost')).toBe(false);
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
expect(backendIsConfigured('trellis_selfhost')).toBe(false); // key still missing
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
expect(backendIsConfigured('trellis_selfhost')).toBe(true);
});
it('surfaces in the catalog as a free, photo-capable, selectable engine', () => {
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
const b = buildCatalog().backends.find((x) => x.id === 'trellis_selfhost');
expect(b).toBeTruthy();
expect(b.free).toBe(true);
expect(b.user_images).toBe(true);
expect(b.byok).toBeNull();
expect(b.configured).toBe(true);
const est = b.estimates.image.find((e) => e.tier === 'standard');
expect(est.eta_seconds).toBeGreaterThan(0);
expect(est.credits).toBeNull();
});
});
describe('forge-tiers — self-hosted TRELLIS routing precedence', () => {
it('becomes the preferred free image lane for photo submissions when configured', () => {
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
process.env.HF_TOKEN = 'hf_test'; // HF also live — TRELLIS must still win the photo default
process.env.NVIDIA_API_KEY = 'nvapi-test';
// Draft/standard photo uploads route to our self-hosted TRELLIS, ahead of HF.
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: true, country: 'US' })).toBe('trellis_selfhost');
expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: true, country: 'US' })).toBe('trellis_selfhost');
});
it('leads text prompts with the self-host photoreal reference pipeline too; high stays on self-host TRELLIS', () => {
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
process.env.HF_TOKEN = 'hf_test';
process.env.NVIDIA_API_KEY = 'nvapi-test';
// Text prompts at draft/standard now default to the self-host TRELLIS
// image-intermediate lane too — NVIDIA's native single-hop text→mesh
// preview skips the photoreal reference image, so it is no longer a
// named tier default anywhere (see forge-tiers.js FREE_DEFAULT_FOR_TIERS).
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: false, country: 'US' })).toBe('trellis_selfhost');
expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: false, country: 'US' })).toBe('trellis_selfhost');
// High names our self-host Hunyuan3D engine; unconfigured here, so the
// candidate walk falls to the self-host TRELLIS lane.
expect(resolveBackendId({ path: 'image', tier: 'high', country: 'US' })).toBe('trellis_selfhost');
});
it('degrades cleanly to HuggingFace when the worker URL is absent', () => {
// No MODEL_TRELLIS_URL → trellis_selfhost unconfigured → HF serves photos.
process.env.HF_TOKEN = 'hf_test';
process.env.NVIDIA_API_KEY = 'nvapi-test';
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: true, country: 'US' })).toBe('huggingface');
});
it('stays explicitly selectable (the handler owns any rejection)', () => {
// Even unconfigured, an explicit pick is honored at resolution time.
expect(
resolveBackendId({ path: 'image', tier: 'standard', backend: 'trellis_selfhost', userImages: true, country: 'US' }),
).toBe('trellis_selfhost');
});
});
describe('gcp provider — trellis mode wire contract', () => {
it('submits image→3D to the worker /infer endpoint and packs a pollable job', async () => {
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
const fetchMock = vi.fn(async (url, opts) => {
expect(url).toBe('https://trellis.example.run.app/infer');
const body = JSON.parse(opts.body);
expect(body.images).toEqual(['https://three.ws/cdn/photo.png']);
expect(body.body_type).toBe('neutral');
expect(opts.headers.authorization).toBe('Bearer secret');
return new Response(JSON.stringify({ task_id: 'task-123', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
globalThis.fetch = fetchMock;
const provider = createRegenProvider();
const submitted = await provider.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/photo.png',
params: { images: ['https://three.ws/cdn/photo.png'] },
});
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(submitted.extJobId).toBeTruthy();
expect(submitted.backend).toBe('gcp');
expect(submitted.viewsUsed).toBe(1);
expect(submitted.eta).toBeGreaterThan(0);
});
it('polls /tasks/:id and surfaces result_gcs_url as the GLB url on done', async () => {
process.env.MODEL_TRELLIS_URL = 'https://trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
// First call: submit (202 + task_id). Second call: poll (200 + done).
const calls = [];
globalThis.fetch = vi.fn(async (url) => {
calls.push(url);
if (url.endsWith('/infer')) {
return new Response(JSON.stringify({ task_id: 'task-xyz', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
}
// poll
expect(url).toBe('https://trellis.example.run.app/tasks/task-xyz');
return new Response(
JSON.stringify({
task_id: 'task-xyz',
status: 'done',
result_gcs_url: 'https://storage.googleapis.com/bucket/raw-meshes/trellis/task-xyz.glb',
}),
{ status: 200, headers: { 'content-type': 'application/json' } },
);
});
const provider = createRegenProvider();
const submitted = await provider.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/photo.png',
params: { images: ['https://three.ws/cdn/photo.png'] },
});
const status = await provider.status(submitted.extJobId);
expect(status.status).toBe('done');
expect(status.resultGlbUrl).toBe(
'https://storage.googleapis.com/bucket/raw-meshes/trellis/task-xyz.glb',
);
});
});
// ── Tier-scaled quality budgets (SELFHOST_TRELLIS_QUALITY) ───────────────────
// Standard/high must buy real sampler/export budget on our own GPU, and the
// gcp provider must forward exactly that object to the worker's /infer body.
describe('forge-tiers — self-host TRELLIS per-tier quality budgets', () => {
it('scales sampler steps, kept geometry, and texture size with the tier', async () => {
const { SELFHOST_TRELLIS_QUALITY, selfhostQualityForTier } = await import(
'../../api/_lib/forge-tiers.js'
);
const draft = selfhostQualityForTier('draft');
const standard = selfhostQualityForTier('standard');
const high = selfhostQualityForTier('high');
expect(draft).toBe(SELFHOST_TRELLIS_QUALITY.draft);
expect(standard.ss_steps).toBeGreaterThan(draft.ss_steps);
expect(high.ss_steps).toBeGreaterThan(standard.ss_steps);
expect(high.slat_steps).toBeGreaterThan(standard.slat_steps);
// simplify is the fraction REMOVED — higher tiers keep more triangles.
expect(standard.simplify).toBeLessThan(draft.simplify);
expect(high.simplify).toBeLessThan(standard.simplify);
expect(high.texture_size).toBeGreaterThanOrEqual(standard.texture_size);
// Worker clamps: stay inside the envelope it accepts (texture ceiling
// raised 2048→4096 alongside the worker's own quality-clamp bump).
for (const q of [draft, standard, high]) {
expect(q.ss_steps).toBeLessThanOrEqual(50);
expect(q.slat_steps).toBeLessThanOrEqual(50);
expect(q.texture_size).toBeLessThanOrEqual(4096);
}
});
it('falls back to the standard budget for an unknown tier id', async () => {
const { SELFHOST_TRELLIS_QUALITY, selfhostQualityForTier } = await import(
'../../api/_lib/forge-tiers.js'
);
expect(selfhostQualityForTier('nope')).toBe(SELFHOST_TRELLIS_QUALITY.standard);
expect(selfhostQualityForTier(undefined)).toBe(SELFHOST_TRELLIS_QUALITY.standard);
});
it('names trellis2 for the high tier and keeps hunyuan3d and huggingface only as fallback', async () => {
const { FREE_DEFAULT_FOR_TIERS, FREE_FALLBACK_FOR_PATH } = await import(
'../../api/_lib/forge-tiers.js'
);
expect(FREE_DEFAULT_FOR_TIERS.high.image).toBe('trellis2');
expect(FREE_FALLBACK_FOR_PATH.image).toContain('hunyuan3d');
expect(FREE_FALLBACK_FOR_PATH.image).toContain('huggingface');
});
});
describe('gcp provider — trellis quality forwarding', () => {
beforeEach(() => {
process.env.MODEL_TRELLIS_URL = 'https://model-trellis.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'test-worker-key';
});
it('forwards the quality object and seed verbatim in the /infer body', async () => {
const calls = [];
const origFetch = globalThis.fetch;
globalThis.fetch = vi.fn(async (url, opts) => {
calls.push({ url: String(url), body: JSON.parse(opts.body) });
return new Response(JSON.stringify({ task_id: 'tsk_1', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
try {
const { createRegenProvider: mk } = await import('../../api/_providers/gcp.js');
const gcp = mk();
const quality = { ss_steps: 45, slat_steps: 45, simplify: 0.85, texture_size: 2048 };
await gcp.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/ref.png',
params: { images: ['https://three.ws/cdn/ref.png'], seed: 7, quality },
});
expect(calls).toHaveLength(1);
expect(calls[0].url).toContain('/infer');
expect(calls[0].body.quality).toEqual(quality);
expect(calls[0].body.seed).toBe(7);
} finally {
globalThis.fetch = origFetch;
}
});
it('forwards matte:true only when the caller requests background pre-matting', async () => {
const bodies = [];
const origFetch = globalThis.fetch;
globalThis.fetch = vi.fn(async (url, opts) => {
bodies.push(JSON.parse(opts.body));
return new Response(JSON.stringify({ task_id: 'tsk_m', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
try {
const { createRegenProvider: mk } = await import('../../api/_providers/gcp.js');
const gcp = mk();
await gcp.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/ref.png',
params: { images: ['https://three.ws/cdn/ref.png'], matte: true },
});
await gcp.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/ref.png',
params: { images: ['https://three.ws/cdn/ref.png'] },
});
expect(bodies[0].matte).toBe(true);
expect(bodies[1]).not.toHaveProperty('matte');
} finally {
globalThis.fetch = origFetch;
}
});
it('omits quality/seed entirely when the caller sends none (worker defaults apply)', async () => {
const calls = [];
const origFetch = globalThis.fetch;
globalThis.fetch = vi.fn(async (url, opts) => {
calls.push({ body: JSON.parse(opts.body) });
return new Response(JSON.stringify({ task_id: 'tsk_2', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
try {
const { createRegenProvider: mk } = await import('../../api/_providers/gcp.js');
const gcp = mk();
await gcp.submit({
mode: 'trellis',
sourceUrl: 'https://three.ws/cdn/ref.png',
params: { images: ['https://three.ws/cdn/ref.png'] },
});
expect(calls[0].body).not.toHaveProperty('quality');
expect(calls[0].body).not.toHaveProperty('seed');
} finally {
globalThis.fetch = origFetch;
}
});
});
describe('gcp provider: trellis2 mode wire contract', () => {
it('forwards resolution, seed and the bake overrides to the TRELLIS.2 worker', async () => {
process.env.MODEL_TRELLIS2_URL = 'https://trellis2.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
let sent = null;
globalThis.fetch = vi.fn(async (url, opts) => {
expect(url).toBe('https://trellis2.example.run.app/infer');
sent = JSON.parse(opts.body);
return new Response(JSON.stringify({ task_id: 'task-t2', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
const provider = createRegenProvider();
await provider.submit({
mode: 'trellis2',
sourceUrl: 'https://three.ws/cdn/photo.png',
params: {
images: ['https://three.ws/cdn/photo.png'],
resolution: 1536,
seed: 7,
tier: 'standard',
texture_size: 2048,
decimation_target: 300000,
},
});
expect(sent).toMatchObject({
images: ['https://three.ws/cdn/photo.png'],
resolution: 1536,
seed: 7,
tier: 'standard',
texture_size: 2048,
decimation_target: 300000,
});
});
it('leaves the bake overrides to the resolution preset when absent', async () => {
process.env.MODEL_TRELLIS2_URL = 'https://trellis2.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
let sent = null;
globalThis.fetch = vi.fn(async (_url, opts) => {
sent = JSON.parse(opts.body);
return new Response(JSON.stringify({ task_id: 'task-t3', status: 'queued' }), {
status: 202,
headers: { 'content-type': 'application/json' },
});
});
await createRegenProvider().submit({
mode: 'trellis2',
sourceUrl: 'https://three.ws/cdn/photo.png',
params: { images: ['https://three.ws/cdn/photo.png'], tier: 'draft' },
});
expect(sent).not.toHaveProperty('texture_size');
expect(sent).not.toHaveProperty('decimation_target');
});
});