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
// POST /api/avatars/from-forge
//
// Save a generated GLB (by URL) straight into the caller's avatar library,
// server-side. This is the durable end of the chat "text → 3D avatar" pipeline:
// the chat tool forges a mesh and auto-rigs it (both return public GLB URLs),
// then hands the final URL here. Doing the copy on the server — instead of the
// browser fetching the GLB and presigning a PUT — sidesteps cross-origin (CORS)
// reads of provider/R2 URLs, the 16 MB browser-upload cap, and the
// size-match race on /api/avatars, and it routes through the same
// createAvatar + agent-provisioning path as a normal upload so the result is a
// first-class, agent-backed avatar.
//
// Mirrors the MCP studio save_avatar tool, but session/bearer authed for the
// browser instead of x402.
//
// Request body (JSON):
// glb_url string — public https URL of the GLB to save (required)
// name string — avatar name, 1–80 chars (required)
// visibility enum? — public | unlisted | private (default unlisted)
// source_prompt string? — the prompt that generated it, kept as provenance
// rigged bool? — whether the GLB is auto-rigged (provenance only)
// tags string[]? — up to 20 organizing tags
//
// Response 201: { avatar, view_url }
import { cors, json, method, readJson, wrap, error } from '../_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { storageKeyFor, createAvatar, defaultAvatarVisibilityFor } from '../_lib/avatars.js';
import { putObject } from '../_lib/r2.js';
import { isValidGlbHeader, inspectGlb } from '../_lib/glb-inspect.js';
import { fetchSafePublicUrl, SsrfBlockedError, MaxBytesExceededError } from '../_lib/ssrf-guard.js';
import { provisionAvatarAgent } from '../_lib/avatar-agent.js';
import { maybeAutoRigAvatar } from '../_lib/auto-rig.js';
import { limits } from '../_lib/rate-limit.js';
import { recordEvent } from '../_lib/usage.js';
import { markActivated } from '../_lib/activation.js';
import { env } from '../_lib/env.js';
// Match the studio/reconstruct ceiling so a runaway model can't ingest an
// unbounded blob. The avatars table allows far more, but a generated avatar is
// realistically 5–25 MB.
const MAX_GLB_BYTES = 64 * 1024 * 1024;
const VISIBILITIES = new Set(['public', 'unlisted', 'private']);
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, source: 'session' };
const bearer = await authenticateBearer(extractBearer(req));
if (!bearer) return null;
if (!hasScope(bearer.scope, 'avatars:write')) return null;
return bearer;
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const auth = await resolveAuth(req);
if (!auth?.userId) {
return error(res, 401, 'unauthorized', 'sign in (or provide an avatars:write token) to save an avatar');
}
const rl = await limits.upload(auth.userId);
if (!rl.success) {
res.setHeader('Retry-After', Math.max(1, Math.ceil((rl.reset - Date.now()) / 1000)));
return error(res, 429, 'rate_limited', 'too many avatar saves; try again shortly');
}
let body;
try {
body = await readJson(req);
} catch (err) {
return error(res, 400, 'bad_request', err?.message || 'invalid JSON body');
}
const glbUrl = typeof body?.glb_url === 'string' ? body.glb_url.trim() : '';
const name = typeof body?.name === 'string' ? body.name.trim().slice(0, 80) : '';
if (!glbUrl) return error(res, 400, 'invalid_request', 'glb_url is required');
if (!name) return error(res, 400, 'invalid_request', 'name is required (1–80 chars)');
// An explicit visibility from the caller wins; otherwise the owner's
// "Default avatar visibility" preference from /settings decides, falling back
// to the unlisted default this endpoint has always used.
const visibility = VISIBILITIES.has(body?.visibility)
? body.visibility
: await defaultAvatarVisibilityFor(auth.userId, 'unlisted');
const sourcePrompt =
typeof body?.source_prompt === 'string' ? body.source_prompt.slice(0, 1000) : null;
const rigged = body?.rigged === true;
const tags = Array.isArray(body?.tags)
? body.tags.map((t) => String(t).trim()).filter(Boolean).slice(0, 20)
: [];
// Fetch the GLB server-side through the SSRF guard (https-only, no
// private/loopback/metadata targets) — glb_url is model-influenced, so it is
// never trusted to point at our own network.
let resp;
try {
resp = await fetchSafePublicUrl(glbUrl, {}, { allowHttp: false, maxBytes: MAX_GLB_BYTES });
} catch (err) {
if (err instanceof MaxBytesExceededError) {
return error(res, 413, 'payload_too_large', `glb is over the ${MAX_GLB_BYTES} byte limit`);
}
if (err instanceof SsrfBlockedError) {
return error(res, 400, 'invalid_url', 'glb_url must be a public https URL');
}
console.warn('[from-forge] glb fetch failed:', err?.message);
return error(res, 502, 'fetch_failed', 'Could not fetch that GLB URL — check the link and try again.');
}
if (!resp.ok) {
return error(res, 502, 'fetch_failed', `glb_url returned ${resp.status}`);
}
const declared = Number(resp.headers.get('content-length') || 0);
if (declared && declared > MAX_GLB_BYTES) {
return error(res, 413, 'payload_too_large', `glb is ${declared} bytes; max is ${MAX_GLB_BYTES}`);
}
let buf;
try {
buf = Buffer.from(await resp.arrayBuffer());
} catch (err) {
if (err instanceof MaxBytesExceededError) {
return error(res, 413, 'payload_too_large', `glb is over the ${MAX_GLB_BYTES} byte limit`);
}
console.warn('[from-forge] glb body read failed:', err?.message);
return error(res, 502, 'fetch_failed', 'Could not read that GLB URL, check the link and try again.');
}
if (buf.length > MAX_GLB_BYTES) {
return error(res, 413, 'payload_too_large', `glb is ${buf.length} bytes; max is ${MAX_GLB_BYTES}`);
}
if (!isValidGlbHeader(buf)) {
return error(res, 422, 'invalid_glb', 'that URL did not return a valid binary glTF (.glb)');
}
// inspectGlb does a deeper parse and can still return null on a header-valid
// but malformed GLB — fall back to an empty meta object so a save never 500s.
const info = inspectGlb(buf) || {};
// Durable copy under the caller's own storage namespace, then register it.
const slug = `studio-${Math.random().toString(36).slice(2, 8)}`;
const storageKey = storageKeyFor({ userId: auth.userId, slug });
await putObject({
key: storageKey,
body: buf,
contentType: 'model/gltf-binary',
metadata: { source: 'studio', user_id: auth.userId },
});
const avatar = await createAvatar({
userId: auth.userId,
storageKey,
input: {
slug,
name,
description: null,
size_bytes: buf.length,
content_type: 'model/gltf-binary',
source: 'studio',
source_meta: {
source_glb_url: glbUrl,
source_prompt: sourcePrompt,
generator: 'chat-forge-avatar',
// Server-side GLB inspection is the ONLY rig truth (definite true/
// false, or null when a header-valid blob couldn't be parsed). The
// client `rigged` body flag is never trusted to decide rig state — it
// is kept separately, clearly labelled, as provenance only.
is_rigged: typeof info.isRigged === 'boolean' ? info.isRigged : null,
client_claimed_rigged: rigged,
mesh_count: info.meshCount ?? null,
animation_count: info.animationCount ?? null,
},
visibility,
tags,
checksum_sha256: null,
parent_avatar_id: null,
},
});
// First-class like a normal upload: provision the agent + custodial wallet,
// and record signed generation provenance on the agent_actions ledger once
// it resolves (creator, prompt, generation model, timestamp).
queueMicrotask(() =>
provisionAvatarAgent({
userId: auth.userId,
avatarId: avatar.id,
avatarName: avatar.name,
provenance: {
prompt: sourcePrompt,
generationModel: 'chat-forge-avatar',
generationProvider: null,
parentAvatarId: null,
},
}),
);
// Auto-rig if the forged mesh arrived static (e.g. a mesh_forge save) so the
// agent's avatar can animate. The rig decision derives from the SERVER-side
// GLB inspection (info.isRigged / skeletonJointCount), never the untrusted
// client `rigged` flag: a client can't send rigged:true on a static mesh to
// skip the gate, nor rigged:false on a skinned mesh to force a paid rig. A
// no-op when inspection finds a real skeleton or no rerig model is configured.
queueMicrotask(() =>
maybeAutoRigAvatar({
userId: auth.userId,
avatar,
rigInfo: { is_rigged: info.isRigged === true, skeleton_joint_count: info.skeletonJointCount ?? null },
source: 'studio',
visibility: avatar.visibility,
prompt: sourcePrompt,
}),
);
recordEvent({
userId: auth.userId,
apiKeyId: auth.apiKeyId,
clientId: auth.clientId,
avatarId: avatar.id,
kind: 'upload',
bytes: buf.length,
meta: { source: 'chat-forge-avatar', rigged: Boolean(rigged) },
});
// First win: claimed a forged 3D model as an avatar. Activates the account
// once and pays the two-sided referral reward when referred. Fire-and-forget.
queueMicrotask(() => markActivated(auth.userId, { source: 'forge_save', meta: { avatarId: avatar.id } }));
const viewUrl = `${env.APP_ORIGIN || ''}/avatars/${avatar.id}`;
return json(res, 201, { avatar, view_url: viewUrl });
});