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(studio): generate avatars on the Hunyuan3D lane the docs already promised

nirholas7d22fc6acc66
diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.js
index 17076f732..d8fc0ee5f 100644
--- a/api/_mcp-studio/tools.js
+++ b/api/_mcp-studio/tools.js
@@ -339,6 +339,26 @@ function looksNonHumanoid(prompt) {
return NON_HUMANOID.test(t) && !HUMANOID.test(t);
}
+// Tier for AVATAR generation specifically (a person, not a prop).
+//
+// The router maps the image path's high tier to the self-hosted Hunyuan3D lane
+// and standard to TRELLIS (GET /api/forge?catalog, default_backend_for_tier).
+// On people that is the difference the whole likeness bar rests on: Hunyuan3D
+// is the organic/portrait-strength lane, and it is what the avatar skill has
+// documented these tools to request all along ("Both avatar tools always
+// request the platform's `high` quality tier under the hood"). The code was
+// still sending `standard`, so every avatar quietly came back off the weaker
+// lane while the docs promised otherwise.
+//
+// Asking for high is safe rather than a latency gamble: startForge degrades an
+// explicit high request to standard on a 402 (a deployment without the platform
+// seed token) or on a submit timeout, and a slow job returns a pollable handle
+// instead of an error. So the worst case is exactly today's behaviour.
+//
+// Props stay on standard. handleForgeFree documents its own reasoning for that
+// and a coffee cup gains nothing from the portrait lane.
+const AVATAR_TIER = 'high';
+
// ── handlers ────────────────────────────────────────────────────────────────
async function handleForgeFree(args, _auth, req) {
@@ -418,7 +438,7 @@ async function handleTextToAvatar(args, _auth, req) {
try {
job = await generate(
base,
- { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: 'standard', internal: true },
+ { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: AVATAR_TIER, internal: true },
{ timeoutEnv: 'STUDIO_FORGE_TIMEOUT_MS' },
);
} catch (err) {
@@ -531,7 +551,7 @@ async function handleForgeAvatar(args, _auth, req) {
try {
gen = await generate(
base,
- { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: 'standard', internal: true },
+ { prompt: effective || undefined, imageUrls: imageUrl ? [imageUrl] : undefined, aspect: '1:1', tier: AVATAR_TIER, internal: true },
{ timeoutEnv: 'STUDIO_FORGE_TIMEOUT_MS' },
);
} catch (err) {
diff --git a/tests/mcp-studio.test.js b/tests/mcp-studio.test.js
index 720387583..2cc6375bd 100644
--- a/tests/mcp-studio.test.js
+++ b/tests/mcp-studio.test.js
@@ -448,4 +448,75 @@ describe('mcp-studio dispatch', () => {
expect(r.error).toBeTruthy();
expect(spy).not.toHaveBeenCalled();
});
+
+ // The tier an avatar is generated on IS the likeness bar: the router maps the
+ // image path's high tier to the self-host Hunyuan3D lane and standard to
+ // TRELLIS. Both the avatar skill and the standalone MCP server
+ // (mcp-server/src/tools/_studio-core.js) have promised high for avatars for a
+ // while; this API-side twin was still sending standard, so every avatar
+ // quietly came off the weaker lane. Pin both halves of the contract.
+ describe('generation tier routing', () => {
+ // Captures the body of the POST /api/forge submit, letting the director's
+ // own fetch (which fails soft) pass through as an unusable response.
+ function stubForge() {
+ const submits = [];
+ globalThis.fetch = vi.fn(async (url, init) => {
+ const u = String(url);
+ // The studio submits through /api/gpt-forge (and /api/forge for the
+ // rig leg); match on the generation submit rather than a bare path so
+ // the art director's own LLM calls cannot be mistaken for one.
+ if (/\/api\/(gpt-)?forge/.test(u)) {
+ if (init?.method === 'POST') {
+ const body = JSON.parse(init.body);
+ if (body.tier) submits.push(body);
+ }
+ // Every forge call (submit, rig submit, and any job poll) answers
+ // finished, so the rigged chain runs to completion instead of
+ // spinning on a poll this test does not care about.
+ return {
+ ok: true,
+ status: 200,
+ json: async () => ({ status: 'done', glb_url: 'https://three.ws/cdn/creations/t.glb', job_id: 'T1', creation_id: 'C1', backend: 'hunyuan3d' }),
+ };
+ }
+ // Anything else (the art director's LLM chain) answers unusably so the
+ // handler falls back to the raw prompt instead of hanging the test.
+ return { ok: false, status: 503, json: async () => ({}), text: async () => '' };
+ });
+ return submits;
+ }
+
+ it('sends avatars to the high tier (the Hunyuan3D lane)', async () => {
+ const submits = stubForge();
+ await dispatch(
+ { jsonrpc: '2.0', id: 20, method: 'tools/call', params: { name: 'text_to_avatar', arguments: { prompt: 'a woman in a red jacket, standing' } } },
+ auth,
+ mkReq(),
+ );
+ expect(submits).toHaveLength(1);
+ expect(submits[0].tier).toBe('high');
+ });
+
+ it('sends the rigged avatar chain to the high tier too', async () => {
+ const submits = stubForge();
+ await dispatch(
+ { jsonrpc: '2.0', id: 21, method: 'tools/call', params: { name: 'forge_avatar', arguments: { prompt: 'a man in a blue suit, standing' } } },
+ auth,
+ mkReq(),
+ );
+ expect(submits.length).toBeGreaterThanOrEqual(1);
+ expect(submits[0].tier).toBe('high');
+ });
+
+ it('leaves props on the standard tier: a mesh gains nothing from the portrait lane', async () => {
+ const submits = stubForge();
+ await dispatch(
+ { jsonrpc: '2.0', id: 22, method: 'tools/call', params: { name: 'mesh_forge', arguments: { prompt: 'a ceramic coffee mug' } } },
+ auth,
+ mkReq(),
+ );
+ expect(submits).toHaveLength(1);
+ expect(submits[0].tier).toBe('standard');
+ });
+ });
});