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
// Hugging Face provider for avatar reconstruction.
//
// Calls HF Space Gradio /call/<api_name> endpoints for image-to-3D inference.
// Why "HF Spaces" instead of HF Inference Endpoints: image-to-3D model families
// (Hunyuan3D, TRELLIS, InstantMesh) need GPUs and aren't served on the
// serverless Inference API. Spaces give free GPU access — at the cost of
// queue waits and frequent cold-start / runtime failures.
//
// Failover: HF Spaces are unreliable (the headline Space goes down with
// "No @spaces.GPU function detected" or hits the queue, etc). We try a chain
// of Spaces in order and return the first GLB we get. Each Space has its own
// /call API name + payload builder so the chain can include different model
// families (Hunyuan3D, TRELLIS, etc).
//
// Submit is BLOCKING: Gradio queue state lives in the server-side event_id
// with no reconnect; once /call/<api>/<event_id> SSE is consumed, the result
// is gone. The reconstruct endpoint's maxDuration is 300s in vercel.json to
// absorb queue wait + processing.
//
// status() echoes the resultGlbUrl back from a packed extJobId so the
// regenerate-status poll loop materializes the avatar without re-hitting HF.
//
// Env:
// HF_TOKEN — required; huggingface.co/settings/tokens
// (read-only OK; public Spaces don't need write)
// HF_RECONSTRUCT_SPACES — comma-separated chain of Space slugs to try
// in order. Format: "owner/name[:api_name]"
// Default: a hand-curated chain of currently
// working textured-GLB Spaces.
// HF_RECONSTRUCT_SPACE — legacy single-target alias; converted into
// a 1-element chain if HF_RECONSTRUCT_SPACES
// is unset.
// HF_RECONSTRUCT_API_NAME — legacy single-API alias.
import { fetchUpstream } from '../_lib/upstream-fetch.js';
const HF_INFERENCE_TIMEOUT_MS = 280_000; // leave headroom for response framing
// Per-call deadlines. The SSE read is bounded by HF_INFERENCE_TIMEOUT_MS in
// consumeSseUntilComplete; its fetch deadline sits above that as a backstop
// (the signal covers the body read too, so it must not be shorter). The
// enqueue and the GLB download are single attempts: the outer Space chain and
// candidate loop already decide what to retry.
const HF_ENQUEUE_TIMEOUT_MS = 60_000;
const HF_SSE_TIMEOUT_MS = HF_INFERENCE_TIMEOUT_MS + 10_000;
const HF_GLB_DOWNLOAD_TIMEOUT_MS = 120_000;
// A reconstructed GLB is served from the Space's ephemeral gradio /tmp path,
// which is purged minutes (sometimes seconds) after the run. Every consumer of
// this provider — the forge image lane and the avatar reconstruct poll — fetches
// the result URL *later*, by which point the temp file can already be gone,
// surfacing as a client-side 404 in model-viewer's loader. So the instant the
// SSE completes (when the temp file is freshest) we pull the bytes and re-host
// them to durable object storage, returning that URL instead. This is fail-soft:
// a deployment without object storage configured keeps the raw Space URL exactly
// as before, so nothing regresses where there's nowhere durable to put it.
const REHOST_MAX_GLB_BYTES = 64 * 1024 * 1024; // 64 MB ceiling, matching reconstruct-finalize
const REHOST_MAX_ATTEMPTS = 3;
const REHOST_RETRY_BASE_MS = 350;
// Ordered failover chain. We try each entry in order until one returns a GLB.
// Each entry is { space, api, builder } where builder shapes the Gradio
// payload from the selfie photos. Add new Spaces as they come online; keep
// the most reliable / highest-quality at the top.
//
// Verified targets (2026-06, probed live against each Space's Gradio /info):
// tencent/Hunyuan3D-2 — textured GLB via /generation_all (highest quality;
// flaky GPU/queue, recovers)
// tencent/Hunyuan3D-2.1 — successor; same /generation_all shape
// stabilityai/TripoSR — fast feed-forward via /generate; takes
// [image, mc_resolution] and returns [OBJ, GLB].
// Reliable terminal fallback — keep it last so the
// chain always has a Space that actually returns a GLB.
//
// JeffreyXiang/TRELLIS was removed: the Space host now 404s (taken down), so
// listing it only burned a failover hop. Re-add a working TRELLIS Space here (or
// via HF_RECONSTRUCT_SPACES) if one comes back online.
const HF_FAILOVER_CHAIN = [
{ space: 'tencent/Hunyuan3D-2', api: 'generation_all', builder: 'hunyuan' },
{ space: 'tencent/Hunyuan3D-2.1', api: 'generation_all', builder: 'hunyuan' },
{ space: 'stabilityai/TripoSR', api: 'generate', builder: 'triposr' },
];
function readEnv(name) {
if (typeof process !== 'undefined' && process.env && process.env[name]) return process.env[name];
return null;
}
function packExtJobId(payload) {
return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
}
function unpackExtJobId(extJobId) {
try {
return JSON.parse(Buffer.from(extJobId, 'base64url').toString('utf8'));
} catch {
return null;
}
}
function spaceBaseUrl(slug) {
// HF subdomain: lowercase, all non-alphanumeric chars → hyphens.
// e.g. tencent/Hunyuan3D-2.1 → tencent-hunyuan3d-2-1.hf.space
const host = slug.replace(/[^a-z0-9]+/gi, '-').toLowerCase();
return `https://${host}.hf.space`;
}
// Gradio file-component input. data: URIs and http(s) URLs both work; the
// Space's preprocessor will fetch URLs server-side.
function toFileData(imageUrl) {
if (!imageUrl) return null;
return {
path: imageUrl,
url: imageUrl,
meta: { _type: 'gradio.FileData' },
};
}
function withTimeout(promise, ms, message) {
let timer;
const timeout = new Promise((_, reject) => {
timer = setTimeout(() => reject(new Error(message)), ms);
});
return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}
// Walk a Gradio output tree for the first GLB-looking file and return every
// address that file might be reachable at, in order of reliability. The Space
// returns outputs like:
// [ { path: "/tmp/x.glb", url: "https://...hf.space/file=/tmp/x.glb", ... },
// { ...white-mesh file...}, "Output text", {...stats...}, 1234 ]
// We want the *first* file: it's the textured mesh from /generation_all.
//
// Multiple candidates exist because a FileData's self-reported `url` is not
// trustworthy: Spaces behind HF's replica router stamp it with a stale proxy
// prefix (observed live on stabilityai/TripoSR: url ".../ca/file=/tmp/...glb"
// 404s while ".../file=/tmp/...glb" serves the same file). Building the URL
// from `path` with the canonical /file= route (Gradio ≤4) is the proven-good
// form, so it goes first; the reported url and the Gradio 5 /gradio_api/file=
// route follow as fallbacks.
function extractFirstGlbCandidates(data, spaceUrl) {
const fromFileData = (node) => {
const path = typeof node.path === 'string' && /\.glb($|\?)/i.test(node.path) ? node.path : null;
const url = typeof node.url === 'string' && /\.glb($|\?)/i.test(node.url) ? node.url : null;
if (!path && !url) return null;
const candidates = [];
if (path) {
if (/^https?:\/\//i.test(path)) candidates.push(path);
else {
const rel = path.startsWith('/') ? path : `/${path}`;
candidates.push(`${spaceUrl}/file=${rel}`, `${spaceUrl}/gradio_api/file=${rel}`);
}
}
if (url && /^https?:\/\//i.test(url)) candidates.push(url);
return candidates.length ? candidates : null;
};
const visit = (node) => {
if (!node) return null;
if (typeof node === 'string') {
if (/^https?:\/\/.+\.glb($|\?)/i.test(node)) return [node];
return null;
}
if (Array.isArray(node)) {
for (const child of node) {
const found = visit(child);
if (found) return found;
}
return null;
}
if (typeof node === 'object') {
const direct = fromFileData(node);
if (direct) return direct;
for (const v of Object.values(node)) {
const found = visit(v);
if (found) return found;
}
}
return null;
};
return visit(data);
}
// Build the 13-arg payload for tencent/Hunyuan3D-2 /generation_all.
//
// Parameters in order:
// caption(str), image(file), mv_front, mv_back, mv_left, mv_right,
// steps(int), guidance_scale(float), seed(int), octree_resolution(int),
// check_box_rembg(bool), num_chunks(int), randomize_seed(bool)
//
// We default to the Space's own defaults so users get a baseline-quality
// result; selfie callers can override via params.steps / params.seed / etc.
function buildHunyuanPayload({ photos, params }) {
const [frontal, left, right] = photos;
return [
params?.caption ?? '',
toFileData(params?.image || frontal),
toFileData(frontal),
null, // mv_back — we don't capture a back photo in the selfie flow
toFileData(left),
toFileData(right),
Number(params?.steps ?? 30),
Number(params?.guidance_scale ?? 5.0),
Number(params?.seed ?? 1234),
Number(params?.octree_resolution ?? 256),
params?.check_box_rembg !== false,
Number(params?.num_chunks ?? 8000),
params?.randomize_seed !== false,
];
}
// Stream SSE response and resolve with the parsed `complete` payload.
// Throws on `error` event or when the stream ends without `complete`.
async function consumeSseUntilComplete(response) {
if (!response.ok || !response.body) {
const body = await response.text().catch(() => '');
throw Object.assign(
new Error(`huggingface /call stream not available: ${response.status} ${body.slice(0, 200)}`),
{ code: 'provider_error', status: 502 },
);
}
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let buffer = '';
let pendingEvent = null;
let result = null;
let errorMessage = null;
const drain = (async () => {
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let nlIdx;
while ((nlIdx = buffer.indexOf('\n')) >= 0) {
const line = buffer.slice(0, nlIdx).replace(/\r$/, '');
buffer = buffer.slice(nlIdx + 1);
if (line === '') {
pendingEvent = null;
continue;
}
if (line.startsWith('event:')) {
pendingEvent = line.slice(6).trim();
continue;
}
if (line.startsWith('data:')) {
const dataStr = line.slice(5).trim();
if (pendingEvent === 'complete') {
try { result = JSON.parse(dataStr); } catch { result = dataStr; }
return;
}
if (pendingEvent === 'error') {
// Gradio emits `data: null` on its error event when the Space dies
// without a message — free-tier GPU quota exhausted or the Space
// sleeping/rebuilding. Passing that through produced the useless
// "inference failed: null" in production logs; name the likely
// cause instead so the failover log line is diagnosable.
errorMessage = dataStr && dataStr !== 'null' && dataStr !== '""'
? dataStr
: 'Space error event with no detail (typically GPU quota exhausted or Space sleeping)';
return;
}
// heartbeat / generating / unknown: ignore
}
}
}
})();
try {
await withTimeout(drain, HF_INFERENCE_TIMEOUT_MS, 'huggingface SSE stream timed out');
} catch (err) {
try { await reader.cancel(); } catch (_) {}
throw Object.assign(
new Error(err?.message || 'huggingface stream timed out'),
{ code: 'provider_timeout', status: 504 },
);
}
if (errorMessage) {
throw Object.assign(new Error(`huggingface inference failed: ${errorMessage}`), {
code: 'provider_error',
status: 502,
// The no-detail error (and any explicit quota message) is the signature
// of ZeroGPU quota exhaustion. It is scoped to the *identity* making the
// call: an exhausted account fails while the same request succeeds
// anonymously on per-IP quota. runOnSpace uses this to retry once
// without the bearer token before advancing the failover chain.
quotaLike: /quota/i.test(errorMessage) || errorMessage.startsWith('Space error event with no detail'),
});
}
if (result === null) {
throw Object.assign(new Error('huggingface stream closed without complete event'), {
code: 'provider_error',
status: 502,
});
}
return result;
}
// Resolve the failover chain from env, falling back to the curated default.
//
// Precedence (first present wins):
// HF_RECONSTRUCT_SPACES — comma-separated "owner/name[:api]" pairs
// HF_RECONSTRUCT_SPACE — legacy single-Space alias (uses HF_RECONSTRUCT_API_NAME or 'generation_all')
// HF_FAILOVER_CHAIN — curated default chain (this module)
function resolveChain() {
const chainCsv = readEnv('HF_RECONSTRUCT_SPACES');
if (chainCsv) {
return chainCsv
.split(',')
.map((entry) => entry.trim())
.filter(Boolean)
.map((entry) => {
const [space, api] = entry.split(':');
return {
space,
api: api || 'generation_all',
builder: builderForApi(api),
};
});
}
const legacySpace = readEnv('HF_RECONSTRUCT_SPACE');
if (legacySpace) {
const api = readEnv('HF_RECONSTRUCT_API_NAME') || 'generation_all';
return [{ space: legacySpace, api, builder: builderForApi(api) }];
}
return HF_FAILOVER_CHAIN;
}
// Pick the payload builder for an env-supplied "owner/name[:api]" entry from its
// Gradio api_name. /generation_all is Hunyuan3D's 13-arg shape; /generate is
// TripoSR's [image, mc_resolution]; anything else (single-image endpoints) gets
// the bare one-file payload.
function builderForApi(api) {
if (!api || api === 'generation_all') return 'hunyuan';
if (api === 'generate') return 'triposr';
return 'single';
}
// Per-Space payload builders. Map our normalized {photos, params} into the
// argument list that Space's Gradio endpoint expects.
const BUILDERS = {
hunyuan: ({ photos, params }) => buildHunyuanPayload({ photos, params }),
single: ({ photos }) => [toFileData(photos[0])],
// stabilityai/TripoSR /generate: (image filepath, marching-cubes resolution
// float) → [OBJ, GLB]. We pass the reference view straight through — the forge
// image lane already supplies a clean subject view — and take the GLB output;
// extractFirstGlbCandidates skips the OBJ and returns the .glb.
triposr: ({ photos, params }) => [toFileData(photos[0]), Number(params?.mc_resolution ?? 256)],
};
// Object storage is configured only when every S3 var the bucket helpers read is
// present. Matches forge-store's gate so a partially-configured deployment skips
// re-hosting (and keeps the raw Space URL) instead of throwing mid-run.
function r2Configured() {
return Boolean(
readEnv('S3_ENDPOINT') &&
readEnv('S3_BUCKET') &&
readEnv('S3_PUBLIC_DOMAIN') &&
readEnv('S3_ACCESS_KEY_ID') &&
readEnv('S3_SECRET_ACCESS_KEY'),
);
}
// Pull the freshly-produced GLB and re-host it to durable storage, returning the
// public URL. The HF bearer token is forwarded so private Spaces' file endpoints
// authorize the read; public Spaces ignore it.
//
// Two terminal outcomes, deliberately distinct:
// • Storage unconfigured → return null. There is nowhere durable to put the
// mesh, so the caller keeps the raw Space URL exactly as before. Nothing
// regresses on storage-less deployments.
// • Storage configured but the rehost can't complete (the temp file already
// 404'd, the fetch errored after retries, the body was empty/oversize, or
// the upload failed) → THROW. Returning the raw gradio /tmp URL here would
// be worse than failing: that URL is ephemeral and *will* 404 when a later
// consumer (the forge poll, materializeCreation, model-viewer's loader)
// fetches it — the exact "materializeCreation failed: ...glb 404" this
// function exists to prevent. Throwing lets the failover loop regenerate on
// the next Space, and if the chain is exhausted the caller surfaces a
// designed error instead of a doomed URL.
async function rehostGlbToR2(glbUrls, token) {
if (!r2Configured()) return null;
const candidates = Array.isArray(glbUrls) ? glbUrls : [glbUrls];
let buf = null;
let lastErr = null;
candidateLoop:
for (const glbUrl of candidates) {
for (let attempt = 1; attempt <= REHOST_MAX_ATTEMPTS; attempt++) {
try {
const resp = await fetchUpstream(glbUrl, { headers: spaceAuthHeaders(token) }, { timeoutMs: HF_GLB_DOWNLOAD_TIMEOUT_MS, attempts: 1, okWhen: () => true });
if (!resp.ok) {
lastErr = Object.assign(new Error(`GLB fetch ${resp.status}`), { status: resp.status });
// 404/410 on this address = wrong route or the temp file is gone;
// retrying the same URL can't recover it, but another candidate
// address for the same file still might (a stale proxy-prefixed
// `url` 404s while the canonical /file= route serves the bytes).
if (resp.status === 404 || resp.status === 410) continue candidateLoop;
} else {
const bytes = Buffer.from(await resp.arrayBuffer());
if (bytes.length === 0) { lastErr = new Error('GLB body was empty'); break candidateLoop; }
if (bytes.length > REHOST_MAX_GLB_BYTES) {
lastErr = new Error(`GLB too large: ${bytes.length} bytes`);
break candidateLoop;
}
buf = bytes;
break candidateLoop;
}
} catch (err) {
lastErr = err;
}
if (attempt < REHOST_MAX_ATTEMPTS) {
await new Promise((r) => setTimeout(r, REHOST_RETRY_BASE_MS * attempt));
}
}
}
if (!buf) {
throw Object.assign(
new Error(`GLB rehost failed: ${lastErr?.message || 'unknown error'}`),
{ code: 'rehost_failed', status: lastErr?.status, cause: lastErr },
);
}
const { putObject, publicUrl } = await import('../_lib/r2.js');
const { randomUUID } = await import('node:crypto');
const key = `hf-recon/${randomUUID()}.glb`;
await putObject({
key,
body: buf,
contentType: 'model/gltf-binary',
metadata: { source: 'huggingface-reconstruct' },
});
return publicUrl(key);
}
// Authorization header set for a Space call. Anonymous calls (token=null) must
// omit the header entirely — "Bearer null" is an invalid credential, not anon.
function spaceAuthHeaders(token) {
return token ? { authorization: `Bearer ${token}` } : {};
}
// Try one Space end-to-end, first with the platform HF token, and once more
// anonymously when the authed run dies with the ZeroGPU quota signature.
// Public Spaces meter anonymous callers per-IP, a separate allowance from the
// account's — so an exhausted platform account (observed live 2026-07-16: the
// same TripoSR request errored with the token and produced a GLB without it)
// must not take the whole rung down. Throws with a tagged error containing the
// Space slug so the failover loop can decide whether to advance.
async function runOnSpace({ token, target, photos, params }) {
try {
return await attemptOnSpace({ token, target, photos, params });
} catch (err) {
if (!token || !err?.quotaLike) throw err;
console.warn(
`[hf] ${target.space} hit the quota signature with the platform token; retrying anonymously on per-IP quota`,
);
return attemptOnSpace({ token: null, target, photos, params });
}
}
async function attemptOnSpace({ token, target, photos, params }) {
const { space, api, builder } = target;
const spaceUrl = spaceBaseUrl(space);
const payloadBuilder = BUILDERS[builder] || BUILDERS.single;
const payload = payloadBuilder({ photos, params });
const tag = (err) => Object.assign(err, { spaceSlug: space, apiName: api });
// Step 1 — POST /call/<api> to enqueue. Returns event_id.
let queueRes;
try {
queueRes = await fetchUpstream(`${spaceUrl}/call/${api}`, {
method: 'POST',
headers: { ...spaceAuthHeaders(token), 'content-type': 'application/json' },
body: JSON.stringify({ data: payload }),
}, { timeoutMs: HF_ENQUEUE_TIMEOUT_MS, attempts: 1, okWhen: () => true });
} catch (err) {
throw tag(Object.assign(new Error(`enqueue failed: ${err?.message}`), {
code: 'provider_unreachable',
status: 502,
}));
}
if (!queueRes.ok) {
const body = await queueRes.text().catch(() => '');
throw tag(Object.assign(
new Error(`enqueue ${queueRes.status}: ${body.slice(0, 200)}`),
{ code: 'provider_error', status: 502, providerStatus: queueRes.status },
));
}
const queueBody = await queueRes.json().catch(() => ({}));
const eventId = queueBody?.event_id;
if (!eventId) {
throw tag(Object.assign(new Error('no event_id returned'), { code: 'provider_error', status: 502 }));
}
// Step 2 — GET /call/<api>/<event_id> SSE; block until complete.
let streamRes;
try {
streamRes = await fetchUpstream(`${spaceUrl}/call/${api}/${eventId}`, {
headers: { ...spaceAuthHeaders(token), accept: 'text/event-stream' },
}, { timeoutMs: HF_SSE_TIMEOUT_MS, attempts: 1, okWhen: () => true });
} catch (err) {
throw tag(Object.assign(new Error(`SSE GET failed: ${err?.message}`), {
code: 'provider_unreachable',
status: 502,
}));
}
const output = await consumeSseUntilComplete(streamRes).catch((err) => {
throw tag(err);
});
const glbCandidates = extractFirstGlbCandidates(output, spaceUrl);
if (!glbCandidates) {
throw tag(Object.assign(new Error('no GLB in output'), { code: 'provider_error', status: 502 }));
}
// Re-host the ephemeral gradio temp file to durable storage right now, while
// it's freshest, so no consumer ever re-fetches the expiring Space URL. When
// storage is configured this returns a durable URL or throws (the asset is
// already gone / unwritable). A throw is tagged as this Space's failure so the
// failover loop advances to the next Space and regenerates rather than handing
// back a URL that will 404 downstream. When storage is unconfigured it returns
// null and we keep the raw URL — the only option where there's nowhere durable.
let durableUrl;
try {
durableUrl = await rehostGlbToR2(glbCandidates, token);
} catch (err) {
throw tag(Object.assign(
new Error(`GLB produced but not persistable: ${err?.message}`),
{ code: 'rehost_failed', status: err?.status || 502, cause: err },
));
}
return { resultGlbUrl: durableUrl || glbCandidates[0], space, api };
}
export function createRegenProvider() {
const token = readEnv('HF_TOKEN');
if (!token) {
throw Object.assign(new Error('HF_TOKEN env var is required for the huggingface provider'), {
code: 'provider_unconfigured',
status: 501,
});
}
const chain = resolveChain();
if (chain.length === 0) {
throw Object.assign(new Error('huggingface failover chain is empty'), {
code: 'provider_unconfigured',
status: 501,
});
}
return {
async submit(request) {
if (request.mode !== 'reconstruct') {
throw Object.assign(
new Error(`huggingface provider only supports mode "reconstruct" (got "${request.mode}")`),
{ code: 'mode_unconfigured', status: 501 },
);
}
const photos = Array.isArray(request.params?.images) ? request.params.images : [];
if (photos.length === 0) {
throw Object.assign(new Error('huggingface provider needs at least one input image'), {
code: 'invalid_input',
status: 400,
});
}
// Try each Space in order. Capture per-Space errors so the final
// failure message tells the operator which Spaces were tried and
// why each failed — debugging "Avatar engine not available" without
// this is painful.
const failures = [];
for (const target of chain) {
try {
const { resultGlbUrl, space, api } = await runOnSpace({
token,
target,
photos,
params: request.params,
});
return {
extJobId: packExtJobId({ resultGlbUrl, space, api, fellBackFrom: failures.map((f) => f.space) }),
eta: 0,
rawStatus: 'completed',
providerNote: failures.length
? `succeeded on ${space} after ${failures.length} failover(s): ${failures.map((f) => `${f.space} (${f.message})`).join('; ')}`
: undefined,
};
} catch (err) {
failures.push({
space: err.spaceSlug || target.space,
api: err.apiName || target.api,
message: err.message || 'unknown error',
status: err.status,
});
// Continue to next Space.
}
}
const summary = failures
.map((f) => `${f.space} → ${f.message}`)
.join(' | ');
throw Object.assign(
new Error(`all ${chain.length} huggingface Space(s) failed: ${summary}`),
{ code: 'all_providers_failed', status: 502, failures },
);
},
async status(extJobId) {
const payload = unpackExtJobId(extJobId);
if (!payload?.resultGlbUrl) {
return { status: 'failed', error: 'missing or malformed ext_job_id' };
}
return {
status: 'done',
rawStatus: 'completed',
resultGlbUrl: payload.resultGlbUrl,
};
},
};
}