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/animations/clips/:id — fetch a clip (baked clip + editor_doc)
// PATCH /api/animations/clips/:id — update metadata (owner only)
// DELETE /api/animations/clips/:id — soft-delete (owner only)
//
// Mirrors api/mocap/[id].js. The baked clip resolves from R2 when offloaded
// (storage_key set); the editor_doc is returned so the studio can reopen the
// animation for lossless re-editing.
//
// A priced, listed, non-public clip comes back with `paywalled: true` and no
// baked tracks for anyone but its owner: that motion sells through
// api/x402/animation-download.js, and `download_url` points there.
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { sql } from '../_lib/db.js';
import { cors, json, method, readJson, wrap, error } from '../_lib/http.js';
import { getObjectBuffer, thumbnailUrl } from '../_lib/r2.js';
import { isUuid } from '../_lib/validate.js';
import { clipSchema, editorDocSchema, validateClipTrackStrides, materializeClip } from './clips.js';
import { z } from 'zod';
const patchSchema = z.object({
name: z.string().trim().min(1).max(120).optional(),
description: z.string().trim().max(2000).optional(),
tags: z.array(z.string().trim().min(1).max(40)).max(20).optional(),
visibility: z.enum(['private', 'unlisted', 'public']).optional(),
kind: z.enum(['animation', 'loop', 'sequence']).optional(),
loop: z.boolean().optional(),
fps: z.number().int().min(1).max(240).nullable().optional(),
avatar_id: z.string().uuid().nullable().optional(),
// Re-saving edited keyframes: the studio sends the re-baked clip and the
// editable source so reopening stays lossless. Persisted with the same
// stride validation + R2 offload as create (POST /api/animations/clips).
clip: clipSchema.optional(),
editor_doc: editorDocSchema.optional(),
});
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,PATCH,DELETE,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PATCH', 'DELETE'])) return;
// The route pattern admits any hex-and-dash string, but the column is a uuid:
// anything looser reaches Postgres as an invalid uuid literal and surfaces as
// a 500 instead of the 400 the caller earned.
const id =
req.query?.id ||
new URL(req.url, 'http://x').pathname.split('/').filter(Boolean).pop();
if (!isUuid(id)) {
return error(res, 400, 'invalid_request', 'id must be an animation clip uuid');
}
const auth = await resolveAuth(req);
if (req.method === 'GET') return handleGet(req, res, auth, id);
if (!auth) return error(res, 401, 'unauthorized', 'authentication required');
if (req.method === 'PATCH') return handlePatch(req, res, auth, id);
return handleDelete(req, res, auth, id);
});
async function handleGet(req, res, auth, id) {
const [row] = await sql`
select id, owner_id, avatar_id, slug, name, description, kind, format,
duration_ms, frame_count, fps, loop, clip, storage_key, editor_doc,
thumbnail_key, tags, visibility, price_amount, price_currency,
listed, play_count, purchase_count, created_at, updated_at
from animation_clips
where id = ${id} and deleted_at is null
limit 1
`;
if (!row) return error(res, 404, 'not_found', 'animation not found');
const ownerView = auth?.userId === row.owner_id;
if (!ownerView && row.visibility === 'private') {
return error(res, 404, 'not_found', 'animation not found');
}
// A priced listing sells the motion, and the marketplace feed publishes the
// clip id to every browser, so handing the baked tracks back here would give
// away exactly what api/x402/animation-download.js charges for. Metadata,
// poster and price still render so the listing card works; the motion itself
// arrives through the paid download. `public` visibility is the creator
// deliberately publishing the clip to the free gallery, so it is never gated.
const paywalled =
!ownerView && !!row.listed && row.visibility !== 'public' && Number(row.price_amount || 0) > 0;
// Resolve the baked clip body from R2 when it was offloaded.
let clip = paywalled ? null : row.clip || null;
if (!paywalled && !clip && row.storage_key) {
try {
const buf = await getObjectBuffer(row.storage_key);
clip = JSON.parse(buf.toString('utf8'));
} catch (err) {
console.error('[animations/get] R2 resolve failed', err?.message || err);
return error(res, 502, 'storage_error', 'Failed to load clip payload');
}
}
// Bump play_count only when a non-owner fetches with ?play=1 (real playback,
// not editor opens or scrubbing). Fire-and-forget.
const isPlay = new URL(req.url, 'http://x').searchParams.get('play') === '1';
if (!ownerView && isPlay && clip) {
queueMicrotask(async () => {
try {
await sql`update animation_clips set play_count = play_count + 1 where id = ${id}`;
} catch (err) {
console.warn('[animations] play_count update failed', err?.message);
}
});
}
res.setHeader(
'Cache-Control',
ownerView ? 'private, max-age=0' : 'public, s-maxage=60, stale-while-revalidate=300',
);
return json(res, 200, {
clip: {
id: row.id,
slug: row.slug,
name: row.name,
description: row.description,
kind: row.kind,
format: row.format,
duration_ms: row.duration_ms,
duration: row.duration_ms / 1000,
frame_count: row.frame_count,
fps: row.fps,
loop: row.loop,
clip, // baked THREE.AnimationClip.toJSON(); null behind the paywall
paywalled,
download_url: paywalled ? `/api/x402/animation-download?id=${row.id}` : null,
editor_doc: ownerView ? row.editor_doc || null : null, // editing source is owner-only
editable: ownerView && !!row.editor_doc,
tags: row.tags || [],
visibility: row.visibility,
avatar_id: row.avatar_id,
thumbnail_url: thumbnailUrl(row.thumbnail_key),
play_count: Number(row.play_count || 0),
purchase_count: Number(row.purchase_count || 0),
listed: !!row.listed,
price: row.price_amount
? { amount: String(row.price_amount), currency: row.price_currency }
: null,
owner: ownerView ? 'self' : 'other',
created_at: row.created_at,
updated_at: row.updated_at,
},
});
}
async function handlePatch(req, res, auth, id) {
if (auth.source === 'oauth' || auth.source === 'apikey') {
if (!hasScope(auth.scope, 'avatars:write'))
return error(res, 403, 'insufficient_scope', 'avatars:write required');
}
const body = await readJson(req);
const parsed = patchSchema.safeParse(body);
if (!parsed.success) {
return error(res, 400, 'validation_error', parsed.error.issues.map((i) => i.message).join('; '));
}
const patch = parsed.data;
const sets = [];
if (patch.name !== undefined) sets.push(sql`name = ${patch.name}`);
if (patch.description !== undefined) sets.push(sql`description = ${patch.description}`);
if (patch.tags !== undefined) sets.push(sql`tags = ${patch.tags}`);
if (patch.visibility !== undefined) sets.push(sql`visibility = ${patch.visibility}`);
if (patch.kind !== undefined) sets.push(sql`kind = ${patch.kind}`);
if (patch.loop !== undefined) sets.push(sql`loop = ${patch.loop}`);
if (patch.fps !== undefined) sets.push(sql`fps = ${patch.fps}`);
// Re-bake the animation body. Recompute duration/frame_count from the new
// clip, re-run stride validation, and offload to R2 (or inline) exactly as
// create does — clearing storage_key when the new clip fits inline.
if (patch.clip !== undefined) {
const strideErr = validateClipTrackStrides(patch.clip);
if (strideErr) return error(res, 400, 'validation_error', strideErr);
const { inlineClip, storageKey, error: clipErr } = await materializeClip(patch.clip, {
userId: auth.userId,
slug: id,
});
if (clipErr) return error(res, 502, 'storage_error', clipErr);
sets.push(sql`clip = ${inlineClip}::jsonb`);
sets.push(sql`storage_key = ${storageKey}`);
sets.push(sql`duration_ms = ${Math.round(patch.clip.duration * 1000)}`);
const frameCount =
patch.editor_doc?.keyframes?.length || patch.clip.tracks[0]?.times?.length || 0;
sets.push(sql`frame_count = ${frameCount}`);
}
if (patch.editor_doc !== undefined) {
sets.push(sql`editor_doc = ${JSON.stringify(patch.editor_doc)}::jsonb`);
}
if (patch.avatar_id !== undefined) {
if (patch.avatar_id) {
const ok = await sql`
select 1 from avatars
where id = ${patch.avatar_id} and owner_id = ${auth.userId} and deleted_at is null
limit 1
`;
if (!ok[0]) return error(res, 404, 'not_found', 'avatar_id not owned by you');
}
sets.push(sql`avatar_id = ${patch.avatar_id}`);
}
if (sets.length === 0) return error(res, 400, 'invalid_request', 'no patchable fields supplied');
const setClause = sets.reduce((acc, s, i) => (i === 0 ? sql`set ${s}` : sql`${acc}, ${s}`), sql``);
const [row] = await sql`
update animation_clips
${setClause}
where id = ${id} and owner_id = ${auth.userId} and deleted_at is null
returning id, slug, name, description, kind, format, duration_ms, frame_count,
fps, loop, tags, visibility, avatar_id, price_amount, price_currency,
listed, created_at, updated_at
`;
if (!row) return error(res, 404, 'not_found', 'animation not found or not yours');
return json(res, 200, {
clip: {
...row,
price: row.price_amount
? { amount: String(row.price_amount), currency: row.price_currency }
: null,
},
});
}
async function handleDelete(req, res, auth, id) {
if (auth.source === 'oauth' || auth.source === 'apikey') {
if (!hasScope(auth.scope, 'avatars:delete'))
return error(res, 403, 'insufficient_scope', 'avatars:delete required');
}
const [row] = await sql`
update animation_clips
set deleted_at = now()
where id = ${id} and owner_id = ${auth.userId} and deleted_at is null
returning id
`;
if (!row) return error(res, 404, 'not_found', 'animation not found or not yours');
return json(res, 200, { ok: true });
}
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session)
return {
userId: session.id,
source: 'session',
scope: 'avatars:read avatars:write avatars:delete',
};
return await authenticateBearer(extractBearer(req));
}
// Exported for contract tests (PATCH schema) without a live DB.
export const __test__ = { patchSchema };