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
// Shared response shaping for the free text-to-3D surfaces.
//
// One shaper, two fronts. `/api/3d/studio` (the ChatGPT Actions contract behind
// the "three.ws 3D Studio" custom GPT) and the OKX.AI A2MCP forge services
// (api/_okx3d/forge.js) hand a buyer exactly the same thing: the model URLs and
// the job state, and nothing else. No upsell block, no pricing paths, no
// internal identifiers. Keeping the shaping here means the GPT and the agent
// marketplace cannot drift into two different contracts over the same lane.
//
// The only per-surface difference is where a pending job is polled: ChatGPT
// polls a REST route, an OKX buyer calls a free MCP tool. That is the
// `pollPath` option; everything else is identical.
import { viewerUrl, arLaunchUrl } from './gpt-forge-client.js';
export const STUDIO_POLL_PATH = '/api/3d/studio';
// The painted reference view of the model, the forge's first, image-generation
// step. Surfaced on every state (pending included) so a caller can show the
// concept image the moment it exists, while the mesh is still generating: the
// same paint-then-reconstruct experience the /forge page gives.
export function previewOf(payload) {
const u = payload?.preview_image_url;
return typeof u === 'string' && /^https:\/\//.test(u) ? u : null;
}
export function tierOf(payload) {
const t = payload?.tier;
return t === 'draft' || t === 'standard' || t === 'high' ? t : null;
}
// The prompt rides the poll URL as `title` so the eventual done response can
// label the AR/viewer pages without the caller having to resend anything.
function titleSuffix(title) {
return typeof title === 'string' && title.trim()
? `&title=${encodeURIComponent(title.trim().slice(0, 80))}`
: '';
}
// Shape a forge submit response into the published contract: model URLs and job
// state only. Pure + exported so tests pin the boundary against real captured
// forge shapes without any network.
export function shapeSubmit(job, base, prompt, { pollPath = STUDIO_POLL_PATH } = {}) {
const glbUrl = typeof job?.glb_url === 'string' ? job.glb_url : '';
const preview = previewOf(job);
const tier = tierOf(job);
if (job?.status === 'done' && glbUrl) {
return {
status: 'done',
glbUrl,
viewerUrl: viewerUrl(base, glbUrl),
arUrl: arLaunchUrl(base, glbUrl, prompt),
format: 'glb',
...(preview ? { previewImageUrl: preview } : {}),
...(tier ? { tier } : {}),
};
}
const handle = job?.job_id ?? null;
const t = titleSuffix(prompt);
const eta = Number(job?.eta_seconds);
return {
status: 'pending',
job: handle,
poll: handle ? `${pollPath}?job=${encodeURIComponent(handle)}${t}` : null,
...(handle ? { watchUrl: `${base}/watch?job=${encodeURIComponent(handle)}${t}` } : {}),
format: 'glb',
...(preview ? { previewImageUrl: preview } : {}),
...(tier ? { tier } : {}),
...(Number.isFinite(eta) && eta > 0 ? { etaSeconds: Math.round(eta) } : {}),
};
}
// Shape a forge poll response into { status:'pending'|'done'|'error', ... }.
// `paid` says whether the surface asking is a metered one. It only changes what
// a FAILED job is told, and it has to: the free lanes really are free to retry,
// while a metered row settles the moment the lane accepts a job, so the free
// wording would tell a charged buyer something false about their money. See the
// failed branch below.
export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH, paid = false } = {}) {
const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';
const preview = previewOf(data);
const tier = tierOf(data);
if (data?.status === 'done' && glbUrl) {
return {
status: 'done',
job: jobId,
glbUrl,
viewerUrl: viewerUrl(base, glbUrl),
arUrl: arLaunchUrl(base, glbUrl, title),
format: 'glb',
...(preview ? { previewImageUrl: preview } : {}),
...(tier ? { tier } : {}),
};
}
if (data?.status === 'failed') {
// The message is already sanitized by /api/gpt-forge, and the lane only
// reports a failure once its own backend failover chain is exhausted, so
// this is terminal for THIS job. What a retry costs depends on the
// surface, and the difference is not cosmetic: on a metered row payment
// settles when the lane accepts the job, so the free lanes' "it costs
// nothing to try again" would tell a buyer who was already charged
// something false. Neither note claims anything about one particular job
// (a status row polls any job id it is handed); each states its own
// surface's payment model, which is what the caller has to act on. The
// exact per-call answer is the PAYMENT-RESPONSE receipt from the submit.
if (!paid) {
return {
status: 'error',
job: jobId,
error: data?.error || '3D generation hit a snag upstream, it costs nothing to try again.',
};
}
const lanes = Array.isArray(data?.retry_backends) ? data.retry_backends.filter((b) => typeof b === 'string') : [];
const upstream = String(data?.error || '3D generation hit a snag upstream').trim().replace(/[.!]+$/, '');
const note = 'Jobs here settle when the lane accepts them, so a retry is a new paid call.';
// The alternate engines ride only on the metered surface. The free lane's
// response shape is the published custom-GPT Action contract
// (public/.well-known/3d-studio-openapi.yaml, byte-guarded against its
// submission source), so a new key there is a contract change for another
// work stream to make, not a bug fix to slip in here. The /forge UI reads
// retry_backends straight off /api/gpt-forge and is unaffected.
return {
status: 'error',
job: jobId,
error: `${upstream}. ${note}`,
...(lanes.length ? { retryBackends: lanes } : {}),
};
}
// queued / running / anything transient stays pending; keep the title on the
// poll URL so it survives to the done response. Forward the live remaining
// estimate the poll carries (falling back to the lane's total estimate)
// instead of leaving the caller with N identical frames.
const t = titleSuffix(title);
// eta_remaining_seconds is dropped upstream once a job outruns its estimate.
// The lane's TOTAL estimate is not a stand-in at that point: it would restate
// a whole fresh countdown on a job already past it. Fall back to the total
// only on a frame carrying no elapsed reading at all, which is the first one.
const hasElapsedReading = Number.isFinite(Number(data?.elapsed_seconds));
const etaRemaining = Number(
hasElapsedReading ? data?.eta_remaining_seconds : (data?.eta_remaining_seconds ?? data?.eta_seconds),
);
const elapsed = Number(data?.elapsed_seconds);
return {
status: 'pending',
job: jobId,
poll: `${pollPath}?job=${encodeURIComponent(jobId)}${t}`,
watchUrl: `${base}/watch?job=${encodeURIComponent(jobId)}${t}`,
...(preview ? { previewImageUrl: preview } : {}),
...(tier ? { tier } : {}),
...(Number.isFinite(etaRemaining) && etaRemaining > 0 ? { etaSeconds: Math.round(etaRemaining) } : {}),
...(Number.isFinite(elapsed) && elapsed >= 0 ? { elapsedSeconds: Math.round(elapsed) } : {}),
};
}