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
// GET /api/cron/avatar-thumbnail-backfill
//
// Steady-state drain of the avatar thumbnail coverage gap.
//
// ~79% of public avatars shipped with `thumbnail_key = NULL` because nothing
// generated a thumbnail when an avatar was forged or built in the studio. The
// only existing renderer (api/cron/avatar-thumbnail-render.js) is fed by the
// x402 spend loop and only ever touches *marketplace listings*, so the other
// ~10k avatars were never going to heal on their own.
//
// Each tick:
// 1. Adopts forge previews — an avatar forged from a forge_creations row points
// its thumbnail_key straight at that creation's already-uploaded preview
// image. Zero new bytes, no chromium. Hundreds per tick.
// 2. Renders the rest — claims the most-visible avatars still missing a
// thumbnail, renders each GLB to a 768² PNG, uploads it, commits the key.
// Bounded by RENDER_BATCH because chromium costs ~6s per model.
//
// Both steps only ever persist a thumbnail_key after confirming the object exists
// in R2 (see api/_lib/avatar-thumbs.js) — a key pointing at a missing object is
// what produced net::ERR_BLOCKED_BY_ORB on the homepage in the first place.
//
// Sibling cron (avatar-thumbnail-render) re-renders *stale* marketplace
// thumbnails; this one fills in *absent* ones. They share the render helper and
// the thumb/<avatarId>.png key space, and each is a no-op on the other's rows.
//
// Env:
// CRON_SECRET required (Bearer)
// THUMBNAIL_BACKFILL_RENDER_BATCH models rendered per tick (default 8)
// THUMBNAIL_BACKFILL_ADOPT_BATCH forge previews adopted per tick (default 200)
// THUMBNAIL_BACKFILL_CONCURRENCY parallel renders (default 2)
//
// Sizing: a render is ~3-6s, so 8 models at concurrency 2 lands around 25-40s —
// comfortably inside maxDuration=120 with room for a slow model. At */5 that is
// ~96 avatars/hour. A large backlog should be cleared with the bulk script
// (scripts/backfill-avatar-thumbnails.mjs --loop), which shares this claim ledger;
// the cron exists to keep coverage at 100% once it is there.
import { json, wrapCron } from '../_lib/http.js';
import { logger } from '../_lib/usage.js';
import {
ensureBackfillSchema,
adoptForgePreviews,
renderBatch,
coverage,
} from '../_lib/avatar-thumbs.js';
import { objectStorageConfigured } from '../_lib/r2.js';
import { requireCron } from '../_lib/cron-auth.js';
export const maxDuration = 120;
const log = logger('avatar-thumbnail-backfill');
const RENDER_BATCH = Math.max(0, Number(process.env.THUMBNAIL_BACKFILL_RENDER_BATCH || 8));
const ADOPT_BATCH = Math.max(0, Number(process.env.THUMBNAIL_BACKFILL_ADOPT_BATCH || 200));
const CONCURRENCY = Math.max(1, Number(process.env.THUMBNAIL_BACKFILL_CONCURRENCY || 2));
export default wrapCron(async (req, res) => {
if (req.method !== 'GET') return json(res, 405, { error: 'method_not_allowed' });
if (!requireCron(req, res)) return;
// Both steps write to R2, adoption verifies the forge preview object exists,
// rendering uploads a PNG, so with storage unconfigured there is nothing this
// tick can do except claim avatars and burn their bounded retries. Skip, the
// way the sibling forge-thumbnail-backfill does on forgeStoreEnabled().
if (!objectStorageConfigured()) {
return json(res, 200, { ok: false, reason: 'object_storage_unconfigured' });
}
try {
await ensureBackfillSchema();
} catch (err) {
return json(res, 200, { ok: false, reason: `schema_unavailable: ${err?.message}` });
}
// Step 1 — free coverage. Cheap enough to always run first and to run to
// completion before we spend a single chromium second.
let adopt = { adopted: 0, missing: 0 };
if (ADOPT_BATCH > 0) {
try {
adopt = await adoptForgePreviews({ limit: ADOPT_BATCH });
if (adopt.adopted) log.info('forge_previews_adopted', adopt);
} catch (err) {
log.warn('adopt_failed', { message: err?.message });
}
}
// Step 2 — render what's left, most-visible first.
let render = { claimed: 0, rendered: 0, failed: 0, results: [] };
if (RENDER_BATCH > 0) {
try {
render = await renderBatch({ limit: RENDER_BATCH, concurrency: CONCURRENCY });
} catch (err) {
log.warn('render_batch_failed', { message: err?.message });
return json(res, 200, { ok: false, reason: `render_failed: ${err?.message}`, adopted: adopt.adopted });
}
}
for (const r of render.results) {
if (r.status === 'done') log.info('thumbnail_rendered', { avatar_id: r.id, bytes: r.bytes, ms: r.ms });
else if (r.status === 'aborted') log.error('thumbnail_browser_died', { avatar_id: r.id, message: r.error });
else log.warn('thumbnail_render_failed', { avatar_id: r.id, message: r.error });
}
// A dead browser is an instance-health problem, not a model problem. Claims were
// rolled back, so the next tick retries the same avatars on a fresh container.
if (render.aborted) {
log.error('backfill_batch_aborted', { reason: render.aborted, rendered: render.rendered });
}
const cov = await coverage().catch(() => null);
return json(res, 200, {
ok: true,
adopted: adopt.adopted,
adopt_missing_objects: adopt.missing,
claimed: render.claimed,
rendered: render.rendered,
failed: render.failed,
aborted: render.aborted || false,
coverage: cov,
results: render.results.map((r) => ({
id: r.id,
status: r.status,
...(r.status === 'done' ? { url: r.url, bytes: r.bytes, ms: r.ms } : { error: r.error }),
})),
});
}, { maxDurationMs: maxDuration * 1000 });