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.

6.9 KB
Raw Blame
// GET /api/users/:username/avatar — resolve a username to their canonical avatar.
//
// Returns a minimal payload designed to drive both:
//   • the portable <script src="…/embed.js" data-avatar="@username"> snippet
//   • the public /@username live profile page
//
// Resolution priority:
//   1. Most-recent PUBLIC avatar owned by the user
//   2. If no public avatars, return 404 (we never leak a private GLB by handle)
//
// Optimization knobs (passed through to the model_url):
//   ?lod=0|1|2
//   ?textureSize=128|256|512|1024|2048
//   ?morphs=arkit52|all
//   ?draco=1
//   ?baked=1            prefer baked_storage_key when fresh (default ON;
//                       pass baked=0 to force the base GLB).
//
// Embed knob (for iframe/script consumers):
//   ?bg=transparent|dark|light
//   ?idle=on|off
//   ?mocap=off|webcam
//
// The returned `embed_url` is a fully-formed iframe src — drop it into an
// <iframe src="…"> and you get a live, lipsynced avatar with idle behaviors
// running. The `model_url` is a direct GLB pointer for SDK consumers (RPM
// Visage style) who want to render it themselves.

import { sql } from '../../_lib/db.js';
import { cors, json, method, wrap, error, rateLimited } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { publicUrl, thumbnailUrl } from '../../_lib/r2.js';
import { env } from '../../_lib/env.js';

const VALID_LOD = new Set(['0', '1', '2']);
const VALID_TEX = new Set(['128', '256', '512', '1024', '2048']);
const VALID_MORPHS = new Set(['arkit52', 'all']);
const VALID_BG = new Set(['transparent', 'dark', 'light']);
const VALID_MOCAP = new Set(['off', 'webcam']);

function originFor(req) {
	const fromEnv = env.APP_ORIGIN;
	if (fromEnv) return fromEnv.replace(/\/$/, '');
	const proto = req.headers['x-forwarded-proto'] || 'https';
	const host = req.headers['x-forwarded-host'] || req.headers.host;
	if (!host) return '';
	return `${proto}://${host}`.replace(/\/$/, '');
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	const usernameRaw =
		req.query?.username ||
		new URL(req.url, 'http://x').pathname.split('/').filter(Boolean).slice(-2)[0] ||
		'';
	const username = String(usernameRaw).toLowerCase().replace(/^@/, '').trim();
	if (!username || !/^[a-z0-9_-]{3,30}$/.test(username)) {
		return error(res, 400, 'validation_error', 'invalid username');
	}

	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, 'http://x');
	const lod = url.searchParams.get('lod');
	const textureSize = url.searchParams.get('textureSize');
	const morphs = url.searchParams.get('morphs');
	const draco = url.searchParams.get('draco');
	const baked = url.searchParams.get('baked') !== '0';
	const bg = url.searchParams.get('bg') || 'transparent';
	const idle = url.searchParams.get('idle') || 'on';
	const mocap = url.searchParams.get('mocap') || 'off';

	if (lod != null && !VALID_LOD.has(lod))
		return error(res, 400, 'validation_error', 'lod must be 0|1|2');
	if (textureSize != null && !VALID_TEX.has(textureSize))
		return error(res, 400, 'validation_error', 'textureSize must be 128|256|512|1024|2048');
	if (morphs != null && !VALID_MORPHS.has(morphs))
		return error(res, 400, 'validation_error', 'morphs must be arkit52|all');
	if (!VALID_BG.has(bg))
		return error(res, 400, 'validation_error', 'bg must be transparent|dark|light');
	if (!VALID_MOCAP.has(mocap))
		return error(res, 400, 'validation_error', 'mocap must be off|webcam');

	const [user] = await sql`
		select id, username, display_name
		from users
		where lower(username) = ${username} and deleted_at is null
		limit 1
	`;
	if (!user) return error(res, 404, 'not_found', 'user not found');

	const [avatar] = await sql`
		select id, slug, name, description,
		       storage_key, baked_storage_key, baked_at, appearance_hash,
		       thumbnail_key, size_bytes, source, version,
		       tags, created_at, updated_at
		from avatars
		where owner_id = ${user.id}
		  and visibility = 'public'
		  and deleted_at is null
		order by updated_at desc nulls last, created_at desc
		limit 1
	`;
	if (!avatar) return error(res, 404, 'not_found', 'user has no public avatar');

	// Base storage key — prefer the baked (dressed) version when fresh.
	const sourceKey =
		baked && avatar.baked_storage_key ? avatar.baked_storage_key : avatar.storage_key;
	const baseModelUrl = publicUrl(sourceKey);

	const origin = originFor(req);

	// model_url — optimization-knob URL. If no optimization params, hand back
	// the raw R2 URL (CDN-cached). Otherwise route through /api/avatar/optimize.
	let modelUrl = baseModelUrl;
	const transcode = lod != null || textureSize != null || morphs != null || draco === '1';
	if (transcode && origin) {
		const u = new URL(origin + '/api/avatar/optimize');
		u.searchParams.set('id', avatar.id);
		if (lod != null) u.searchParams.set('lod', lod);
		if (textureSize != null) u.searchParams.set('textureSize', textureSize);
		if (morphs != null) u.searchParams.set('morphs', morphs);
		if (draco === '1') u.searchParams.set('draco', '1');
		modelUrl = u.toString();
	}

	// embed_url — points at /embed/avatar/:username so the script-tag and
	// iframe both land on the same Vite entry. URL params control bg, idle,
	// mocap, and any optimization knobs.
	let embedUrl = '';
	if (origin) {
		const u = new URL(origin + `/embed/avatar/${user.username}`);
		if (lod != null) u.searchParams.set('lod', lod);
		if (textureSize != null) u.searchParams.set('textureSize', textureSize);
		if (morphs != null) u.searchParams.set('morphs', morphs);
		if (draco === '1') u.searchParams.set('draco', '1');
		if (bg !== 'transparent') u.searchParams.set('bg', bg);
		if (idle !== 'on') u.searchParams.set('idle', idle);
		if (mocap !== 'off') u.searchParams.set('mocap', mocap);
		if (!baked) u.searchParams.set('baked', '0');
		embedUrl = u.toString();
	}

	res.setHeader('Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300');
	return json(res, 200, {
		user: {
			username: user.username,
			display_name: user.display_name || user.username,
		},
		avatar: {
			id: avatar.id,
			slug: avatar.slug,
			name: avatar.name,
			description: avatar.description,
			thumbnail_url: thumbnailUrl(avatar.thumbnail_key),
			model_url: modelUrl,
			base_model_url: baseModelUrl,
			size_bytes: Number(avatar.size_bytes || 0),
			source: avatar.source,
			version: avatar.version,
			tags: avatar.tags || [],
			created_at: avatar.created_at,
			updated_at: avatar.updated_at,
			baked: baked && !!avatar.baked_storage_key,
		},
		embed_url: embedUrl,
		embed: {
			script: origin
				? `<script async src="${origin}/embed.js" data-avatar="@${user.username}"></script>`
				: '',
			iframe: embedUrl
				? `<iframe src="${embedUrl}" width="420" height="600" frameborder="0" allow="autoplay; camera; clipboard-write; xr-spatial-tracking" style="border-radius:12px;"></iframe>`
				: '',
		},
	});
});