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
// Tripo provider: alternative native geometry-first backend, on Tripo's v3 API.
//
// geometry path → POST /generation/text-to-model
// Native text->model: clean (often quad) geometry directly from the
// prompt. `face_limit` carries the tier's poly budget.
//
// image path → POST /generation/image-to-model
// Single-image reconstruction with PBR textures.
//
// v3 gives every capability its own endpoint (no more shared `type` field) and
// unifies every file/task source under a single `input` string: a public
// http(s) URL, a `task_id` from a prior task, or a `file_token` from /files.
// Every task type polls the same GET /tasks/{id}, returning
// {status, output, credits_consumed, created_at, completed_at}; rig-check is
// the one task whose `output` is `{riggable, rig_type}` instead of a model url.
//
// BYOK or house key: the caller passes either the user's Tripo key (tsk_...)
// or, when TRIPO_API_KEY is set, the platform's own key (forge-tiers.js /
// forge-provider-key.js resolve which one). The model version defaults to
// v3.1 and is overridable via TRIPO_MODEL_VERSION.
import { fetchUpstream } from '../_lib/upstream-fetch.js';
const TRIPO_BASE = 'https://openapi.tripo3d.com/v3';
const DEFAULT_MODEL_VERSION = 'v3.1-20260211';
// Tripo's face_limit is unbounded upward in practice, but keep the same sane
// floor/ceiling as the rest of the pipeline so a tier can't request an
// unworkable mesh.
const FACE_MIN = 100;
const FACE_MAX = 300_000;
function clampFaces(n) {
const v = Math.round(Number(n) || 0);
return Math.max(FACE_MIN, Math.min(FACE_MAX, v));
}
function modelVersion() {
if (typeof process !== 'undefined' && process.env?.TRIPO_MODEL_VERSION) {
return process.env.TRIPO_MODEL_VERSION;
}
return DEFAULT_MODEL_VERSION;
}
// Exported so forge.js and the exported-file attribution stamp can name the
// exact version a job ran on, without a second source of truth: this is the
// same value threaded into every request body below.
export const tripoModelVersion = modelVersion;
function mapStatus(s) {
switch (String(s || '').toLowerCase()) {
case 'queued':
return 'queued';
case 'running':
return 'running';
case 'success':
return 'done';
case 'failed':
case 'cancelled':
return 'failed';
default:
return 'queued';
}
}
// Parse a data:image/...;base64,... URI into its raw bytes, mime, and the file
// extension Tripo expects. Returns null for anything that isn't a base64 image
// data URI (e.g. a plain http(s) URL), so callers can branch on it.
function parseImageDataUri(s) {
const m = /^data:(image\/(?:png|jpe?g|webp));base64,(.+)$/is.exec(String(s || ''));
if (!m) return null;
const mime = m[1].toLowerCase();
const ext = mime === 'image/png' ? 'png' : mime === 'image/webp' ? 'webp' : 'jpg';
let bytes;
try {
bytes = Buffer.from(m[2], 'base64');
} catch {
return null;
}
if (!bytes.length) return null;
return { bytes, mime, ext };
}
// Every v3 error response (any status) is the unified envelope
// { code, message, suggestion, request_id }. HTTP status is advisory;
// disambiguate credits-vs-permission on 403 using the error code, since Tripo
// overloads 403 for both "no permission" and "insufficient credits".
function classify(res, data) {
if (res.status === 401) {
throw Object.assign(new Error(data?.message || 'Tripo rejected the API key.'), {
code: 'invalid_key',
status: 401,
providerStatus: res.status,
});
}
if (data?.code === 2010) {
throw Object.assign(new Error(data?.message || 'Tripo account is out of credits.'), {
code: 'insufficient_credits',
status: 402,
providerStatus: res.status,
});
}
if (res.status === 403) {
throw Object.assign(new Error(data?.message || 'Tripo rejected the API key.'), {
code: 'invalid_key',
status: 401,
providerStatus: res.status,
});
}
if (res.status === 429 || data?.code === 2000) {
throw Object.assign(new Error(data?.message || 'Tripo is rate limiting this key.'), {
code: 'rate_limited',
status: 429,
providerStatus: res.status,
});
}
if (!res.ok || data?.code !== 0) {
throw Object.assign(
new Error(data?.message || `tripo returned ${res.status} (code ${data?.code})`),
{ code: 'provider_error', status: 502, providerStatus: res.status },
);
}
return data;
}
export function createTripoProvider(apiKey) {
if (!apiKey) {
throw Object.assign(new Error('Tripo API key is required'), { code: 'missing_key' });
}
const headers = {
authorization: `Bearer ${apiKey}`,
'content-type': 'application/json',
};
async function postJson(path, body) {
let res;
try {
res = await fetchUpstream(`${TRIPO_BASE}${path}`, {
method: 'POST',
headers,
body: JSON.stringify(body),
}, { name: 'tripo', timeoutMs: 30_000, attempts: 2, okWhen: () => true });
} catch (err) {
throw Object.assign(new Error(`tripo unreachable: ${err?.message}`), {
code: 'provider_unreachable',
status: 502,
});
}
const data = await res.json().catch(() => ({}));
return classify(res, data);
}
async function createTask(path, body) {
const data = await postJson(path, body);
const taskId = data?.data?.task_id;
if (!taskId) {
throw Object.assign(new Error('tripo accepted the task but returned no task_id'), {
code: 'provider_error',
status: 502,
});
}
return String(taskId);
}
// Pushes raw bytes (a selfie data URI, a re-exported mesh, ...) through
// Tripo's multipart /files endpoint and hands back a file_token usable as
// `input` on any other v3 endpoint. Mirrors createTask's error
// classification so a bad key / no credits / throttle surfaces the same
// actionable code.
async function uploadFile({ bytes, mime, ext }) {
const form = new FormData();
form.append('file', new Blob([bytes], { type: mime }), `upload.${ext}`);
let res;
try {
// Let fetch set the multipart content-type (with boundary) itself, only
// forward the bearer, never the JSON content-type from `headers`.
res = await fetchUpstream(`${TRIPO_BASE}/files`, {
method: 'POST',
headers: { authorization: headers.authorization },
body: form,
}, { name: 'tripo', timeoutMs: 60_000, attempts: 2, okWhen: () => true });
} catch (err) {
throw Object.assign(new Error(`tripo upload unreachable: ${err?.message}`), {
code: 'provider_unreachable',
status: 502,
});
}
const data = await res.json().catch(() => ({}));
classify(res, data);
const token = data?.data?.file_token;
if (!token) {
throw Object.assign(new Error('tripo upload returned no file_token'), {
code: 'provider_error',
status: 502,
});
}
return String(token);
}
// Resolves an imageUrl/modelUrl into the string the v3 `input` field wants:
// a data URI is uploaded first and replaced with its file_token; a real
// http(s) URL (or an existing task_id/file_token) passes straight through.
async function resolveInput(source) {
const parsed = parseImageDataUri(source);
if (!parsed) return source;
return uploadFile(parsed);
}
// Every task type's status payload is {status, output, credits_consumed,
// error_message} except rig-check, whose output is {riggable, rig_type}
// instead of a model url. Surface both shapes on the same result object.
async function status({ taskId }) {
let res;
try {
res = await fetchUpstream(`${TRIPO_BASE}/tasks/${encodeURIComponent(taskId)}`, { headers }, { name: 'tripo', timeoutMs: 15_000, attempts: 2, okWhen: () => true });
} catch (err) {
return { status: 'running', error: `tripo poll failed: ${err?.message}` };
}
const data = await res.json().catch(() => ({}));
if (res.status === 404) return { status: 'failed', error: 'tripo task not found' };
if (!res.ok || data?.code !== 0) {
return { status: 'running', error: `tripo returned ${res.status}` };
}
const d = data.data || {};
const taskStatus = mapStatus(d.status);
const result = { status: taskStatus, progress: Number(d.progress) || 0 };
if (taskStatus === 'done') {
const out = d.output || {};
if (out.model_url) {
result.resultGlbUrl = out.model_url;
} else if (typeof out.riggable === 'boolean') {
result.riggable = out.riggable;
result.rigType = out.rig_type || null;
} else {
result.error = 'tripo finished but produced no model url';
}
if (typeof d.credits_consumed === 'number') result.creditsConsumed = d.credits_consumed;
}
if (taskStatus === 'failed') {
result.error = d.error_message || `tripo task ${d.status || 'failed'}`;
}
return result;
}
return {
// targetFaces overrides the tier's poly budget when the caller sent an
// explicit target_polycount/target_faces (forge-options.js).
async textToGeometry({ prompt, tier, targetPolycount: targetFaces }) {
const taskId = await createTask('/generation/text-to-model', {
prompt: String(prompt).slice(0, 1024),
model: modelVersion(),
face_limit: clampFaces(targetFaces ?? tier.polycount),
texture: false,
pbr: false,
});
return { kind: 'task', taskId };
},
async imageTo3d({ imageUrl, tier, targetPolycount: targetFaces }) {
const input = await resolveInput(imageUrl);
const taskId = await createTask('/generation/image-to-model', {
input,
model: modelVersion(),
face_limit: clampFaces(targetFaces ?? tier.polycount),
texture: true,
pbr: Boolean(tier.pbr),
});
return { kind: 'task', taskId };
},
// One status endpoint for every task type.
status,
// Riggability pre-check: recommended before rig() so the UI can show
// "not riggable" without spending a rig credit.
async rigCheck({ input }) {
const taskId = await createTask('/animations/rig-check', { input: await resolveInput(input) });
return { kind: 'task', taskId };
},
// spec:'mixamo' asks Tripo for Mixamo-named bones, which plugs directly
// into this repo's existing glb-canonicalize.js Mixamo mapping, no new
// bone-naming code needed on our side.
async rig({ input, rigType, model, spec = 'mixamo', outFormat = 'glb' }) {
const body = { input: await resolveInput(input), spec, out_format: outFormat };
if (rigType) body.rig_type = rigType;
if (model) body.model = model;
const taskId = await createTask('/animations/rig', body);
return { kind: 'task', taskId };
},
async retarget({ input, animation, animations, outFormat = 'glb', bakeAnimation = true }) {
const body = { input, out_format: outFormat, bake_animation: bakeAnimation };
if (Array.isArray(animations) && animations.length) body.animations = animations;
else body.animation = animation || 'preset:walk';
const taskId = await createTask('/animations/retarget', body);
return { kind: 'task', taskId };
},
// Retopology for the "game-ready" preset. v3.0 can also unwrap UVs
// (smart_uv) in the same task; v2.0 (default) does smart highpoly-to-
// lowpoly retopology; v1.0 is basic decimation.
async decimate({ input, faceLimit, quad = false, smartUv = false, model = 'v2.0' }) {
const body = { input: await resolveInput(input), model, quad: Boolean(quad) };
if (faceLimit) body.face_limit = clampFaces(faceLimit);
if (smartUv) body.smart_uv = true;
const taskId = await createTask('/mesh/decimate', body);
return { kind: 'task', taskId };
},
// Semantic/geometry segmentation feeding the parts editor.
async segment({ input, model = 'v1.0-20250506' }) {
const taskId = await createTask('/mesh/segment', { input: await resolveInput(input), model });
return { kind: 'task', taskId };
},
// Exposed so callers that already have raw bytes (not an imageUrl/task_id)
// can get a file_token without duplicating the upload logic.
uploadFile,
};
}