Skip to content

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.

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.js
index 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.js
index 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: asy
vi.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();
});