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
fix(avatars): paint text-avatar references on the forge reference-image lane at 1:1 so the free FLUX rung stops returning a blurred portrait frame
nirholas966bd5984f27
diff --git a/api/avatars/_actions.js b/api/avatars/_actions.jsindex 35486d877..3afa1e2c2 100644--- a/api/avatars/_actions.js+++ b/api/avatars/_actions.js@@ -20,7 +20,7 @@ import { resolveProviderKey } from '../_lib/forge-provider-key.js';import { finalizeReconstructStage, pollRiggingStage } from '../_lib/reconstruct-finalize.js';import { finalizeAutoRigStage } from '../_lib/auto-rig.js';import { isAllowedProviderResultUrl } from '../_lib/provider-result-url.js';-import { textToImage } from '../_mcp3d/text-to-image.js';+import { generateReferenceImage } from '../_lib/forge-reference-image.js';import { planPromptAvatarLanes, promptAvatarImagePrompt } from '../_lib/prompt-avatar.js';import { laneHealthSnapshot } from '../_lib/forge-lane-health.js';@@ -1170,14 +1170,18 @@ const handleReconstruct = wrap(async (req, res) => {let referenceImageUrl = null;if (fromPrompt) {try {- const generated = await textToImage(promptAvatarImagePrompt(body.prompt), {- aspectRatio: '2:3',+ // The forge's reference-image lane (Vertex first, then the shared+ // text→image ladder), square like the forge's own avatar references:+ // the free FLUX rung returned a visibly blurred 832x1216 portrait+ // frame for this framing while its 1:1 output was sharp.+ const generated = await generateReferenceImage(promptAvatarImagePrompt(body.prompt), {+ aspectRatio: '1:1',});referenceImageUrl = generated.imageUrl;photos = [generated.imageUrl];} catch (err) {// Map the reference-image failure to the most accurate status so the- // symptom is self-explanatory instead of a blank 502. textToImage tags+ // symptom is self-explanatory instead of a blank 502. The text→image ladder tags// its errors: 'unconfigured' (no provider), 'rate_limited' (Replicate// throttle — common when account credit is low, carries retryAfter),// 'provider_unreachable' (network), or a raw providerStatus (e.g. 402@@ -1202,7 +1206,7 @@ const handleReconstruct = wrap(async (req, res) => {if (err?.code === 'billing' || err?.providerStatus === 402) {// Never relay the provider's raw "purchase credit at …/billing"// copy — even the error_description must be buyer-safe, since a- // client may surface it verbatim. textToImage already logged the+ // client may surface it verbatim. The text→image ladder already logged the// raw detail (providerDetail) for operators.return error(res,diff --git a/tests/api/prompt-avatar-routing.test.js b/tests/api/prompt-avatar-routing.test.jsindex 2dfa2d6b8..8efdc40e8 100644--- a/tests/api/prompt-avatar-routing.test.js+++ b/tests/api/prompt-avatar-routing.test.js@@ -28,7 +28,7 @@ import {vi.mock('../../api/_lib/zauth.js', () => ({ instrument: () => {}, drain: async () => {} }));vi.mock('../../api/_lib/sentry.js', () => ({ captureException: () => {} }));-const state = { inserts: [], health: {}, gcpSubmit: null, textToImageCalls: [] };+const state = { inserts: [], health: {}, gcpSubmit: null, referenceCalls: [] };const sqlMock = vi.fn(async (strings, ...values) => {const text = (Array.isArray(strings) ? strings.join('?') : String(strings)).toLowerCase();@@ -75,10 +75,10 @@ vi.mock('../../api/_lib/forge-provider-key.js', () => ({ resolveProviderKey: asyvi.mock('../../api/_lib/forge-lane-health.js', () => ({laneHealthSnapshot: async () => ({ byId: state.health, statusMap: {} }),}));-vi.mock('../../api/_mcp3d/text-to-image.js', () => ({- textToImage: vi.fn(async (prompt) => {- state.textToImageCalls.push(prompt);- return { imageUrl: 'https://cdn.example.com/ref/full-body.png' };+vi.mock('../../api/_lib/forge-reference-image.js', () => ({+ generateReferenceImage: vi.fn(async (prompt, opts) => {+ state.referenceCalls.push({ prompt, opts });+ return { imageUrl: 'https://cdn.example.com/ref/full-body.png', model: 'test' };}),}));@@ -169,7 +169,7 @@ describe('POST /api/avatars/reconstruct with a prompt', () => {beforeEach(() => {state.inserts = [];state.health = {};- state.textToImageCalls = [];+ state.referenceCalls = [];gcpInstance.submit.mockClear();state.gcpSubmit = async ({ mode }) => ({ extJobId: `env-${mode}`, eta: 120 });});@@ -178,7 +178,8 @@ describe('POST /api/avatars/reconstruct with a prompt', () => {const { statusCode, body } = await reconstruct({ name: 'Explorer', prompt: 'a silver-haired explorer in a teal flight jacket' });expect(statusCode).toBe(202);expect(body).toMatchObject({ ok: true, provider: 'gcp', status: 'queued' });- expect(state.textToImageCalls[0]).toMatch(/^a silver-haired explorer in a teal flight jacket, full-body/);+ expect(state.referenceCalls[0].prompt).toMatch(/^a silver-haired explorer in a teal flight jacket, full-body/);+ expect(state.referenceCalls[0].opts).toMatchObject({ aspectRatio: '1:1' });const call = gcpInstance.submit.mock.calls[0][0];expect(call.mode).toBe('hunyuan');@@ -205,7 +206,7 @@ describe('POST /api/avatars/reconstruct with a prompt', () => {it('still routes a photo submission through the face pipeline', async () => {const { statusCode } = await reconstruct({ name: 'Me', photos: ['https://cdn.example.com/selfie.jpg'] });expect(statusCode).toBe(202);- expect(state.textToImageCalls).toHaveLength(0);+ expect(state.referenceCalls).toHaveLength(0);expect(gcpInstance.submit.mock.calls[0][0].mode).toBe('reconstruct');expect(state.inserts[0].params.source).toBeUndefined();});