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
// Private module: avatar action endpoints dispatched from [id].js.
// presign, public, regenerate, regenerate-status
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { presignUpload, headObject, r2, publicUrl, putObject } from '../_lib/r2.js';
import { storageKeyFor, enforceQuotas, searchPublicAvatars, stripOwnerFor, assertAvatarSlotAvailable, isPlanLimitError, PLAN_LIMIT_JOB_ERROR, defaultAvatarVisibilityFor } from '../_lib/avatars.js';
import { listAvatars } from '../_lib/avatars.js';
import { env } from '../_lib/env.js';
import { OPENROUTER_ATTRIBUTION_HEADERS } from '../_lib/openrouter-attribution.js';
import { sql } from '../_lib/db.js';
import { cors, json, method, readJson, readBody, wrap, error, rateLimited } from '../_lib/http.js';
import { parse, presignUploadBody, slug as slugSchema, createAvatarBody } from '../_lib/validate.js';
import { recordEvent } from '../_lib/usage.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { z } from 'zod';
import { randomUUID } from 'crypto';
import { isValidGlbHeader } from '../_lib/glb-inspect.js';
import { pickReconstructParams } from '../_lib/reconstruct-params.js';
import { fetchSafePublicUrlPinned, SsrfBlockedError, MaxBytesExceededError } from '../_lib/ssrf-guard.js';
import { getRegenProviderCandidates, getRegenProviderByName, getRegenProviderForJob, BYOK_REGEN_PROVIDERS } from '../_lib/regen-provider.js';
import { resolveProviderKey } from '../_lib/forge-provider-key.js';
import { finalizeReconstructStage, pollRiggingStage } from '../_lib/reconstruct-finalize.js';
import { finalizeAutoRigStage } from '../_lib/auto-rig.js';
import { isAllowedProviderResultUrl } from '../_lib/provider-result-url.js';
import { generateReferenceImage } from '../_lib/forge-reference-image.js';
import { requestTerritory } from '../_lib/forge-territory.js';
import { planPromptAvatarLanes, promptAvatarImagePrompt } from '../_lib/prompt-avatar.js';
import { laneHealthSnapshot } from '../_lib/forge-lane-health.js';
// ── provider error masking ──────────────────────────────────────────────────────
// The regen adapters (Replicate, GCP, and the BYOK Meshy/Tripo) attach a stable
// .code/.status to every thrown error, but err.message can name the vendor, its
// billing state ("Meshy account is out of credits."), or echo a raw upstream
// body. None of that may reach the browser. These two helpers translate by code
// into neutral, actionable copy and keep the raw detail in server logs only.
// Classify a provider submit/resolve failure into a vendor-free { status, code,
// message } envelope. The error CODE is preserved (the clients already branch on
// invalid_key / missing_key / insufficient_credits / rate_limited) — only the
// leaky MESSAGE is replaced, so the BYOK key-entry UX keeps working while no
// vendor name or billing state ever ships. Pure + exported for direct testing.
export function classifyProviderError(err) {
const code = err?.code;
const status = Number(err?.status) || 0;
if (code === 'insufficient_credits' || status === 402) {
return { status: 402, code: 'insufficient_credits', message: 'The 3D engine key is out of credits — top it up and try again.' };
}
if (code === 'invalid_key' || code === 'missing_key' || status === 401) {
return { status: 401, code: code === 'missing_key' ? 'missing_key' : 'invalid_key', message: 'The 3D engine key was rejected — check it and try again.' };
}
if (code === 'rate_limited' || status === 429) {
return { status: 429, code: 'rate_limited', message: 'The 3D engine is busy right now — wait a moment and try again.', retryAfter: 15 };
}
if (code === 'invalid_request' || status === 400) {
return { status: 400, code: 'invalid_request', message: 'That request could not be processed — check your photo and try again.' };
}
if (code === 'mode_unconfigured' || code === 'regen_provider_unknown' || status === 501) {
return { status: 501, code: 'regen_unconfigured', message: 'The 3D engine is not available for this request right now.' };
}
// provider_unreachable, provider_error, and anything else → generic retry.
return { status: 502, code: 'regen_provider_error', message: 'The 3D engine could not start this job — please try again shortly.' };
}
// Send the masked classification to the client, logging the raw detail for ops.
function maskSubmitError(res, err) {
const c = classifyProviderError(err);
console.warn('[avatars] provider error:', err?.code || err?.status || 'unknown', '—', err?.message);
if (c.retryAfter) res.setHeader('retry-after', String(c.retryAfter));
return error(res, c.status, c.code, c.message, c.retryAfter ? { retry_after: c.retryAfter } : {});
}
// Collapse a raw job/provider error string into neutral copy before it leaves the
// API. The DB keeps the raw value for operators; only this masked form is
// returned to any client (browser or bearer-token API consumer). Shared with the
// forge text→3D poll (api/forge.js) so both pipelines mask identically; re-exported
// here because the avatar tests and handlers already import it from this module.
// A bare `export { x } from './mod'` re-export does NOT bind `x` in this module's
// scope, so the regenerate-status poll handler below (which calls sanitizeJobError)
// threw `ReferenceError: sanitizeJobError is not defined` at runtime. Import the
// local binding and re-export it so both this module and its consumers resolve it.
import { sanitizeJobError } from '../_lib/provider-job-error.js';
import { fetchUpstream } from '../_lib/upstream-fetch.js';
// Per-rung deadline for the vision classifiers so a hung provider moves the
// chain to its next lane instead of holding the request.
const VISION_TIMEOUT_MS = 30_000;
export { sanitizeJobError };
// ── presign ───────────────────────────────────────────────────────────────────
async function resolvePresignUser(req, requiredScope) {
const session = await getSessionUser(req);
if (session) return session.id;
const bearer = await authenticateBearer(extractBearer(req), { audience: undefined });
if (!bearer || !hasScope(bearer.scope, requiredScope)) return null;
return bearer.userId;
}
const handlePresign = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const rl = await limits.upload(userId);
if (!rl.success) return rateLimited(res, rl, 'upload rate exceeded');
const body = parse(presignUploadBody, await readJson(req));
try { await enforceQuotas(userId, body.size_bytes); }
catch (err) { return error(res, err.status || 402, err.code || 'plan_limit', err.message); }
const bodyAny = body;
const slug = bodyAny.slug ? slugSchema.parse(bodyAny.slug) : `draft-${Math.random().toString(36).slice(2, 8)}`;
const key = storageKeyFor({ userId, slug });
const url = await presignUpload({ key, contentType: body.content_type });
return json(res, 200, { storage_key: key, upload_url: url, method: 'PUT', headers: { 'content-type': body.content_type }, expires_in: 300 });
});
// ── upload proxy ──────────────────────────────────────────────────────────────
// Server-side upload fallback for environments where direct browser→R2 PUT is
// blocked (Codespaces previews, ephemeral domains not in the bucket CORS
// allowlist, restrictive corporate networks). The client streams the GLB to
// this endpoint and we PUT it to R2 server-side using already-authenticated
// S3 credentials. Same quotas, same key naming as presign — only the wire path
// differs. Used by account.js after a CORS-blocked presigned PUT.
//
// Body: raw octet stream (the GLB bytes). Metadata passed as query params so
// the body can be a single contiguous buffer:
// ?slug=optional-slug&content_type=model/gltf-binary&sha256=hex-or-empty
//
// Vercel Pro caps Node function request bodies at 50 MB. Realistic avatars
// are 5–15 MB; the presign+direct path remains for anything larger.
const MAX_PROXY_UPLOAD_BYTES = 50 * 1024 * 1024;
const PROXY_CONTENT_TYPES = new Set([
'model/gltf-binary',
'application/octet-stream',
'application/gltf-binary',
]);
const handleUpload = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
if (!(await requireCsrf(req, res, userId))) return;
const rl = await limits.upload(userId);
if (!rl.success) return rateLimited(res, rl, 'upload rate exceeded');
const url = new URL(req.url, 'http://x');
const rawContentType = url.searchParams.get('content_type') || req.headers['content-type'] || 'model/gltf-binary';
const contentType = rawContentType.split(';')[0].trim().toLowerCase();
if (!PROXY_CONTENT_TYPES.has(contentType)) {
return error(res, 415, 'unsupported_media_type', `content_type must be one of: ${[...PROXY_CONTENT_TYPES].join(', ')}`);
}
// Two body modes:
// • source_url=<http(s) GLB URL> — we fetch the bytes server-side. This is
// the URL-import path: the browser can't fetch most avatar CDNs directly
// (CloudFront/Arweave/etc. send no CORS headers), so we pull it here where
// same-origin policy doesn't apply. SSRF-guarded against internal targets.
// • raw octet-stream body — the CORS-fallback path for client-held blobs.
const sourceUrl = url.searchParams.get('source_url');
let buffer;
if (sourceUrl) {
try {
buffer = await fetchRemoteGlb(sourceUrl, MAX_PROXY_UPLOAD_BYTES);
} catch (err) {
return error(res, err.status || 502, err.code || 'fetch_failed', err.message || 'failed to fetch source URL');
}
// Cloud Run's Express layer pre-drains the request stream and stashes the
// bytes on req.rawBody / req.body (see readBody in api/_lib/http.js). The
// raw-stream listener below never fires for those requests: its 'data' and
// 'end' events already emitted, so production uploads must prefer the
// captured buffer over the stream, exactly like readBody does.
} else if (Buffer.isBuffer(req.rawBody) || req.body !== undefined) {
try {
buffer = await readBody(req, MAX_PROXY_UPLOAD_BYTES);
} catch (err) {
return error(res, err.status || 400, err.code || 'invalid_body', err.message || 'failed to read body');
}
} else {
const declaredLength = Number(req.headers['content-length']);
if (Number.isFinite(declaredLength) && declaredLength > MAX_PROXY_UPLOAD_BYTES) {
return error(res, 413, 'payload_too_large', `body exceeds ${MAX_PROXY_UPLOAD_BYTES} bytes — use presigned upload for larger GLBs`);
}
try {
buffer = await readRawBody(req, MAX_PROXY_UPLOAD_BYTES);
} catch (err) {
return error(res, err.status || 400, err.code || 'invalid_body', err.message || 'failed to read body');
}
}
if (!buffer.length) return error(res, 400, 'empty_body', 'no bytes received');
// GLB header (binary glTF 2.0 spec): 12 bytes of
// magic uint32 0x46546C67 // 'glTF' little-endian
// version uint32 must be 2
// length uint32 total file length in bytes (must equal buffer length)
// Catches mis-named uploads (JPEGs, HTML error pages, truncated files) and
// sets the catalog up to only ever serve well-formed binary glTF.
if (!isValidGlbHeader(buffer)) {
return error(res, 415, 'invalid_glb', 'body is not a valid binary glTF 2.0 (GLB) — magic/version/length check failed');
}
try {
await enforceQuotas(userId, buffer.length);
} catch (err) {
return error(res, err.status || 402, err.code || 'plan_limit', err.message);
}
// Canonicalize bone names + up-axis orientation at ingest so every stored
// GLB shares the canonical convention. The client-body path sends already-
// canonical bytes (account.js canonicalizes before upload), so this is a
// no-op there; the source_url path fetches raw bytes that may still be
// Mixamo/FBX-oriented. Non-fatal: if the buffer isn't a recognised humanoid
// rig the canonicalizer returns it unchanged.
try {
const { canonicalizeGLBBones } = await import('../../src/glb-canonicalize.js');
const ab = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
const canonical = canonicalizeGLBBones(ab);
if (canonical.renamed > 0 || canonical.orientationCorrected) {
buffer = Buffer.from(canonical.buffer);
}
} catch (err) {
console.warn('[avatar-upload] canonicalize skipped:', err?.message);
}
const rawSlug = url.searchParams.get('slug');
const slug = rawSlug ? slugSchema.parse(rawSlug) : `draft-${Math.random().toString(36).slice(2, 8)}`;
const key = storageKeyFor({ userId, slug });
const checksum = await sha256Hex(buffer);
const claimedChecksum = (url.searchParams.get('sha256') || '').toLowerCase();
if (claimedChecksum && claimedChecksum !== checksum) {
return error(res, 400, 'checksum_mismatch', 'sha256 query param does not match received bytes');
}
await putObject({ key, body: buffer, contentType });
return json(res, 200, {
storage_key: key,
size_bytes: buffer.length,
content_type: contentType,
checksum_sha256: checksum,
});
});
// Fetch a remote GLB server-side for the URL-import flow. Guards against SSRF:
// the URL is attacker-controlled (any signed-in user can submit one), so we
// resolve every redirect hop's hostname to its IPs and reject anything that
// points at loopback, private, link-local, or cloud-metadata ranges before a
// single byte is read. Streamed with a hard byte cap and a wall-clock timeout.
const REMOTE_FETCH_TIMEOUT_MS = 20_000;
export async function fetchRemoteGlb(rawUrl, maxBytes) {
let target;
try {
target = new URL(rawUrl);
} catch {
throw fetchError(400, 'invalid_url', 'source_url is not a valid URL');
}
if (!['http:', 'https:'].includes(target.protocol)) {
throw fetchError(400, 'unsupported_scheme', 'only http(s) URLs can be imported');
}
try {
// IP-pinned: every hop's address is validated and the socket connects to
// exactly that address, so DNS cannot change between check and connect.
const resp = await fetchSafePublicUrlPinned(
target.href,
{
signal: AbortSignal.timeout(REMOTE_FETCH_TIMEOUT_MS),
headers: { accept: 'model/gltf-binary,application/octet-stream,*/*' },
},
{ allowHttp: true, maxBytes },
);
if (!resp.ok) throw fetchError(502, 'fetch_failed', `source URL returned HTTP ${resp.status}`);
return Buffer.from(await resp.arrayBuffer());
} catch (err) {
if (err instanceof SsrfBlockedError) {
console.warn('[avatar-upload] ssrf blocked:', err.message);
throw fetchError(400, 'blocked_host', 'source_url host is not allowed');
}
if (err instanceof MaxBytesExceededError) {
throw fetchError(413, 'payload_too_large', `source file exceeds ${maxBytes} bytes`);
}
if (err.code && err.status) throw err;
if (err.name === 'AbortError' || err.name === 'TimeoutError' || /abort|timed? ?out/i.test(err?.message || '')) {
throw fetchError(504, 'fetch_timeout', 'source URL timed out');
}
console.warn('[avatar-upload] remote fetch failed:', err?.message);
throw fetchError(502, 'fetch_failed', 'could not fetch the source URL');
}
}
function fetchError(status, code, message) {
const err = new Error(message);
err.status = status;
err.code = code;
return err;
}
function readRawBody(req, limit) {
return new Promise((resolve, reject) => {
const chunks = [];
let total = 0;
req.on('data', (chunk) => {
total += chunk.length;
if (total > limit) {
const err = new Error(`body exceeds ${limit} bytes`);
err.status = 413;
err.code = 'payload_too_large';
reject(err);
req.destroy();
return;
}
chunks.push(chunk);
});
req.on('end', () => resolve(Buffer.concat(chunks)));
req.on('error', reject);
});
}
async function sha256Hex(buf) {
const { createHash } = await import('crypto');
return createHash('sha256').update(buf).digest('hex');
}
// ── public ────────────────────────────────────────────────────────────────────
// Public discovery surface — must always return 200 with a stable JSON shape so
// agent crawlers, OpenAPI probes, and the Bazaar validator see a clean response
// even when the DB is unreachable or the query parameters are malformed. Any
// internal failure degrades to an empty result set rather than a 5xx.
const handlePublic = wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const url = new URL(req.url, 'http://x');
const parsedLimit = Number(url.searchParams.get('limit'));
const limit = Math.min(Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 24, 100);
let result;
try {
result = await searchPublicAvatars({
q: url.searchParams.get('q') || undefined,
tag: url.searchParams.get('tag') || undefined,
category: url.searchParams.get('category') || undefined,
rigged: url.searchParams.get('rigged') || undefined,
limit,
cursor: url.searchParams.get('cursor') || undefined,
withTotals: url.searchParams.get('totals') === '1',
});
} catch {
result = { avatars: [], next_cursor: null };
}
const avatars = Array.isArray(result?.avatars) ? result.avatars : [];
const payload = {
avatars: avatars.map((a) => stripOwnerFor(a, null)),
next_cursor: result?.next_cursor ?? null,
};
if (Object.prototype.hasOwnProperty.call(result || {}, 'total')) {
payload.total = result.total;
payload.total_views = result.total_views;
}
res.setHeader('cache-control', 'public, max-age=60, s-maxage=60');
return json(res, 200, payload);
});
// ── regenerate ────────────────────────────────────────────────────────────────
const regenerateSchema = z.object({
sourceAvatarId: z.string().trim().min(1).max(100),
mode: z.enum(['remesh', 'retex', 'rerig', 'restyle', 'reconstruct']),
params: z.record(z.unknown()).optional(),
});
async function resolveRegenUser(req) {
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
if (!session && !bearer) return null;
if (bearer && !hasScope(bearer.scope, 'avatars:write')) return null;
return session?.id ?? bearer?.userId;
}
const handleRegenerate = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolveRegenUser(req);
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const rl = await limits.upload(userId);
if (!rl.success) return rateLimited(res, rl);
const body = parse(regenerateSchema, await readJson(req));
const rows = await sql`select id, name, storage_key from avatars where id = ${body.sourceAvatarId} and owner_id = ${userId} and deleted_at is null limit 1`;
if (!rows[0]) return error(res, 404, 'not_found', 'source avatar not found or not owned');
// Platform provider failover: try every configured provider (primary first),
// retrying transient faults, so a single outage / throttle / cold start
// doesn't dead-end the job. Mirrors the reconstruct submit path.
let candidates;
try {
candidates = await getRegenProviderCandidates();
} catch (err) {
return maskSubmitError(res, err);
}
if (candidates.length === 0) {
return error(
res,
501,
'regen_unconfigured',
'Avatar regeneration is not available on this deployment yet.',
);
}
const sourceUrl = publicUrl(rows[0].storage_key);
let submission = null;
let usedProvider = null;
let bestError = null;
const attempts = [];
for (const provider of candidates) {
try {
submission = await submitWithTransientRetry(provider.instance, {
userId,
sourceAvatarId: body.sourceAvatarId,
mode: body.mode,
params: body.params ?? {},
sourceUrl,
sourceStorageKey: rows[0].storage_key,
});
usedProvider = provider;
break;
} catch (err) {
attempts.push(`${provider.name}:${err?.code || err?.status || classifyProviderError(err).code}`);
console.warn(
'[avatars] regenerate submit failed on',
provider.name,
'—',
err?.code || err?.status || 'unknown',
'-',
err?.message,
);
// Keep the most actionable error to surface if every provider fails.
if (!bestError || (isGenericProviderError(bestError) && !isGenericProviderError(err))) {
bestError = err;
}
}
}
if (!submission || !usedProvider) {
if (attempts.length > 1) {
console.warn('[avatars] all regenerate providers failed:', attempts.join(', '));
}
return maskSubmitError(res, bestError || new Error('no regenerate provider available'));
}
const jobId = `${usedProvider.name}-${randomUUID()}`;
await sql`
insert into avatar_regen_jobs
(job_id, user_id, source_avatar_id, mode, params, status, provider, ext_job_id, created_at, updated_at)
values
(${jobId}, ${userId}, ${body.sourceAvatarId}, ${body.mode}, ${JSON.stringify(body.params ?? {})}, 'queued', ${usedProvider.name}, ${submission.extJobId ?? null}, now(), now())
`;
return json(res, 202, {
ok: true,
jobId,
status: 'queued',
eta: submission.eta ?? null,
provider: usedProvider.name,
});
});
// ── regenerate-status ─────────────────────────────────────────────────────────
// PLAN_LIMIT_JOB_ERROR is the copy shown to a user whose library is full when a
// job reaches materialization. handleReconstruct pre-flights the same quota, so
// this only fires on the race (another avatar landed while the mesh was
// generating), but a job that loses that race must still end somewhere the user
// can act on.
/**
* A materialize stage threw. If the cause was a plan-limit refusal, terminate
* the job as failed with caller-facing copy rather than leaving it at 'done'
* with no avatar, that state is invisible to every recovery cron (they filter
* on queued/running) and re-runs the same doomed materialization on every poll,
* so the browser retries forever against a generic engine-fault message. Marked
* error_kind 'input' so the wire relays the copy verbatim.
* @returns {Promise<any|null>} the updated job row, or null if err was not a plan limit
*/
async function failJobOnPlanLimit({ userId, jobId, job, err }) {
if (!isPlanLimitError(err)) return null;
await sql`
update avatar_regen_jobs
set status = 'failed', error = ${PLAN_LIMIT_JOB_ERROR}, error_kind = 'input', updated_at = now()
where job_id = ${jobId} and user_id = ${userId}
`;
return { ...job, status: 'failed', error: PLAN_LIMIT_JOB_ERROR, error_kind: 'input' };
}
const handleRegenerateStatus = wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
if (!session && !bearer) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
if (bearer && !hasScope(bearer.scope, 'avatars:read')) return error(res, 403, 'insufficient_scope', 'avatars:read scope required');
const userId = session?.id ?? bearer?.userId;
const url = new URL(req.url, 'http://x');
const jobId = url.searchParams.get('jobId');
if (!jobId) return error(res, 400, 'invalid_request', 'jobId required');
const rows = await sql`
select job_id, status, result_avatar_id, result_glb_url, error, error_kind, provider, ext_job_id, created_at,
mode, params, source_avatar_id
from avatar_regen_jobs
where job_id = ${jobId} and user_id = ${userId}
limit 1
`;
if (!rows[0]) return error(res, 404, 'not_found', 'job not found');
let job = rows[0];
// Strategy A: an auto-rig job's terminal 'done' transition is owned solely by
// finalizeAutoRigStage (its closeJob writes done + result_avatar_id together).
// If this poll flipped the row to 'done' and finalize then threw, the job would
// strand at 'done' + null — invisible to the cron's queued/running recovery
// filter. So for auto-rig we persist a non-terminal status here and let finalize
// own 'done'; `autoRigProviderDone` carries the provider's verdict to the
// finalize branch below. Reconstruct and every other mode are unaffected.
const isAutoRig = job.mode === 'rerig' && job.params?.auto_rig === true;
let autoRigProviderDone = false;
// Pull a fresh status from the provider when the job is still in flight
// and we have an external id to query. The status endpoint serves as our
// poll trigger — no separate cron needed for short-lived jobs.
// Route by job.provider so BYOK jobs (meshy, tripo) load the right adapter
// with the user's stored key, not the platform env credential.
if ((job.status === 'queued' || job.status === 'running') && job.provider && job.ext_job_id) {
try {
const provider = await getRegenProviderForJob(job.provider, req);
if (provider.instance) {
const update = await provider.instance.status(job.ext_job_id);
let nextStatus = update.status;
let nextResultUrl = update.resultGlbUrl ?? null;
let nextError = update.error ?? null;
// Worker failure taxonomy (gcp adapter only): 'input' means the
// error text is caller-facing copy we can relay verbatim.
let nextErrorKind = update.errorKind === 'input' || update.errorKind === 'internal' ? update.errorKind : null;
// SSRF gate (defense-in-depth): a provider-returned result URL is
// attacker-influenceable if the provider account/payload is forged.
// Pin it to an allowed provider host BEFORE it ever lands in
// result_glb_url — which the cron/poll later fetch server-side. A
// disallowed URL terminates the job cleanly instead of seeding a
// poisoned fetch (the guarded fetch would reject it too, but failing
// here keeps the bad URL out of the DB).
if (nextResultUrl && !isAllowedProviderResultUrl(nextResultUrl)) {
let blockedHost = 'unparseable';
try { blockedHost = new URL(nextResultUrl).hostname; } catch { /* keep placeholder */ }
console.warn('[regenerate-status] blocked result url', { jobId, host: blockedHost });
nextStatus = 'failed';
nextResultUrl = null;
nextError = 'provider returned a disallowed result url';
nextErrorKind = null;
}
if (isAutoRig && nextStatus === 'done') autoRigProviderDone = true;
const persistStatus = isAutoRig && nextStatus === 'done' ? 'running' : nextStatus;
if (
persistStatus !== job.status ||
nextResultUrl !== job.result_glb_url ||
nextError !== job.error ||
nextErrorKind !== job.error_kind
) {
await sql`
update avatar_regen_jobs
set status = ${persistStatus},
result_glb_url = ${nextResultUrl},
error = ${nextError},
error_kind = ${nextErrorKind},
updated_at = now()
where job_id = ${jobId} and user_id = ${userId}
`;
job = {
...job,
status: persistStatus,
result_glb_url: nextResultUrl,
error: nextError,
error_kind: nextErrorKind,
};
}
}
} catch (err) {
// Surface the polling error but don't fail the request — the job
// row stays as-is and the client can retry later.
job = { ...job, error: job.error || `provider poll failed: ${err?.message}` };
}
}
// Stage 2 — the reconstructed mesh was bare and we kicked off an auto-rig
// job. Poll that child job; the shared stage swaps in the rigged GLB when it
// lands, or falls back to the bare mesh so the user is never left empty.
if (job.status === 'rigging' && job.mode === 'reconstruct' && !job.result_avatar_id) {
try {
const result = await pollRiggingStage({ userId, jobId, job });
job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };
} catch (err) {
job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {
...job,
error: job.error || `rig stage failed: ${err?.message}`,
};
}
}
// Stage 1 — the reconstruct job finished successfully but isn't materialized
// yet. The shared stage copies the GLB into R2 and either creates the avatar
// immediately or, when the mesh is unrigged and a rig model is configured,
// chains a rigging job and moves us into 'rigging' (handled above next poll).
if (
job.status === 'done' &&
job.mode === 'reconstruct' &&
!job.result_avatar_id &&
!job.source_avatar_id &&
job.result_glb_url
) {
try {
const result = await finalizeReconstructStage({ userId, jobId, job, glbUrl: job.result_glb_url });
job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };
} catch (err) {
job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {
...job,
error: job.error || `materialize failed: ${err?.message}`,
};
}
}
// Auto-rig completion (browser-poll fallback to the webhook) — a static
// upload/import/forge avatar finished its 'rerig' job. Materialize the rigged
// result as a sibling and re-point the agent at it; resultAvatarId is the NEW
// sibling id so the browser navigates to the animation-ready model. Gated on
// auto_rig so the manual rig panel (which materializes a sibling client-side)
// is untouched.
// Fire when the provider just reported success (autoRigProviderDone — the row is
// now persisted as the non-terminal 'running', not 'done') OR when the row was
// already 'done' on entry (a legacy orphan from before Strategy A, or another
// driver mid-flight). finalize's DB claim makes a concurrent fire a safe no-op.
if (
isAutoRig &&
!job.result_avatar_id &&
job.result_glb_url &&
(autoRigProviderDone || job.status === 'done')
) {
try {
const result = await finalizeAutoRigStage({ userId, jobId, job, glbUrl: job.result_glb_url });
job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };
} catch (err) {
job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {
...job,
error: job.error || `auto-rig finalize failed: ${err?.message}`,
};
}
}
const response = { ok: true, jobId: job.job_id, status: job.status };
if (job.result_avatar_id) response.resultAvatarId = job.result_avatar_id;
if (job.result_glb_url) response.resultGlbUrl = job.result_glb_url;
// Never return the raw provider/job error — it can carry a vendor name, task
// id, or upstream status. The DB row keeps the raw value for operators; the
// wire gets the masked form only (safe for both the web UI and API consumers).
// One exception: our own avatar workers classify a failure as error_kind
// 'input' when the error text is caller-facing by contract ("no face
// detected in any of the provided photos"), so relay that copy verbatim
// instead of collapsing it into the generic retry message.
const maskedError = job.error_kind === 'input' && job.error
? String(job.error).slice(0, 300)
: sanitizeJobError(job.error);
if (maskedError) response.error = maskedError;
// Tell the client WHICH kind of copy it just received. Without this the
// browser has to guess, and its keyword-matching fallback rewrites the
// caller-facing text we deliberately relayed verbatim into a generic
// "try a clearer photo" that is wrong for a quota or a plan refusal.
if (job.error_kind === 'input' && maskedError) response.errorKind = 'input';
if (job.provider) response.provider = job.provider;
return json(res, 200, response);
});
// ── presign-thumbnail ─────────────────────────────────────────────────────────
// Called by the browser after rendering a GLB preview via <model-viewer>.
// The client captures toBlob() and uploads the PNG here, then PATCHes the
// avatar record with the resulting thumbnail_key.
const thumbnailPresignSchema = z.object({
avatar_id: z.string().uuid(),
size_bytes: z.number().int().min(1).max(2 * 1024 * 1024), // 2 MB max for a PNG thumb
});
const handlePresignThumbnail = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const body = parse(thumbnailPresignSchema, await readJson(req));
// Verify caller owns the avatar they're thumbnailing.
const rows = await (await import('../_lib/db.js')).sql`
select id, storage_key from avatars
where id = ${body.avatar_id} and owner_id = ${userId} and deleted_at is null
limit 1
`;
if (!rows[0]) return error(res, 404, 'not_found', 'avatar not found or not yours');
// Thumbnail key: same prefix as the GLB, different suffix.
const thumbKey = rows[0].storage_key.replace(/\.glb$/i, '') + '_thumb.jpg';
const uploadUrl = await presignUpload({ key: thumbKey, contentType: 'image/jpeg' });
return json(res, 200, {
thumb_key: thumbKey,
upload_url: uploadUrl,
method: 'PUT',
headers: { 'content-type': 'image/jpeg' },
expires_in: 300,
});
});
// ── presign-usdz ──────────────────────────────────────────────────────────────
// Called by the browser after a GLB upload completes. The client converts the
// GLB → USDZ in-memory via three's USDZExporter and PUTs it to R2 here, then
// PATCHes the avatar row with the returned usdz_key. Enables iOS Quick Look
// for every avatar without an external USDZ source.
const usdzPresignSchema = z.object({
avatar_id: z.string().uuid(),
size_bytes: z.number().int().min(1).max(50 * 1024 * 1024), // 50 MB cap — USDZ is larger than GLB
});
const handlePresignUsdz = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const body = parse(usdzPresignSchema, await readJson(req));
const rows = await sql`
select id, storage_key from avatars
where id = ${body.avatar_id} and owner_id = ${userId} and deleted_at is null
limit 1
`;
if (!rows[0]) return error(res, 404, 'not_found', 'avatar not found or not yours');
const usdzKey = rows[0].storage_key.replace(/\.glb$/i, '') + '.usdz';
const uploadUrl = await presignUpload({ key: usdzKey, contentType: 'model/vnd.usdz+zip' });
return json(res, 200, {
usdz_key: usdzKey,
upload_url: uploadUrl,
method: 'PUT',
headers: { 'content-type': 'model/vnd.usdz+zip' },
expires_in: 300,
});
});
// ── presign-halfbody ──────────────────────────────────────────────────────────
// Half-body (waist-up) GLB variant used in VR / first-person seats. Generated
// client-side by stripping the lower-body bone hierarchy + skinned mesh from
// the source avatar. Uploaded here, then PATCHed onto the avatar row.
const halfbodyPresignSchema = z.object({
avatar_id: z.string().uuid(),
size_bytes: z.number().int().min(1).max(25 * 1024 * 1024),
});
const handlePresignHalfbody = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const body = parse(halfbodyPresignSchema, await readJson(req));
const rows = await sql`
select id, storage_key from avatars
where id = ${body.avatar_id} and owner_id = ${userId} and deleted_at is null
limit 1
`;
if (!rows[0]) return error(res, 404, 'not_found', 'avatar not found or not yours');
const halfKey = rows[0].storage_key.replace(/\.glb$/i, '') + '_halfbody.glb';
const uploadUrl = await presignUpload({ key: halfKey, contentType: 'model/gltf-binary' });
return json(res, 200, {
halfbody_key: halfKey,
upload_url: uploadUrl,
method: 'PUT',
headers: { 'content-type': 'model/gltf-binary' },
expires_in: 300,
});
});
// ── auto-tag ──────────────────────────────────────────────────────────────────
// Called after thumbnail upload; sends the poster to Claude vision for
// auto-generated tags and a one-line description. Non-blocking — a failure
// here must never fail the upload flow.
const autoTagSchema = z.object({
avatar_id: z.string().uuid(),
thumb_key: z.string().min(1).max(512),
});
const AVATAR_TAG_PROMPT = `You are a 3D avatar classification assistant.
Given a screenshot of a 3D avatar, respond with ONLY a JSON object:
{
"tags": [3-6 tags from: humanoid, robot, animal, vehicle, stylized, realistic, anime, creature, character, abstract, military, fantasy, sci-fi, casual, formal],
"description": "One sentence describing this 3D avatar (20-60 words)."
}
Respond with nothing else — no markdown, no explanation.`;
// Classify an avatar thumbnail with a vision-capable model. Platform LLM
// policy (api/_lib/llm.js): free providers lead — OpenRouter's free vision
// Llama, then the same model family on NVIDIA NIM — and paid Anthropic is the
// last-resort backstop. Every configured provider is TRIED in order (not
// pick-first-and-die): a 429 on the free tier degrades to the next lane
// instead of failing the auto-tag. Throws { code: 'not_configured' } when no
// vision provider is available so the caller can skip silently.
async function classifyAvatarImage({ thumbUrl, prompt, env }) {
const openaiVision = (name, key, url, model, extraHeaders = {}) => async () => {
const r = await fetchUpstream(url, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${key}`, ...extraHeaders },
body: JSON.stringify({
model,
max_tokens: 256,
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'image_url', image_url: { url: thumbUrl } },
],
},
],
}),
}, { name: `${name}:vision`, timeoutMs: VISION_TIMEOUT_MS, attempts: 1, okWhen: () => true });
if (!r.ok) throw Object.assign(new Error(`${name} vision ${r.status}`), { code: 'vision_api_error' });
const d = await r.json();
return d.choices?.[0]?.message?.content || '';
};
const attempts = [];
if (env.OPENROUTER_API_KEY) {
attempts.push(openaiVision(
'openrouter',
env.OPENROUTER_API_KEY,
'https://openrouter.ai/api/v1/chat/completions',
'meta-llama/llama-3.2-11b-vision-instruct',
OPENROUTER_ATTRIBUTION_HEADERS,
));
}
if (env.NVIDIA_API_KEY) {
attempts.push(openaiVision(
'nvidia',
env.NVIDIA_API_KEY,
'https://integrate.api.nvidia.com/v1/chat/completions',
'meta/llama-3.2-11b-vision-instruct',
));
}
if (env.ANTHROPIC_API_KEY) {
attempts.push(async () => {
const r = await fetchUpstream('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-haiku-4-5-20251001',
max_tokens: 256,
messages: [
{
role: 'user',
content: [
{ type: 'image', source: { type: 'url', url: thumbUrl } },
{ type: 'text', text: prompt },
],
},
],
}),
}, { name: 'anthropic:vision', timeoutMs: VISION_TIMEOUT_MS, attempts: 1, okWhen: () => true });
if (!r.ok) throw Object.assign(new Error(`anthropic vision ${r.status}`), { code: 'vision_api_error' });
const d = await r.json();
// Pick the first TEXT block rather than content[0]: on a thinking-capable
// model the leading block is a (possibly empty) thinking block, which
// would silently classify every avatar as untagged.
return (d.content || []).find((b) => b?.type === 'text')?.text || '';
});
}
if (!attempts.length) {
throw Object.assign(new Error('no vision provider configured'), { code: 'not_configured' });
}
let lastErr;
for (const attempt of attempts) {
try {
return await attempt();
} catch (err) {
lastErr = err;
}
}
throw lastErr;
}
const handleAutoTag = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolvePresignUser(req, 'avatars:write');
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const body = parse(autoTagSchema, await readJson(req));
// Verify ownership.
const { sql } = await import('../_lib/db.js');
const rows = await sql`
select id, name, tags, description, thumbnail_key
from avatars where id = ${body.avatar_id} and owner_id = ${userId} and deleted_at is null
limit 1
`;
if (!rows[0]) return error(res, 404, 'not_found', 'avatar not found');
// Never trust thumb_key blindly: it is used for a server-side vision fetch and
// written into avatars.thumbnail_key (which decorate() exposes as a public
// URL). Restrict it to keys the caller can legitimately own — either their own
// u/<userId>/ namespace, or the canonical thumb/<avatarId>.png slot for THIS
// avatar (the shape thumbnail.js writes). Anything else would let one user
// point the fetch at, and publicly disclose, another user's private object.
const thumbKey = body.thumb_key;
const ownsKey =
thumbKey.startsWith(`u/${userId}/`) || thumbKey === `thumb/${body.avatar_id}.png`;
if (!ownsKey) {
return error(res, 400, 'invalid_storage_key', 'thumb_key must live under your namespace');
}
// Fetch the thumbnail from R2 for vision.
const { publicUrl, headObject } = await import('../_lib/r2.js');
const { env } = await import('../_lib/env.js');
// `thumb_key` is caller-supplied. Ownership was checked above, but nothing has
// checked that an object actually lives there — the caller may never have
// completed the upload. Confirm it before we (a) spend a vision call on a URL
// that 404s and (b) write the key into avatars.thumbnail_key, from where
// decorate() would publish it into an <img> that Chrome blocks as ORB.
// The invariant: a thumbnail_key is persisted only after its object exists.
if (!(await headObject(thumbKey))) {
return error(res, 404, 'thumbnail_not_found', 'no object stored at thumb_key — upload the thumbnail first');
}
const thumbUrl = publicUrl(thumbKey);
// Image classification needs a vision-capable model. Per platform policy
// the free providers come first (OpenRouter hosts open vision models);
// Anthropic is BYOK and only used when a server-side key is present. When
// no vision provider is configured we skip auto-tagging rather than fail —
// it is an enhancement, not a required step.
let visionText;
try {
visionText = await classifyAvatarImage({ thumbUrl, prompt: AVATAR_TAG_PROMPT, env });
} catch (err) {
console.error('[auto-tag] vision error', err.message);
return json(res, 200, { ok: false, reason: err.code || 'vision_api_error' });
}
let parsed;
try {
parsed = JSON.parse((visionText || '{}').trim());
} catch {
return json(res, 200, { ok: false, reason: 'parse_error' });
}
const newTags = Array.isArray(parsed.tags) ? parsed.tags.slice(0, 6) : [];
const desc = typeof parsed.description === 'string' ? parsed.description.slice(0, 500) : '';
// Only write if the avatar still has no tags/description (don't overwrite manual ones).
const currentTags = rows[0].tags || [];
const currentDesc = rows[0].description || '';
const patch = {};
if (!currentTags.length && newTags.length) patch.tags = newTags;
if (!currentDesc && desc) patch.description = desc;
// Always write thumbnail_key if not set yet — using the validated key only.
if (!rows[0].thumbnail_key) patch.thumbnail_key = thumbKey;
if (Object.keys(patch).length) {
await sql`
update avatars set
tags = coalesce(${patch.tags ?? null}::text[], tags),
description = coalesce(${patch.description ?? null}, description),
thumbnail_key = coalesce(${patch.thumbnail_key ?? null}, thumbnail_key),
updated_at = now()
where id = ${body.avatar_id} and owner_id = ${userId}
`;
}
return json(res, 200, { ok: true, tags: newTags, description: desc });
});
// ── reconstruct (Phase 1 — Selfie → Avatar engine) ────────────────────────────
// Submits a reconstruct job from selfie photos. No source avatar exists yet;
// the avatar row is materialized when the status handler observes a successful
// result and copies the generated GLB into R2.
//
// Provider resolution order:
// 1. Platform env (REPLICATE_API_TOKEN / GCP_RECONSTRUCTION_URL / HF_TOKEN)
// 2. Inline BYOK key in request body (provider_name + provider_key)
// 3. User's stored BYOK key for a supported provider (meshy > tripo)
// When none is available, returns needs_key so the client can prompt for a key.
// Photos may be either:
// • http(s):// URL — typically an R2 object URL the client uploaded first
// • data:image/...;base64,... — inline base64 (Replicate / Meshy accept these)
const photoUrlOrDataUri = z
.string()
.max(8 * 1024 * 1024) // generous cap to allow inline JPEGs up to ~6 MB pre-base64
.refine(
(v) =>
/^https?:\/\//i.test(v) ||
/^data:image\/(png|jpe?g|webp|heic|heif);base64,/i.test(v),
'must be an http(s) URL or a data:image/* base64 URI',
);
const reconstructSchema = z
.object({
name: z.string().trim().min(1).max(120),
description: z.string().trim().max(500).optional(),
photos: z.array(photoUrlOrDataUri).min(1).max(6).optional(),
// Text → avatar: a prompt is painted as one full-body reference image,
// reconstructed on a full-figure image→3D engine (self-hosted Hunyuan3D
// first), then auto-rigged by the same finalize tail as a selfie. See
// _lib/prompt-avatar.js. One of `photos` or `prompt` is required.
prompt: z.string().trim().min(3).max(600).optional(),
visibility: z.enum(['private', 'unlisted', 'public']).optional(),
params: z.record(z.unknown()).optional(),
// BYOK: caller can supply their own provider key when the platform backend
// is unconfigured. Never stored on the job row.
provider_key: z.string().trim().max(512).optional(),
provider_name: z.enum(['meshy', 'tripo']).optional(),
})
.refine((v) => (Array.isArray(v.photos) && v.photos.length > 0) || !!v.prompt, {
message: 'provide either photos or a prompt',
path: ['photos'],
});
const handleReconstruct = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolveRegenUser(req);
if (!userId) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');
const rl = await limits.upload(userId);
if (!rl.success) return rateLimited(res, rl);
const body = parse(reconstructSchema, await readJson(req));
// A library that is already at its plan ceiling cannot accept the avatar this
// job would produce, and nothing downstream discovers that until
// materialization, about ninety seconds of GPU reconstruction (plus a Flux
// reference image on the prompt lane) after the user pressed the button. The
// job then strands at 'done' with no avatar and the browser shows the generic
// engine-fault copy, which is both a lie and a dead end: every retry burns the
// same spend and lands in the same place. Refuse here instead, with the 402
// the client already renders as "Avatar quota reached".
try {
await assertAvatarSlotAvailable(userId);
} catch (err) {
if (isPlanLimitError(err)) {
return error(
res,
402,
'plan_limit',
'Your avatar library is full on this plan. Delete an avatar or upgrade to build another.',
);
}
throw err;
}
// ── Provider resolution ──────────────────────────────────────────────────
// Build the ordered list of providers to try. Every configured platform
// provider leads (primary first), then the caller's BYOK keys (inline, then
// stored) backstop them — so a single provider outage, throttle, or credit
// exhaustion fails over to the next instead of dead-ending the job. Each
// entry is { name, instance }; names are de-duplicated.
const reconstructCandidates = await resolveReconstructCandidates(req, body);
// A prompt with no photos never goes to the face pipeline: it runs the
// full-body lane plan (see _lib/prompt-avatar.js). Each entry carries the
// adapter mode to run, so one provider (gcp) can offer several engines.
const fromPrompt = !(Array.isArray(body.photos) && body.photos.length);
const candidates = fromPrompt
? planPromptAvatarLanes({
platform: reconstructCandidates.filter((c) => !BYOK_REGEN_PROVIDERS.includes(c.name)),
byok: reconstructCandidates.filter((c) => BYOK_REGEN_PROVIDERS.includes(c.name)),
health: await promptLaneHealth(),
country: requestTerritory(req),
})
: reconstructCandidates.map((c) => ({ ...c, mode: 'reconstruct', lane: c.name, params: {} }));
// Nothing configured anywhere — tell the client which BYOK providers are
// accepted (unchanged 402 contract the client branches on).
if (candidates.length === 0) {
return json(res, 402, {
ok: false,
code: 'regen_needs_byok',
message:
'Avatar reconstruction requires an API key. Add your Meshy or Tripo key in settings, or pass provider_key + provider_name in this request.',
providers: BYOK_REGEN_PROVIDERS,
});
}
// Text → avatar: paint the prompt as one full-body reference image for the
// image→3D engine. Done only once a backend is known to be live, so a
// configuration gap never burns an image generation.
let photos = body.photos ?? null;
let referenceImageUrl = null;
if (fromPrompt) {
try {
// The forge's reference-image lane (Vertex first, then the shared
// text→image ladder), square like the forge's own avatar references:
// the free FLUX rung returned a visibly blurred 832x1216 portrait
// frame for this framing while its 1:1 output was sharp.
const generated = await generateReferenceImage(promptAvatarImagePrompt(body.prompt), {
aspectRatio: '1:1',
});
referenceImageUrl = generated.imageUrl;
photos = [generated.imageUrl];
} catch (err) {
// Map the reference-image failure to the most accurate status so the
// symptom is self-explanatory instead of a blank 502. The text→image ladder tags
// its errors: 'unconfigured' (no provider), 'rate_limited' (Replicate
// throttle — common when account credit is low, carries retryAfter),
// 'provider_unreachable' (network), or a raw providerStatus (e.g. 402
// billing). Anything else is a genuine upstream 5xx.
if (err?.code === 'unconfigured') {
return error(res, 501, 'txt2img_unconfigured', 'The avatar generator is not available on this deployment yet.');
}
if (err?.code === 'rate_limited') {
const retryAfter = Number(err.retryAfter) || 10;
res.setHeader('retry-after', String(retryAfter));
return error(
res,
429,
'txt2img_rate_limited',
err.message || 'the image provider is throttling requests — try again shortly',
{ retry_after: retryAfter },
);
}
if (err?.code === 'provider_unreachable') {
return error(res, 503, 'txt2img_unreachable', 'Could not reach the image engine — please try again shortly.');
}
if (err?.code === 'billing' || err?.providerStatus === 402) {
// Never relay the provider's raw "purchase credit at …/billing"
// copy — even the error_description must be buyer-safe, since a
// client may surface it verbatim. The text→image ladder already logged the
// raw detail (providerDetail) for operators.
return error(
res,
402,
'txt2img_billing',
'the image engine is temporarily unavailable — please try again later',
);
}
return error(
res,
502,
'txt2img_error',
'Could not generate a reference image from your prompt — try rewording it.',
);
}
}
// ── Submit with provider failover ─────────────────────────────────────────
// Try each candidate in turn. A submit() only spends provider credits on
// success (the prediction/task is created server-side after the call
// returns), so advancing past a thrown error never double-charges. We keep
// the most actionable classified error to surface if every provider fails.
let submission = null;
let usedProvider = null;
let bestError = null;
const attempts = [];
for (const provider of candidates) {
try {
submission = await submitWithTransientRetry(provider.instance, {
userId,
mode: provider.mode,
params: { ...pickReconstructParams(body.params), ...provider.params, images: photos, name: body.name },
sourceUrl: photos[0],
});
usedProvider = provider;
break;
} catch (err) {
const classified = classifyProviderError(err);
attempts.push(`${provider.lane}:${err?.code || err?.status || classified.code}`);
console.warn(
'[avatars] reconstruct submit failed on',
provider.lane,
'—',
err?.code || err?.status || 'unknown',
'-',
err?.message,
);
// Prefer the first error that points to a concrete, user-fixable cause
// (bad key, no credits, bad request) over a generic retry — that is the
// most useful thing to tell the user if nothing succeeds.
if (!bestError || (isGenericProviderError(bestError) && !isGenericProviderError(err))) {
bestError = err;
}
}
}
if (!submission || !usedProvider) {
if (attempts.length > 1) {
console.warn('[avatars] all reconstruct providers failed:', attempts.join(', '));
}
return maskSubmitError(res, bestError || new Error('no reconstruct provider available'));
}
const jobId = `${usedProvider.name}-${randomUUID()}`;
const params = {
images: photos,
name: body.name,
description: body.description ?? null,
// Same rule as POST /api/avatars: an explicit choice wins, silence falls
// back to the owner's default from /settings.
visibility: body.visibility ?? (await defaultAvatarVisibilityFor(userId, 'private')),
...(fromPrompt
? { source: 'prompt', prompt: body.prompt, referenceImageUrl, engine: usedProvider.lane }
: {}),
};
await sql`
insert into avatar_regen_jobs
(job_id, user_id, source_avatar_id, mode, params, status, provider, ext_job_id, created_at, updated_at)
values
(${jobId}, ${userId}, ${null}, ${'reconstruct'}, ${JSON.stringify(params)}, 'queued', ${usedProvider.name}, ${submission.extJobId ?? null}, now(), now())
`;
return json(res, 202, {
ok: true,
jobId,
status: 'queued',
eta: submission.eta ?? null,
provider: usedProvider.name,
});
});
// Liveness of the self-host image→3D lanes the prompt plan leads with, so a
// worker whose model failed to load is tried last instead of accepting the job
// and failing it minutes later. Best-effort: no telemetry keeps the plan order.
async function promptLaneHealth() {
try {
return (await laneHealthSnapshot(['trellis2', 'hunyuan3d', 'trellis_selfhost'])).byId;
} catch (err) {
console.warn('[avatars] prompt lane health skipped:', err?.message);
return {};
}
}
// Assemble the ordered provider candidate list for a reconstruct submit:
// configured platform providers (primary first) followed by the caller's BYOK
// keys (inline body key, then stored keys), de-duplicated by provider name.
async function resolveReconstructCandidates(req, body) {
const candidates = [];
const seen = new Set();
const add = (resolved) => {
if (resolved?.instance && !seen.has(resolved.name)) {
seen.add(resolved.name);
candidates.push(resolved);
}
};
// 1. Every configured platform provider, in precedence order.
try {
for (const p of await getRegenProviderCandidates()) add(p);
} catch (err) {
console.warn('[avatars] platform provider enumeration failed:', err?.message);
}
// 2. Inline BYOK key supplied by the client (provider_name + provider_key).
if (body.provider_key && body.provider_name) {
try {
add(getRegenProviderByName(body.provider_name, body.provider_key));
} catch (err) {
console.warn('[avatars] inline BYOK provider load failed:', err?.message);
}
}
// 3. User's stored BYOK keys — iterate preferred providers in order.
for (const pName of BYOK_REGEN_PROVIDERS) {
if (seen.has(pName)) continue;
try {
const key = await resolveProviderKey(req, null, pName);
if (key) add(getRegenProviderByName(pName, key));
} catch {
// resolveProviderKey can fail when there is no DB session — skip.
}
}
return candidates;
}
// A "generic" provider error is the catch-all 502 (unreachable / unclassified
// provider_error) — i.e. one that doesn't name a concrete, user-fixable cause.
// Used to prefer the most actionable error when reporting an all-providers-failed
// outcome.
function isGenericProviderError(err) {
return classifyProviderError(err).code === 'regen_provider_error';
}
// Infra faults worth one quick retry against the *same* provider before failing
// over or giving up: transport errors and upstream 5xx. These are the cold-start
// and transient-network failures behind most "engine rejected the job" 502s — a
// single bounded retry clears them without the user noticing, and on a
// single-provider deployment it's the only second chance there is. Deterministic
// faults (bad key, no credits, bad input, throttle, a provider 4xx) are never
// retried here: an identical second call won't change the outcome.
export function isTransientProviderError(err) {
if (!err) return false;
if (err.code === 'provider_unreachable' || err.code === 'provider_timeout') return true;
const upstream = Number(err.providerStatus) || 0;
if (err.code === 'provider_error') {
// No upstream status (couldn't even parse a response) or a 5xx → transient.
// A concrete provider 4xx (e.g. 422 bad image) is deterministic — don't retry.
return upstream === 0 || upstream >= 500;
}
const status = Number(err.status) || 0;
return status === 503 || status === 504;
}
const SUBMIT_RETRY_DELAY_MS = 1500;
// Submit one provider job, retrying once on a transient infra fault. The retry
// is safe against double-charging: a provider only spends credits / creates the
// upstream prediction on a successful return, so a thrown error means nothing
// was queued. Non-transient errors propagate immediately for the caller to
// classify (and, in the failover loop, fail over to the next provider).
export async function submitWithTransientRetry(instance, request) {
try {
return await instance.submit(request);
} catch (err) {
if (!isTransientProviderError(err)) throw err;
await new Promise((resolve) => setTimeout(resolve, SUBMIT_RETRY_DELAY_MS));
return instance.submit(request);
}
}
// ── dispatcher ────────────────────────────────────────────────────────────────
const DISPATCH = {
presign: handlePresign,
upload: handleUpload,
'presign-thumbnail': handlePresignThumbnail,
'presign-usdz': handlePresignUsdz,
'presign-halfbody': handlePresignHalfbody,
'auto-tag': handleAutoTag,
public: handlePublic,
reconstruct: handleReconstruct,
regenerate: handleRegenerate,
'regenerate-status': handleRegenerateStatus,
};
export function dispatch(action, req, res) {
const fn = DISPATCH[action];
if (!fn) return error(res, 404, 'not_found', `unknown avatar action: ${action}`);
return fn(req, res);
}