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(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.jsindex 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.jsindex 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');+ });+ });});