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
// Rodin (Hyper3D) provider — native geometry-first + image→3D backend with
// quad topology and a real poly-count target. A BYOK alternative to Meshy/Tripo.
//
// Three real Rodin Gen-2 endpoints back the forge paths:
//
// geometry path → POST /api/v2/rodin { tier:"Gen-2", prompt, mesh_mode:"Quad" }
// Native text→geometry: emits an untextured quad mesh directly from the
// prompt. `quality_override` carries the tier's poly budget.
//
// image path → POST /api/v2/rodin { tier:"Gen-2", images:<file>, prompt? }
// Single-image reconstruction with PBR texturing + quad topology.
//
// Submit is multipart/form-data and returns a top-level task `uuid` (used to
// download results) plus `jobs.subscription_key` (used to poll status). Both
// ids are needed later, so the forge job handle carries the subscription key in
// `kind` and the download uuid in `taskId`. Status is polled on /api/v2/status;
// when Done, the GLB url is fetched from /api/v2/download.
//
// BYOK only: the caller supplies their own Rodin key. No platform key — when
// absent, the forge endpoint never reaches this module.
import { fetchUpstream, fetchUpstreamPublic } from '../_lib/upstream-fetch.js';
const RODIN_BASE = 'https://api.hyper3d.com/api/v2';
// Quad mode accepts 1,000–200,000 for the poly target; clamp the tier budget
// into that window so a request never 4xxs on an out-of-range count.
const POLY_MIN = 1_000;
const POLY_MAX = 200_000;
function clampPoly(n) {
const v = Math.round(Number(n) || 0);
return Math.max(POLY_MIN, Math.min(POLY_MAX, v));
}
// Map the forge tier to Rodin's named quality rung (quality_override still
// carries the exact poly target; this is the coarse speed/detail knob).
function qualityForTier(tier) {
switch (tier?.id) {
case 'draft':
return 'low';
case 'high':
return 'high';
default:
return 'medium';
}
}
function mapStatus(jobs) {
const statuses = (Array.isArray(jobs) ? jobs : []).map((j) => String(j?.status || ''));
if (!statuses.length) return 'queued';
if (statuses.some((s) => s === 'Failed')) return 'failed';
if (statuses.every((s) => s === 'Done')) return 'done';
if (statuses.some((s) => s === 'Generating')) return 'running';
return 'queued';
}
function glbFromList(list) {
if (!Array.isArray(list)) return null;
// Prefer an explicit .glb; ignore preview.webp and texture maps.
const glb = list.find((f) => /\.glb($|\?)/i.test(String(f?.name || f?.url || '')));
return glb?.url || null;
}
export function createRodinProvider(apiKey) {
if (!apiKey) {
throw Object.assign(new Error('Rodin API key is required'), { code: 'missing_key' });
}
const authHeader = { authorization: `Bearer ${apiKey}` };
function normalizeError(res, data) {
if (res.status === 401 || res.status === 403) {
return Object.assign(new Error('Rodin rejected the API key.'), {
code: 'invalid_key',
status: 401,
providerStatus: res.status,
});
}
if (res.status === 402) {
return Object.assign(new Error('Rodin account is out of credits.'), {
code: 'insufficient_credits',
status: 402,
providerStatus: 402,
});
}
if (res.status === 429) {
return Object.assign(new Error('Rodin is rate limiting this key.'), {
code: 'rate_limited',
status: 429,
providerStatus: 429,
});
}
return Object.assign(
new Error(data?.error || data?.message || `rodin returned ${res.status}`),
{ code: 'provider_error', status: 502, providerStatus: res.status },
);
}
async function submit(form) {
let res;
try {
res = await fetchUpstream(`${RODIN_BASE}/rodin`, { method: 'POST', headers: authHeader, body: form }, { name: 'rodin', timeoutMs: 60_000, attempts: 2, okWhen: () => true });
} catch (err) {
throw Object.assign(new Error(`rodin unreachable: ${err?.message}`), {
code: 'provider_unreachable',
status: 502,
});
}
const data = await res.json().catch(() => ({}));
if (!res.ok || data?.error) throw normalizeError(res, data);
const uuid = data?.uuid;
const subscriptionKey = data?.jobs?.subscription_key;
if (!uuid || !subscriptionKey) {
throw Object.assign(new Error('rodin accepted the task but returned no uuid/subscription_key'), {
code: 'provider_error',
status: 502,
});
}
// kind carries the poll key; taskId carries the download uuid.
return { kind: String(subscriptionKey), taskId: String(uuid) };
}
return {
// Native geometry-first: text → untextured quad mesh, no intermediate
// image. targetPolycount overrides the tier default when the caller sent
// an explicit target_polycount/target_faces (forge-options.js).
async textToGeometry({ prompt, tier, targetPolycount }) {
const form = new FormData();
form.set('tier', 'Gen-2');
form.set('prompt', String(prompt).slice(0, 1024));
form.set('mesh_mode', 'Quad');
form.set('material', 'None');
form.set('quality', qualityForTier(tier));
form.set('quality_override', String(clampPoly(targetPolycount ?? tier.polycount)));
form.set('geometry_file_format', 'glb');
return submit(form);
},
// Single image → native geometry + PBR textures, poly target from the
// tier unless the caller overrides it explicitly.
async imageTo3d({ imageUrl, prompt, tier, targetPolycount }) {
let imgRes;
try {
// The reference image URL is caller-supplied: every hop is SSRF-checked.
imgRes = await fetchUpstreamPublic(imageUrl, {}, { timeoutMs: 20_000, attempts: 2, okWhen: () => true });
} catch (err) {
throw Object.assign(new Error(`could not fetch reference image: ${err?.message}`), {
code: 'bad_image',
status: 400,
});
}
if (!imgRes.ok) {
throw Object.assign(new Error(`reference image fetch returned ${imgRes.status}`), {
code: 'bad_image',
status: 400,
});
}
const blob = await imgRes.blob();
const form = new FormData();
form.set('tier', 'Gen-2');
form.append('images', blob, 'reference.png');
if (prompt) form.set('prompt', String(prompt).slice(0, 1024));
form.set('mesh_mode', 'Quad');
form.set('material', tier.pbr ? 'PBR' : 'Shaded');
form.set('quality', qualityForTier(tier));
form.set('quality_override', String(clampPoly(targetPolycount ?? tier.polycount)));
form.set('geometry_file_format', 'glb');
return submit(form);
},
// Poll on /status with the subscription key (carried in `kind`); when Done,
// resolve the GLB url from /download using the task uuid (carried in `taskId`).
async status({ kind, taskId }) {
let res;
try {
res = await fetchUpstream(`${RODIN_BASE}/status`, {
method: 'POST',
headers: { ...authHeader, 'content-type': 'application/json' },
body: JSON.stringify({ subscription_key: kind }),
}, { name: 'rodin', timeoutMs: 15_000, attempts: 2, okWhen: () => true });
} catch (err) {
return { status: 'running', error: `rodin poll failed: ${err?.message}` };
}
const data = await res.json().catch(() => ({}));
if (res.status === 404) return { status: 'failed', error: 'rodin task not found' };
if (!res.ok) return { status: 'running', error: `rodin returned ${res.status}` };
const status = mapStatus(data.jobs);
const result = { status };
if (status === 'failed') {
result.error = data?.error || 'rodin task failed';
return result;
}
if (status !== 'done') return result;
// Done — fetch the downloadable file list and pull the GLB url.
let dl;
try {
dl = await fetchUpstream(`${RODIN_BASE}/download`, {
method: 'POST',
headers: { ...authHeader, 'content-type': 'application/json' },
body: JSON.stringify({ task_uuid: taskId }),
}, { name: 'rodin', timeoutMs: 15_000, attempts: 2, okWhen: () => true });
} catch (err) {
return { status: 'running', error: `rodin download list failed: ${err?.message}` };
}
const dlData = await dl.json().catch(() => ({}));
if (!dl.ok) return { status: 'running', error: `rodin download returned ${dl.status}` };
const glb = glbFromList(dlData.list);
if (glb) result.resultGlbUrl = glb;
else result.error = 'rodin finished but produced no GLB';
return result;
},
};
}