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 the text→image provider chain behind text→3D.
//
// Regression cover for the production outage where a mangled
// GCP_SERVICE_ACCOUNT_JSON took down ALL text→3D generation:
// • vertex-imagen must reject mangled service-account JSON with a designed
// `unconfigured` error, not a raw JSON.parse SyntaxError.
// • textToImage must fall back to Replicate flux when the preferred Vertex
// path throws for any reason (it previously trusted isConfigured(), which
// only checks GOOGLE_CLOUD_PROJECT, and never fell back).
// • A Vertex data: URI result must be persisted to object storage and
// returned as an https URL (Replicate caps inline data URIs well below an
// Imagen PNG's size, so forwarding the data URI breaks reconstruction).
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { cacheDel } from '../../api/_lib/cache.js';
const vertexState = { configured: false, generate: null };
vi.mock('../../api/_mcp3d/vertex-imagen.js', () => ({
isConfigured: () => vertexState.configured,
generateImage: (...a) => vertexState.generate(...a),
}));
const r2State = { puts: [] };
vi.mock('../../api/_lib/r2.js', () => ({
putObject: async (args) => {
r2State.puts.push(args);
},
publicUrl: (key) => `https://cdn.example/${key}`,
}));
// The Replicate text→image submit is paced through forge-scale's rate gate. The
// gate itself fails open without Redis (its own unit tests cover that); here we
// drive it deterministically so we can assert the queue/shed behavior of the
// caller. Defaults to "slot granted, no wait" so every other test is unaffected.
const rateState = { result: { ok: true, waitMs: 0 } };
vi.mock('../../api/_lib/forge-scale.js', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, reserveProviderRateSlot: vi.fn(async () => rateState.result) };
});
const ORIGINAL_FETCH = globalThis.fetch;
const ENV_KEYS = [
'NVIDIA_API_KEY',
'GOOGLE_CLOUD_PROJECT',
'GCP_SERVICE_ACCOUNT_JSON',
'REPLICATE_API_TOKEN',
'VERTEX_IMAGEN_ENABLED',
'VERTEX_IMAGEN_FIRST',
'LIVEPEER_FEDERATION_ENABLED',
'LIVEPEER_GATEWAY_URL',
];
const ORIGINAL_ENV = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
async function freshTextToImage() {
const mod = await import('../../api/_mcp3d/text-to-image.js?t=' + Math.random());
return mod.textToImage;
}
// Route a mocked fetch by host so a single test can exercise the full fallback
// chain (NIM → Vertex → Replicate) and assert which lanes were actually hit.
// Each route is [substringMatch, () => Response]; the first match wins.
function stubFetch(routes) {
const calls = [];
globalThis.fetch = vi.fn(async (url, opts = {}) => {
const u = String(url);
calls.push({ url: u, body: opts.body ? JSON.parse(opts.body) : null });
for (const [match, responder] of routes) {
if (u.includes(match)) return responder();
}
throw new Error(`unexpected fetch in test: ${u}`);
});
return calls;
}
// NIM FLUX artifacts are JPEG (probed live, tasks/nvidia-nim/probes/flux.md),
// so the fixture carries real JPEG magic bytes (ff d8 ff) for the format sniff.
const NIM_JPEG_BYTES = Buffer.concat([Buffer.from([0xff, 0xd8, 0xff, 0xe0]), Buffer.from('nim-jpeg-bytes')]);
function nimSuccessResponse(b64 = NIM_JPEG_BYTES.toString('base64')) {
return new Response(JSON.stringify({ artifacts: [{ base64: b64, finishReason: 'SUCCESS' }] }), {
status: 200,
headers: { 'content-type': 'application/json' },
});
}
function replicateSuccessResponse(url = 'https://replicate.delivery/out.png') {
return new Response(JSON.stringify({ id: 'pred_flux', status: 'succeeded', output: [url] }), {
status: 201,
headers: { 'content-type': 'application/json' },
});
}
function stubFluxSuccess() {
return stubFetch([['api.replicate.com', () => replicateSuccessResponse()]]);
}
beforeEach(async () => {
vertexState.configured = false;
vertexState.generate = null;
r2State.puts.length = 0;
rateState.result = { ok: true, waitMs: 0 };
for (const k of ENV_KEYS) delete process.env[k];
// The NIM FLUX circuit breaker persists a short cooldown in the shared in-memory
// cache; clear it between tests so one test's induced NIM failure doesn't make a
// later test skip the (now healthy) NIM lane it means to exercise.
await cacheDel('llm-cooldown:forge-nim-flux');
});
afterEach(() => {
globalThis.fetch = ORIGINAL_FETCH;
for (const k of ENV_KEYS) {
if (ORIGINAL_ENV[k] === undefined) delete process.env[k];
else process.env[k] = ORIGINAL_ENV[k];
}
vi.restoreAllMocks();
});
describe('textToImage: Vertex quality lane leads by default', () => {
it('serves from Vertex before NIM when both are configured (credit-burner first)', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
const png = Buffer.from('vertex-first-png').toString('base64');
vertexState.generate = vi.fn(async () => ({
imageUrl: `data:image/png;base64,${png}`,
model: 'vertex-ai/gemini-2.5-flash-image',
}));
const calls = stubFetch([['ai.api.nvidia.com', () => nimSuccessResponse()]]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.model).toBe('vertex-ai/gemini-2.5-flash-image');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(calls).toHaveLength(0); // NIM never touched, Vertex led and served
});
it('falls from a failed Vertex lead to NIM without surfacing an error', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => {
throw new Error('vertex down');
});
const calls = stubFetch([['ai.api.nvidia.com', () => nimSuccessResponse()]]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.model).toBe('black-forest-labs/flux.1-dev');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(calls).toHaveLength(1);
});
it('VERTEX_IMAGEN_FIRST=0 restores the legacy NIM-first order', async () => {
process.env.VERTEX_IMAGEN_FIRST = '0';
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => ({ imageUrl: 'data:image/png;base64,AAAA' }));
const calls = stubFetch([['ai.api.nvidia.com', () => nimSuccessResponse()]]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.model).toBe('black-forest-labs/flux.1-dev');
expect(vertexState.generate).not.toHaveBeenCalled();
expect(calls).toHaveLength(1);
});
});
describe('textToImage: NIM FLUX free lane (legacy NIM-first order)', () => {
beforeEach(() => {
// These pin the legacy ladder (NIM → Vertex → Replicate), preserved
// behind VERTEX_IMAGEN_FIRST=0.
process.env.VERTEX_IMAGEN_FIRST = '0';
});
it('serves from NIM and never touches Vertex or Replicate', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => ({ imageUrl: 'data:image/png;base64,AAAA' }));
const calls = stubFetch([['ai.api.nvidia.com', () => nimSuccessResponse()]]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.model).toBe('black-forest-labs/flux.1-dev');
// NIM output is JPEG, persisted bytes, key extension, and Content-Type
// must all say jpeg, not png (regression cover for the probe finding).
expect(result.imageUrl).toMatch(/^https:\/\/cdn\.example\/forge\/refs\/.+\.jpg$/);
// NIM artifact persisted to R2; Vertex and Replicate left untouched.
expect(r2State.puts).toHaveLength(1);
expect(r2State.puts[0].contentType).toBe('image/jpeg');
expect(r2State.puts[0].key).toMatch(/\.jpg$/);
expect(Buffer.compare(r2State.puts[0].body, NIM_JPEG_BYTES)).toBe(0);
expect(vertexState.generate).not.toHaveBeenCalled();
expect(calls).toHaveLength(1);
expect(calls[0].url).toContain('flux.1-dev');
expect(calls[0].body.prompt).toMatch(/^a red teapot/);
expect(calls[0].body).toMatchObject({ steps: 20, cfg_scale: 3.5 });
// schnell is guidance-distilled: the endpoint 422s on cfg_scale > 0
// (verified live), so the request must not send it at all.
});
it('maps aspect ratio to FLUX pixel dimensions', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
const calls = stubFetch([['ai.api.nvidia.com', () => nimSuccessResponse()]]);
const textToImage = await freshTextToImage();
await textToImage('a wide vista', { aspectRatio: '16:9' });
expect(calls[0].body).toMatchObject({ width: 1344, height: 768 });
});
it('falls through to Vertex when NIM fails', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
const png = Buffer.from('vertex-png').toString('base64');
vertexState.generate = vi.fn(async () => ({
imageUrl: `data:image/png;base64,${png}`,
model: 'vertex-ai/imagen-3.0-generate-001',
}));
const calls = stubFetch([['ai.api.nvidia.com', () => new Response('upstream boom', { status: 500 })]]);
vi.spyOn(console, 'error').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.model).toBe('vertex-ai/imagen-3.0-generate-001');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(calls).toHaveLength(1); // NIM was attempted exactly once before handoff
expect(Buffer.compare(r2State.puts[0].body, Buffer.from('vertex-png'))).toBe(0);
});
it('falls all the way through NIM → Vertex → Replicate', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => {
throw Object.assign(new Error('vertex down'), { code: 'unconfigured' });
});
// 500 is a terminal upstream fault (not a retryable gateway 502/503/504), so
// NIM is attempted once and the chain cascades straight through.
const calls = stubFetch([
['ai.api.nvidia.com', () => new Response('boom', { status: 500 })],
['api.replicate.com', () => replicateSuccessResponse()],
]);
vi.spyOn(console, 'error').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.imageUrl).toBe('https://replicate.delivery/out.png');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(calls.filter((c) => c.url.includes('ai.api.nvidia.com'))).toHaveLength(1);
expect(calls.some((c) => c.url.includes('api.replicate.com'))).toBe(true);
});
it('retries a transient NIM gateway 504 once, then succeeds inline', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
let nimHits = 0;
const calls = stubFetch([
[
'ai.api.nvidia.com',
() => {
nimHits += 1;
// First hit: a fast gateway 504 (cold model / routing blip).
// Second hit: the warmed model returns the artifact.
return nimHits === 1 ? new Response('gateway timeout', { status: 504 }) : nimSuccessResponse();
},
],
]);
vi.useFakeTimers();
try {
const textToImage = await freshTextToImage();
const p = textToImage('a red teapot');
await vi.advanceTimersByTimeAsync(2_000); // let the retry backoff elapse
const result = await p;
expect(result.model).toBe('black-forest-labs/flux.1-dev');
expect(calls.filter((c) => c.url.includes('ai.api.nvidia.com'))).toHaveLength(2);
} finally {
vi.useRealTimers();
}
});
it('does NOT retry a NIM timeout: hands off immediately to avoid a double wait', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
const calls = stubFetch([
[
'ai.api.nvidia.com',
() => {
// Emulate the AbortController firing: a timeout, not a gateway status.
const err = new Error('aborted');
err.name = 'TimeoutError';
throw err;
},
],
['api.replicate.com', () => replicateSuccessResponse()],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.imageUrl).toBe('https://replicate.delivery/out.png');
// NIM attempted exactly once, a timeout already burned the full window.
expect(calls.filter((c) => c.url.includes('ai.api.nvidia.com'))).toHaveLength(1);
});
// There is no "only configured lane" any more: keyless Pollinations always
// sits behind the keyed rungs. NIM's failure is logged and the ladder walks
// on; the terminal error is the LAST rung's, so a diagnosis reads the warns.
it('walks past a NIM failure to the keyless rung, and the terminal error is the last rung\'s', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
const calls = stubFetch([
['ai.api.nvidia.com', () => new Response('nope', { status: 401 })],
['image.pollinations.ai', () => new Response('down', { status: 503 })],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
await expect(textToImage('a red teapot')).rejects.toThrow(/pollinations returned 503/);
expect(calls.some((c) => c.url.includes('ai.api.nvidia.com'))).toBe(true);
});
it('skipNim bypasses the NIM lane entirely when a fallback exists', async () => {
// A caller that just watched a sibling NVCF lane time out passes skipNim so the
// degraded gateway never gets a second submit-timeout window this request.
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
const calls = stubFetch([['api.replicate.com', () => replicateSuccessResponse()]]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot', { skipNim: true });
expect(result.imageUrl).toBe('https://replicate.delivery/out.png');
expect(calls.some((c) => c.url.includes('ai.api.nvidia.com'))).toBe(false);
});
it('skipNim with no keyed fallback still lands on the keyless rung, never a dead end', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
const calls = stubFetch([
['ai.api.nvidia.com', () => nimSuccessResponse()],
['image.pollinations.ai', () => new Response(new Uint8Array([0xff, 0xd8, 0xff, 0xe0, 0, 0, 0, 0]), { status: 200, headers: { 'content-type': 'image/jpeg' } })],
]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot', { skipNim: true });
expect(result.model).toBe('pollinations/flux');
expect(calls.some((c) => c.url.includes('ai.api.nvidia.com'))).toBe(false);
});
it('a degraded NIM failure cools the lane so the next call skips it', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
const calls = stubFetch([
['ai.api.nvidia.com', () => new Response('boom', { status: 500 })],
['api.replicate.com', () => replicateSuccessResponse()],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
// First call trips the breaker (NIM 500 → cooldown), still serves via Replicate.
await textToImage('a red teapot');
const nimAfterFirst = calls.filter((c) => c.url.includes('ai.api.nvidia.com')).length;
expect(nimAfterFirst).toBe(1);
// Second call sees the cooldown and skips NIM straight to Replicate, no new NIM hit.
await textToImage('a blue teapot');
const nimAfterSecond = calls.filter((c) => c.url.includes('ai.api.nvidia.com')).length;
expect(nimAfterSecond).toBe(1);
});
});
// The Livepeer federation lane sits between the first-party free lanes and the
// paid Replicate backstop. It is a real downstream lane, so the ladder's
// "is there anything left to try" test has to count it: before this cover, a
// deployment whose ONLY downstream lane was Livepeer threw the upstream lane's
// error instead of handing off, and the configured federated lane never ran.
function livepeerSuccessResponse(url = 'https://gateway.test/images/out.png') {
return new Response(JSON.stringify({ images: [{ url, seed: 1, nsfw: false }] }), {
status: 200,
headers: { 'content-type': 'application/json' },
});
}
// A Livepeer job is TWO fetches against the same gateway host: POST
// /text-to-image returns the job JSON, then the artifact URL it names is
// downloaded and magic-byte verified before the lane is allowed to succeed.
// Route the artifact path FIRST (stubFetch is first-match-wins on a substring)
// so the download gets real PNG bytes instead of the job JSON, which the
// provider correctly rejects as "no image signature".
// A real PNG signature padded past the provider's 1 KB size floor, the same
// fixture shape tests/livepeer-federation.test.js uses.
const LIVEPEER_PNG_BYTES = Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
Buffer.alloc(2048, 1),
]);
function livepeerRoutes() {
return [
[
'gateway.test/images/',
() =>
new Response(LIVEPEER_PNG_BYTES, {
status: 200,
headers: { 'content-type': 'image/png' },
}),
],
['gateway.test', () => livepeerSuccessResponse()],
];
}
describe('textToImage: Livepeer federation lane counts as a real fallback', () => {
beforeEach(() => {
process.env.LIVEPEER_FEDERATION_ENABLED = '1';
process.env.LIVEPEER_GATEWAY_URL = 'https://gateway.test';
vi.spyOn(console, 'warn').mockImplementation(() => {});
});
it('hands a failed NIM lane off to Livepeer when it is the only lane downstream', async () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
const calls = stubFetch([
['ai.api.nvidia.com', () => new Response('boom', { status: 500 })],
...livepeerRoutes(),
]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
// The verified artifact is persisted to our own storage, so the lane
// returns the durable CDN URL, never the gateway's ephemeral one.
expect(result.imageUrl).toMatch(/^https:\/\/cdn\.example\/forge\/refs\/.+\.png$/);
expect(result.lane).toBe('livepeer');
expect(calls.some((c) => c.url.includes('gateway.test/images/'))).toBe(true);
});
it('hands a failed Vertex lead off to Livepeer when it is the only lane downstream', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
vertexState.generate = async () => {
throw new Error('vertex exploded');
};
const calls = stubFetch(livepeerRoutes());
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.imageUrl).toMatch(/^https:\/\/cdn\.example\/forge\/refs\/.+\.png$/);
expect(result.lane).toBe('livepeer');
expect(calls.some((c) => c.url.includes('gateway.test/images/'))).toBe(true);
});
it('with Livepeer off, the keyless rung is what stands between NIM and a dead end', async () => {
delete process.env.LIVEPEER_FEDERATION_ENABLED;
process.env.NVIDIA_API_KEY = 'nvapi-test';
const calls = stubFetch([
['ai.api.nvidia.com', () => new Response('nope', { status: 401 })],
['image.pollinations.ai', () => new Response('down', { status: 503 })],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
await expect(textToImage('a red teapot')).rejects.toThrow(/pollinations returned 503/);
expect(calls.some((c) => c.url.includes('gateway.test'))).toBe(false);
});
});
describe('textToImage: Vertex → Replicate fallback', () => {
it('falls back to Replicate flux when the Vertex path throws', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
vertexState.configured = true;
vertexState.generate = async () => {
throw Object.assign(new Error('GCP_SERVICE_ACCOUNT_JSON is set but is not valid'), {
code: 'unconfigured',
});
};
const calls = stubFluxSuccess();
vi.spyOn(console, 'error').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.imageUrl).toBe('https://replicate.delivery/out.png');
expect(calls.some((c) => c.url.includes('flux-schnell'))).toBe(true);
});
it('rethrows the Vertex error when no Replicate token exists to fall back to', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
vertexState.generate = async () => {
throw Object.assign(new Error('vertex broke'), { code: 'unconfigured' });
};
const textToImage = await freshTextToImage();
await expect(textToImage('a red teapot')).rejects.toThrow('vertex broke');
});
it('classifies a Replicate 429 as rate_limited without leaking the account credit balance', async () => {
// The production incident: a low-credit Replicate account throttles
// prediction creation and its `detail` names the balance. We must parse the
// reset hint for backoff and keep the raw detail for logs (providerDetail),
// but the surfaced message must be clean, no credit numbers, no $ amounts.
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
const RAW_DETAIL =
'Request was throttled. Your rate limit for creating predictions is reduced to 6 requests ' +
'per minute with a burst of 1 requests while you have less than $5.0 in credit. ' +
'Your rate limit resets in ~10s.';
stubFetch([
[
'api.replicate.com',
() =>
new Response(JSON.stringify({ detail: RAW_DETAIL }), {
status: 429,
headers: { 'content-type': 'application/json' },
}),
],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const caught = await textToImage('a red teapot').then(
() => null,
(e) => e,
);
expect(caught).toBeTruthy();
expect(caught.code).toBe('rate_limited');
expect(caught.retryAfter).toBe(10); // parsed from "resets in ~10s"
expect(caught.providerDetail).toBe(RAW_DETAIL); // retained for server logs
expect(caught.message).toBe('Image generation is briefly busy upstream, please retry in a few seconds.');
expect(caught.message).not.toMatch(/credit|\$5|throttl|rate limit/i);
});
it('queues against the Replicate rate gate and waits for the reserved slot before submitting', async () => {
// Under the reduced-rate account state Replicate paces creation to 6/min; the
// gate reserves the next slot and tells us to hold for it. We must wait out
// that slot, THEN submit, never fire early into a throttle 429.
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
rateState.result = { ok: true, waitMs: 5_000 };
const calls = stubFetch([['api.replicate.com', () => replicateSuccessResponse()]]);
vi.useFakeTimers();
try {
const textToImage = await freshTextToImage();
const p = textToImage('a red teapot');
// Mid-wait: the reserved slot has not opened, so no prediction is created yet.
await vi.advanceTimersByTimeAsync(4_000);
expect(calls.some((c) => c.url.includes('api.replicate.com'))).toBe(false);
// Slot opens, the submit fires and resolves.
await vi.advanceTimersByTimeAsync(2_000);
const result = await p;
expect(result.imageUrl).toBe('https://replicate.delivery/out.png');
expect(calls.some((c) => c.url.includes('api.replicate.com'))).toBe(true);
} finally {
vi.useRealTimers();
}
});
it('sheds to a queued rate-limit (no submit) when the queue is deeper than the wait budget', async () => {
// The gate reports the next slot is further out than we will block a worker for.
// We must NOT fire the prediction (that would just earn a throttle 429); instead
// surface a retryable, queued rate-limit carrying the time until the slot opens.
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
rateState.result = { ok: false, waitMs: 12_000 };
const calls = stubFetch([['api.replicate.com', () => replicateSuccessResponse()]]);
const textToImage = await freshTextToImage();
const caught = await textToImage('a red teapot').then(
() => null,
(e) => e,
);
expect(caught).toBeTruthy();
expect(caught.code).toBe('rate_limited');
expect(caught.queued).toBe(true);
expect(caught.retryAfter).toBe(12); // ceil(12000ms / 1000)
// The Replicate prediction was never created, we shed before firing.
expect(calls.some((c) => c.url.includes('api.replicate.com'))).toBe(false);
// The buyer-facing message names the queue, not the account's rate state.
expect(caught.message).not.toMatch(/credit|\$|throttl|rate limit/i);
});
it('masks a Replicate 402 out-of-credit failure as a buyer-safe billing error', async () => {
// The incident the user hit: the free NIM lane fell through to the paid
// Replicate backstop, which had zero credit. Replicate returns the hard
// "purchase credit at replicate.com/billing" copy on a 402, that vendor
// billing page must never reach the buyer. We keep the raw detail for logs
// (providerDetail) but the surfaced message must be neutral.
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
const RAW_DETAIL =
'You have insufficient credit to run this model. Go to ' +
'https://replicate.com/account/billing#billing to purchase credit. ' +
'Once you purchase credit, please wait a few minutes before trying again.';
stubFetch([
[
'api.replicate.com',
() =>
new Response(JSON.stringify({ detail: RAW_DETAIL }), {
status: 402,
headers: { 'content-type': 'application/json' },
}),
],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const caught = await textToImage('a red teapot').then(
() => null,
(e) => e,
);
expect(caught).toBeTruthy();
expect(caught.code).toBe('billing');
expect(caught.providerStatus).toBe(402);
expect(caught.providerDetail).toBe(RAW_DETAIL); // retained for server logs
expect(caught.message).toBe('image provider billing error');
// The raw vendor billing page and "buy credit" call-to-action must be gone.
expect(caught.message).not.toMatch(/credit|replicate\.com|purchase|insufficient/i);
});
it('masks a credit/billing message even on a non-402 status', async () => {
// Defense in depth: if Replicate ever delivers the same billing copy under
// a different 4xx, the content match must still keep it off the buyer.
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
stubFetch([
[
'api.replicate.com',
() =>
new Response(
JSON.stringify({ detail: 'Payment required: please purchase credit to continue.' }),
{ status: 400, headers: { 'content-type': 'application/json' } },
),
],
]);
vi.spyOn(console, 'warn').mockImplementation(() => {});
const textToImage = await freshTextToImage();
const caught = await textToImage('a red teapot').then(
() => null,
(e) => e,
);
expect(caught.code).toBe('billing');
expect(caught.providerStatus).toBe(402);
expect(caught.message).not.toMatch(/credit|purchase|payment/i);
});
it('polls a Replicate prediction that returns non-terminal, then resolves', async () => {
// Regression: under load / cold start Replicate returns the prediction still
// `starting` (Prefer: wait elapsed) with no output. The free text→3D lane
// must poll the prediction to completion, never dead-end on a transient
// "text-to-image did not complete (status: starting)".
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
let pollHits = 0;
stubFetch([
[
'/predictions/pred_poll',
() => {
pollHits += 1;
const done = pollHits >= 2;
return new Response(
JSON.stringify({
id: 'pred_poll',
status: done ? 'succeeded' : 'processing',
output: done ? ['https://replicate.delivery/polled.png'] : null,
}),
{ status: 200, headers: { 'content-type': 'application/json' } },
);
},
],
[
'flux-schnell',
() =>
new Response(
JSON.stringify({
id: 'pred_poll',
status: 'starting',
output: null,
urls: { get: 'https://api.replicate.com/v1/predictions/pred_poll' },
}),
{ status: 201, headers: { 'content-type': 'application/json' } },
),
],
]);
vi.useFakeTimers();
try {
const textToImage = await freshTextToImage();
const p = textToImage('a red teapot');
await vi.advanceTimersByTimeAsync(5_000); // let two poll intervals elapse
const result = await p;
expect(result.imageUrl).toBe('https://replicate.delivery/polled.png');
expect(result.predictionId).toBe('pred_poll');
expect(pollHits).toBeGreaterThanOrEqual(2);
} finally {
vi.useRealTimers();
}
});
it('surfaces a clean error when a polled Replicate prediction fails', async () => {
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
stubFetch([
[
'/predictions/pred_fail',
() =>
new Response(
JSON.stringify({ id: 'pred_fail', status: 'failed', error: 'NSFW content detected' }),
{ status: 200, headers: { 'content-type': 'application/json' } },
),
],
[
'flux-schnell',
() =>
new Response(
JSON.stringify({
id: 'pred_fail',
status: 'starting',
output: null,
urls: { get: 'https://api.replicate.com/v1/predictions/pred_fail' },
}),
{ status: 201, headers: { 'content-type': 'application/json' } },
),
],
]);
vi.useFakeTimers();
try {
const textToImage = await freshTextToImage();
const p = textToImage('a red teapot');
const settled = p.then(
() => null,
(e) => e,
);
await vi.advanceTimersByTimeAsync(3_000);
const caught = await settled;
expect(caught).toBeTruthy();
expect(caught.message).toMatch(/text-to-image failed/);
} finally {
vi.useRealTimers();
}
});
it('persists a Vertex data: URI to object storage and returns the https URL', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
vertexState.configured = true;
const png = Buffer.from('fake-png-bytes').toString('base64');
vertexState.generate = async () => ({
imageUrl: `data:image/png;base64,${png}`,
model: 'vertex-ai/imagen-3.0-generate-001',
});
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(result.imageUrl).toMatch(/^https:\/\/cdn\.example\/forge\/refs\/.+\.png$/);
expect(result.model).toBe('vertex-ai/imagen-3.0-generate-001');
expect(r2State.puts).toHaveLength(1);
expect(r2State.puts[0].contentType).toBe('image/png');
expect(Buffer.compare(r2State.puts[0].body, Buffer.from('fake-png-bytes'))).toBe(0);
});
});
describe('textToImage: VERTEX_IMAGEN_ENABLED gate', () => {
it('unset ⇒ current behavior: Vertex serves when the project is set', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => ({
imageUrl: `data:image/png;base64,${Buffer.from('vx').toString('base64')}`,
model: 'vertex-ai/gemini-2.5-flash-image',
}));
const calls = stubFetch([['api.replicate.com', () => replicateSuccessResponse()]]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(result.model).toBe('vertex-ai/gemini-2.5-flash-image');
expect(calls).toHaveLength(0); // Replicate never reached
});
it('=0 forces the Vertex lane off, falling through to Replicate', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.REPLICATE_API_TOKEN = 'r8_test_token';
process.env.VERTEX_IMAGEN_ENABLED = '0';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => {
throw new Error('vertex should never be called when gated off');
});
const calls = stubFluxSuccess();
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(vertexState.generate).not.toHaveBeenCalled();
expect(result.model).toBe('black-forest-labs/flux-schnell');
expect(calls.some((c) => c.url.includes('api.replicate.com'))).toBe(true);
});
it('=1 keeps the Vertex lane on', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
process.env.VERTEX_IMAGEN_ENABLED = '1';
vertexState.configured = true;
vertexState.generate = vi.fn(async () => ({
imageUrl: `data:image/png;base64,${Buffer.from('vx').toString('base64')}`,
model: 'vertex-ai/gemini-2.5-flash-image',
}));
stubFetch([]);
const textToImage = await freshTextToImage();
const result = await textToImage('a red teapot');
expect(vertexState.generate).toHaveBeenCalledOnce();
expect(result.model).toBe('vertex-ai/gemini-2.5-flash-image');
});
});
describe('enhanceFluxPrompt: realism + 3D-reference isolation suffixes', () => {
const ISOLATION = ', isolated subject, bright studio lighting, plain white background';
const REALISM =
', photorealistic, true-to-life materials and surface detail, sharp focus, professional product photograph';
async function enhance() {
const mod = await import('../../api/_mcp3d/text-to-image.js?t=' + Math.random());
return mod.enhanceFluxPrompt;
}
it('appends realism + isolation to a plain subject prompt (photoreal by default)', async () => {
const enhanceFluxPrompt = await enhance();
expect(enhanceFluxPrompt('a red teapot')).toBe('a red teapot' + REALISM + ISOLATION);
});
it('respects a named art style: isolation stays, realism words are withheld', async () => {
// Regression (older): "cartoon"/"stylized" must never suppress isolation,
// a cartoon fox still needs a plain background to reconstruct cleanly.
// New contract: those same words DO suppress the realism cues, which would
// otherwise fight the caller's explicit style.
const enhanceFluxPrompt = await enhance();
expect(enhanceFluxPrompt('a cartoon fox character standing upright')).toBe(
'a cartoon fox character standing upright' + ISOLATION,
);
expect(enhanceFluxPrompt('a stylized vibrant robot')).toBe('a stylized vibrant robot' + ISOLATION);
expect(enhanceFluxPrompt('a low-poly wolf')).toBe('a low-poly wolf' + ISOLATION);
expect(enhanceFluxPrompt('a watercolor bird')).toBe('a watercolor bird' + ISOLATION);
});
it('leaves the prompt untouched when it already sets a background / composition cue', async () => {
const enhanceFluxPrompt = await enhance();
for (const p of [
'a knight on a plain white background',
'an owl figurine, studio lighting',
'a vase isolated on white bg',
]) {
expect(enhanceFluxPrompt(p)).toBe(p);
}
});
it('matches whole words only: substrings never trigger or suppress', async () => {
const enhanceFluxPrompt = await enhance();
// "light" inside "lightsaber" is not a composition cue…
expect(enhanceFluxPrompt('a glowing lightsaber')).toBe('a glowing lightsaber' + REALISM + ISOLATION);
// …and "cartoonish" IS a style signal via the word boundary on "cartoon"?
// No: \b matches inside "cartoonish" only at the start, the suffix "ish"
// keeps the word alive, so assert the boundary behaves as written.
expect(enhanceFluxPrompt('a legolas figure')).toBe('a legolas figure' + REALISM + ISOLATION);
});
it('returns an empty prompt unchanged', async () => {
const enhanceFluxPrompt = await enhance();
expect(enhanceFluxPrompt('')).toBe('');
expect(enhanceFluxPrompt(' ')).toBe('');
});
});
describe('vertex-imagen: service-account JSON hardening', () => {
it('rejects mangled GCP_SERVICE_ACCOUNT_JSON with a designed unconfigured error', async () => {
process.env.GOOGLE_CLOUD_PROJECT = 'demo-project';
// The classic secrets-UI mangle: escaped quotes but no usable key material.
process.env.GCP_SERVICE_ACCOUNT_JSON = '{\\"type\\":\\"service_account\\"}';
const real = await vi.importActual('../../api/_mcp3d/vertex-imagen.js');
await expect(real.generateImage('a red teapot')).rejects.toMatchObject({
code: 'unconfigured',
});
});
});