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
feat(forge): add target_faces, bbox, and pose generation controls
nirholasfa02fa82d184
diff --git a/api/_lib/forge-options.js b/api/_lib/forge-options.jsindex 44adb3ed9..acc3ad345 100644--- a/api/_lib/forge-options.js+++ b/api/_lib/forge-options.js@@ -8,6 +8,16 @@// • output_format — glb (default) or a compressed variant (draco / meshopt)// • texture_size — bake textures at a specific resolution// • target_polycount — explicit geometry budget on poly-aware backends+// (target_faces is an accepted alias, same field, same validation)+// • bbox : [x, y, z] in meters; the delivered mesh is uniformly+// scaled to fit inside this box (aspect ratio preserved), centered on X/Z+// and floored at Y=0. Lane-agnostic: it is a post-generation fit applied+// to the final GLB, so every backend honors it regardless of polyControl.+// • pose : 't' | 'a' | 'none', requested rest pose for a+// humanoid/character subject. Only lanes without a caller-supplied+// reference image can honor this (BACKENDS[*].poseControl); a lane whose+// pose is already fixed by the caller's own photo reports pose_applied:+// false in the response rather than silently ignoring the field.// • resolution : TRELLIS.2 / Pixal3D voxel resolution (512, 1024 or 1536)// • view_labels : per-image front/back/left/right tag for a multi-image// request (Pixal3D's "Match my photo" lane). Null entries are allowed:@@ -41,7 +51,10 @@ export const TEXTURE_SIZES = Object.freeze([512, 1024, 2048, 4096]);const POLYCOUNT_MIN = 100;const POLYCOUNT_MAX = 500_000;-const SEED_MAX = 4_294_967_295; // uint32 — the range every provider's RNG accepts+const SEED_MAX = 4_294_967_295; // uint32 - the range every provider's RNG accepts+const BBOX_MIN = 0.01; // meters - below this a "fit" is numerically meaningless+const BBOX_MAX = 50; // meters - above this a caller almost certainly meant cm/mm+export const POSE_VALUES = Object.freeze(['t', 'a', 'none']);function compressionFor(format) {if (format === 'glb-draco') return 'draco';@@ -65,6 +78,8 @@ function compressionFor(format) {* numParts: number | null, // PartCrafter's requested part count (2-16)* derivePbr: boolean, // material completion pass, true unless opted out* lods: boolean, // build and store a real MSFT_lod chain, opt-in+ * bbox: [number, number, number] | null, // [x, y, z] meters, post-gen fit+ * pose: 't' | 'a' | null, // requested rest pose, text-conditioned lanes only* hasOptions: boolean, // true iff any non-default option was supplied* errors: Array<{ field: string, message: string }>,* }}@@ -110,10 +125,13 @@ export function normalizeForgeOptions(body) {});}- // target_polycount — explicit geometry budget (poly-aware backends only). A- // `quality` alias maps coarse → fine for callers that prefer a word over a number.+ // target_polycount: explicit geometry budget (poly-aware backends only).+ // target_faces is an accepted alias for the same field (same validation,+ // same clamp); target_polycount wins if a caller sends both. A `quality`+ // alias maps coarse → fine for callers that prefer a word over a number.let targetPolycount = null;- let rawPoly = b.target_polycount;+ const polyField = b.target_polycount !== undefined && b.target_polycount !== null ? 'target_polycount' : 'target_faces';+ let rawPoly = b.target_polycount ?? b.target_faces;if ((rawPoly === undefined || rawPoly === null) && typeof b.quality === 'string') {const map = { low: 5_000, draft: 5_000, medium: 30_000, standard: 50_000, high: 150_000, ultra: 300_000 };const q = b.quality.toLowerCase().trim();@@ -124,8 +142,8 @@ export function normalizeForgeOptions(body) {const n = Number(rawPoly);if (!Number.isFinite(n) || !Number.isInteger(n) || n < POLYCOUNT_MIN || n > POLYCOUNT_MAX) {errors.push({- field: 'target_polycount',- message: `target_polycount must be an integer between ${POLYCOUNT_MIN} and ${POLYCOUNT_MAX}.`,+ field: polyField,+ message: `${polyField} must be an integer between ${POLYCOUNT_MIN} and ${POLYCOUNT_MAX}.`,});} else {targetPolycount = n;@@ -219,6 +237,40 @@ export function normalizeForgeOptions(body) {}}+ // bbox: [x, y, z] in meters. The delivered mesh is uniformly scaled to fit+ // inside this box (aspect ratio preserved, never stretched per-axis), then+ // centered on X/Z and floored at Y=0 (glb-bbox-fit.js). Lane-agnostic: it is+ // a post-generation step on the final GLB, so unlike target_polycount/pose+ // there is no backend that cannot honor it.+ let bbox = null;+ if (b.bbox !== undefined && b.bbox !== null) {+ if (!Array.isArray(b.bbox) || b.bbox.length !== 3) {+ errors.push({ field: 'bbox', message: 'bbox must be an array of 3 numbers [x, y, z] in meters.' });+ } else {+ const nums = b.bbox.map(Number);+ const bad = nums.some((n) => !Number.isFinite(n) || n < BBOX_MIN || n > BBOX_MAX);+ if (bad) {+ errors.push({+ field: 'bbox',+ message: `Each bbox dimension must be a number between ${BBOX_MIN} and ${BBOX_MAX} meters.`,+ });+ } else {+ bbox = nums;+ }+ }+ }++ // pose: requested rest pose for a humanoid/character subject. Only lanes+ // without a caller-supplied reference image can honor it (poseControl in+ // forge-tiers.js's BACKENDS); forge.js reports pose_applied so a caller+ // knows whether the request actually reached the generator as a directive.+ let pose = null;+ if (b.pose !== undefined && b.pose !== null && b.pose !== '') {+ const p = String(b.pose).toLowerCase().trim();+ if (POSE_VALUES.includes(p)) pose = p === 'none' ? null : p;+ else errors.push({ field: 'pose', message: `pose must be one of: ${POSE_VALUES.join(', ')}.` });+ }+const hasOptions =seed !== null ||outputFormat !== 'glb' ||@@ -229,7 +281,9 @@ export function normalizeForgeOptions(body) {fillOtherSides ||numParts !== null ||!derivePbr ||- lods;+ lods ||+ bbox !== null ||+ pose !== null;return {seed,@@ -243,6 +297,8 @@ export function normalizeForgeOptions(body) {numParts,derivePbr,lods,+ bbox,+ pose,hasOptions,errors,};@@ -264,21 +320,38 @@ export function providerReconstructParams(opts, { polyControl = false } = {}) {return out;}+// Re-usable pose directive text, appended to a text-conditioned generation+// prompt AFTER any art-director rewrite so it survives verbatim into the+// reference image / text-to-3d call. Kept here (not forge.js) so the wording+// stays next to the field's validation and the one place it is documented.+export function poseDirective(pose) {+ if (pose === 't') return 'standing in a neutral T-pose, arms held straight out to the sides, palms down';+ if (pose === 'a') return 'standing in a neutral A-pose, arms relaxed at a slight angle from the body';+ return null;+}+// Compact, response-safe echo of what the caller actually got — included in the// generation response so a client can confirm the seed used (for reproducibility)// and which format/resolution was applied.-export function summarizeForgeOptions(opts) {+// `poseApplied` is resolved by forge.js (it knows the chosen backend's+// poseControl flag; this module validates the field but has no backend+// context), null when the caller did not request a pose at all.+export function summarizeForgeOptions(opts, { poseApplied = null } = {}) {if (!opts) return {};return {seed: opts.seed,output_format: opts.outputFormat,texture_size: opts.textureSize,target_polycount: opts.targetPolycount,+ target_faces: opts.targetPolycount,resolution: opts.resolution ?? null,view_labels: opts.viewLabels ?? null,fill_other_sides: Boolean(opts.fillOtherSides),num_parts: opts.numParts ?? null,derive_pbr: opts.derivePbr !== false,lods: Boolean(opts.lods),+ bbox: opts.bbox ?? null,+ pose: opts.pose ?? null,+ ...(opts.pose !== null ? { pose_applied: Boolean(poseApplied) } : {}),};}diff --git a/api/_lib/forge-tiers.js b/api/_lib/forge-tiers.jsindex 79d42c39a..04f7bab63 100644--- a/api/_lib/forge-tiers.js+++ b/api/_lib/forge-tiers.js@@ -393,6 +393,12 @@ export const BACKENDS = Object.freeze({// Discoverable capability flag the catalog/UI read directly, rather than// hardcoding an "anigen" check outside this registry.rigged: true,+ // The rigging pass normalizes every output to AniGen's own trained rest+ // pose before it predicts the skeleton: a `pose` directive on the input+ // image has nothing left to influence by the time skinning runs, unlike+ // a plain mesh backend where the delivered geometry is just whatever the+ // reference image showed. The only backend where this is false.+ poseControl: false,baseEta: 90,// Cold-start budget for our own scale-to-zero worker: checkpoint copy +// pipeline load before the first inference.@@ -1008,6 +1014,12 @@ export function buildCatalog() {paths: b.paths,byok: b.byok || null,poly_control: b.polyControl,+ // True unless this specific backend re-normalizes its output pose+ // downstream of the prompt/reference image (see poseControlFor above).+ // A caller-supplied photo (image mode) still fixes the pose regardless+ // of this flag; that per-request outcome is echoed as pose_applied on+ // the generation response, not here.+ pose_control: b.poseControl !== false,free: Boolean(b.free),// False when the backend generates from text prompts only (NVIDIA's// hosted TRELLIS preview) — the UI must not offer it for photo input.@@ -1058,6 +1070,18 @@ export function buildCatalog() {};}+// Whether a `pose` request (api/_lib/forge-options.js) has any chance of+// reaching the delivered mesh on this backend. True for every backend except+// one (anigen): pose is a prompt-time directive (baked into the native+// text-to-geometry prompt or the synthesized reference image), so it can only+// be defeated by a backend that re-normalizes its output pose downstream of+// that image, not by the backend's input modality. Request-time factors+// (isImageMode: a caller-supplied photo already fixes the pose) are decided+// in forge.js, which is why this alone is not the full pose_applied answer.+export function poseControlFor(backendId) {+ return BACKENDS[backendId]?.poseControl !== false;+}+// Translate a resolved (path, tier) into the mesh-budget params the poly-aware// providers (Meshy/Tripo) accept. Backends without poly control ignore these.export function meshBudgetFor({ tier }) {diff --git a/api/_providers/meshy.js b/api/_providers/meshy.jsindex 3c6fb862a..cc8885f5d 100644--- a/api/_providers/meshy.js+++ b/api/_providers/meshy.js@@ -117,26 +117,30 @@ export function createMeshyProvider(apiKey) {return {// Native geometry-first: text → untextured mesh, no intermediate image.- async textToGeometry({ prompt, tier }) {+ // targetPolycount overrides the tier default when the caller sent an+ // explicit target_polycount/target_faces (forge-options.js); absent, the+ // tier's own budget applies exactly as before.+ async textToGeometry({ prompt, tier, targetPolycount }) {const taskId = await postTask(ENDPOINT['text-to-3d'], {mode: 'preview',prompt: String(prompt).slice(0, 600),ai_model: 'meshy-6',topology: 'triangle',- target_polycount: clampPoly(tier.polycount),+ target_polycount: clampPoly(targetPolycount ?? tier.polycount),should_remesh: true,target_formats: ['glb'],});return { kind: 'text-to-3d', taskId };},- // Single image → native geometry + textures, poly target from the tier.- async imageTo3d({ imageUrl, prompt, tier }) {+ // Single image → native geometry + textures, poly target from the tier+ // unless the caller overrides it explicitly.+ async imageTo3d({ imageUrl, prompt, tier, targetPolycount }) {const body = {image_url: imageUrl,ai_model: 'meshy-6',topology: 'triangle',- target_polycount: clampPoly(tier.polycount),+ target_polycount: clampPoly(targetPolycount ?? tier.polycount),should_remesh: true,should_texture: true,enable_pbr: Boolean(tier.pbr),diff --git a/api/_providers/rodin.js b/api/_providers/rodin.jsindex 80500b69c..4f5e917af 100644--- a/api/_providers/rodin.js+++ b/api/_providers/rodin.js@@ -121,21 +121,24 @@ export function createRodinProvider(apiKey) {}return {- // Native geometry-first: text → untextured quad mesh, no intermediate image.- async textToGeometry({ prompt, tier }) {+ // 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(tier.polycount)));+ 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.- async imageTo3d({ imageUrl, prompt, tier }) {+ // 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.@@ -160,7 +163,7 @@ export function createRodinProvider(apiKey) {form.set('mesh_mode', 'Quad');form.set('material', tier.pbr ? 'PBR' : 'Shaded');form.set('quality', qualityForTier(tier));- form.set('quality_override', String(clampPoly(tier.polycount)));+ form.set('quality_override', String(clampPoly(targetPolycount ?? tier.polycount)));form.set('geometry_file_format', 'glb');return submit(form);},diff --git a/api/_providers/tripo.js b/api/_providers/tripo.jsindex b1c49557a..39b2f0b90 100644--- a/api/_providers/tripo.js+++ b/api/_providers/tripo.js@@ -203,19 +203,21 @@ export function createTripoProvider(apiKey) {}return {- async textToGeometry({ prompt, tier }) {+ // 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({type: 'text_to_model',prompt: String(prompt).slice(0, 1024),model_version: modelVersion(),- face_limit: clampFaces(tier.polycount),+ face_limit: clampFaces(targetFaces ?? tier.polycount),texture: false,pbr: false,});return { kind: 'task', taskId };},- async imageTo3d({ imageUrl, tier }) {+ async imageTo3d({ imageUrl, tier, targetPolycount: targetFaces }) {// Data URI (selfie) → upload first and reference the token; a real// http(s) URL passes straight through as `file.url`.const parsed = parseImageDataUri(imageUrl);@@ -226,7 +228,7 @@ export function createTripoProvider(apiKey) {type: 'image_to_model',file,model_version: modelVersion(),- face_limit: clampFaces(tier.polycount),+ face_limit: clampFaces(targetFaces ?? tier.polycount),texture: true,pbr: Boolean(tier.pbr),});diff --git a/api/forge.js b/api/forge.jsindex 0a4864ae9..6f22c2a58 100644--- a/api/forge.js+++ b/api/forge.js@@ -85,6 +85,7 @@ import {isSelfHostImageLane,selfHostLaneName,nextSelfHostImageLane,+ poseControlFor,} from './_lib/forge-tiers.js';import {laneHealthSnapshot,@@ -138,7 +139,7 @@ import {import { markProviderCooldown, providersInCooldown } from './_lib/provider-health.js';import { acquireLock, releaseLock, cacheGet, cacheSet } from './_lib/cache.js';import { sanitizeJobError } from './_lib/provider-job-error.js';-import { normalizeForgeOptions, providerReconstructParams, summarizeForgeOptions } from './_lib/forge-options.js';+import { normalizeForgeOptions, providerReconstructParams, summarizeForgeOptions, poseDirective } from './_lib/forge-options.js';import { bindJobToOptions, optionsForJob } from './_lib/forge-job-options.js';import {forgeResultCacheKey,@@ -603,10 +604,17 @@ async function qualityGateFinalize({ tierId, prompt, path, backend, referenceIma// itself unavailable (so the caller can fall through to the next lane). Prompt// is required: NVCF is text-only; photo submissions never reach here.async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opts = null, cacheKey = null }) {+ // NVCF emits the mesh directly from text, no FLUX-synthesized reference+ // image exists for this lane, so a pose directive (if honorable at all,+ // see forge-tiers.js poseControlFor) has to be appended here rather than+ // relying on the image-intermediate injection in startJobWithBody.+ const poseText = opts?.pose && poseControlFor('nvidia') ? poseDirective(opts.pose) : null;+ const poseApplied = Boolean(poseText);+ const withPose = (p) => (poseText ? `${p}, ${poseText}` : p);let submitted;try {const nv = await loadNvidiaProvider();- submitted = await nv.textTo3d({ prompt, tier, seed: opts?.seed ?? undefined });+ submitted = await nv.textTo3d({ prompt: withPose(prompt), tier, seed: opts?.seed ?? undefined });} catch (err) {// A timed-out / unreachable / throttled / 5xx NIM lane is degraded, cool it// down so the next request skips the submit-timeout gamble and fails over@@ -673,7 +681,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optif (shouldRetryForQuality(durable?.quality)) {try {const nv = await loadNvidiaProvider();- const retry = await nv.textTo3d({ prompt, tier, seed: opts?.seed ?? undefined });+ const retry = await nv.textTo3d({ prompt: withPose(prompt), tier, seed: opts?.seed ?? undefined });if (!retry.taskId && retry.resultGlbUrl) {const retryJob = randomUUID().replace(/-/g, '');await createCreation({@@ -727,7 +735,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optregenerate: async ({ prompt: retryPrompt } = {}) => {const useP = retryPrompt || prompt;const nvr = await loadNvidiaProvider();- const r = await nvr.textTo3d({ prompt: useP, tier, seed: opts?.seed ?? undefined });+ const r = await nvr.textTo3d({ prompt: withPose(useP), tier, seed: opts?.seed ?? undefined });if (r.taskId || !r.resultGlbUrl) return null;const rj = randomUUID().replace(/-/g, '');await createCreation({@@ -770,7 +778,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optquality_retried: retried,quality_gate: qualityGate || undefined,compression: durable?.compression || null,- options: opts?.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,...provenance,});return true;@@ -805,7 +813,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optjob_id: token,creation_id: creationId,status: 'queued',- options: opts?.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,...provenance,});return true;@@ -868,6 +876,11 @@ async function runHfImageLane({directedPrompt = null,opts = null,cacheKey = null,+ // Whether a requested pose was already baked into the reference image this+ // lane is reconstructing from (decided once in startJobWithBody, before any+ // lane failover reassigned the backend); false on the image→3D path and on+ // a pose-incapable backend (forge-tiers.js poseControlFor).+ poseApplied = false,}) {// The Spaces chain runs Hunyuan3D, so the lane is closed to the EU, the UK,// South Korea and unknown countries. false means "could not serve" and every@@ -1096,7 +1109,7 @@ async function runHfImageLane({quality_retried: retried,quality_gate: qualityGate || undefined,compression: durable?.compression || null,- options: opts?.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,mode,path,tier: tier.id,@@ -1144,6 +1157,13 @@ async function startJobWithBody(req, res, body) {// before. An explicitly-present but invalid value is a 400 with an actionable// message; an absent field is never an error.const opts = normalizeForgeOptions(body);+ // True once a `pose` request actually reached a prompt that drives+ // generation (native text-to-geometry, or the synthesized reference image+ // for text→3D). Stays false for every image-mode request (the caller's own+ // photo already fixes the pose) and for a backend whose poseControl is+ // false (forge-tiers.js); summarizeForgeOptions echoes it as pose_applied+ // so a caller who asked for a pose can tell whether it actually took.+ let poseApplied = false;// Optional client-supplied trace id for the pre-submit progress channel. The// director pass and the reference-view synthesis both finish long before this// request can answer, so each records a crumb the page reads with a cheap poll@@ -1294,7 +1314,13 @@ async function startJobWithBody(req, res, body) {backend: cached.backend || backendId,prompt: prompt || null,quality: cached.quality || null,- options: opts.hasOptions ? summarizeForgeOptions(opts) : undefined,+ // Cache lookup runs before any lane failover, so `backendId` here is+ // still the originally requested lane; a hit only exists because a+ // prior run with this exact (pose included) cache key already+ // generated it under that same lane.+ options: opts.hasOptions+ ? summarizeForgeOptions(opts, { poseApplied: Boolean(opts.pose) && poseControlFor(backendId) })+ : undefined,});}}@@ -1733,15 +1759,24 @@ async function startJobWithBody(req, res, body) {let previewImageUrl = null;if (isImageMode) {// The native image→3D endpoints reconstruct from a single primary- // view; multi-view fusion stays on the image/TRELLIS path.+ // view; multi-view fusion stays on the image/TRELLIS path. The+ // caller's own photo already fixes the subject's pose, so `pose` is+ // never applied here regardless of this backend's poseControl.previewImageUrl = imageUrls[0];submitted = await gp.imageTo3d({imageUrl: previewImageUrl,prompt: prompt || undefined,tier,+ targetPolycount: opts.targetPolycount ?? undefined,});} else if (typeof gp.textToGeometry === 'function') {- submitted = await gp.textToGeometry({ prompt, tier });+ const poseText = opts.pose && poseControlFor(backendId) ? poseDirective(opts.pose) : null;+ if (poseText) poseApplied = true;+ submitted = await gp.textToGeometry({+ prompt: poseText ? `${prompt}, ${poseText}` : prompt,+ tier,+ targetPolycount: opts.targetPolycount ?? undefined,+ });} else {// Image-only backend (e.g. Stable Fast 3D) asked to run text→3D.return json(res, 422, {@@ -1793,7 +1828,7 @@ async function startJobWithBody(req, res, body) {durable: Boolean(durable),quality: durable?.quality || null,compression: durable?.compression || null,- options: opts.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,mode: isImageMode ? 'image_to_3d' : 'text_to_3d',path,tier: tier.id,@@ -2046,6 +2081,17 @@ async function startJobWithBody(req, res, body) {if (directed) promptForReference = directed;}}+ // Pose directive, appended AFTER the director rewrite so it survives+ // verbatim into the reference image. Baked into the synthesized image's+ // pixels, so it applies no matter which image-conditioned backend this+ // request ultimately lands on (including a later lane failover).+ if (opts.pose && poseControlFor(backendId)) {+ const poseText = poseDirective(opts.pose);+ if (poseText) {+ promptForReference = `${promptForReference}, ${poseText}`;+ poseApplied = true;+ }+ }// Report the rewrite only when it actually changed the brief, an// unchanged value means the model saw exactly what the user typed.if (promptForReference && promptForReference !== prompt) directedPrompt = promptForReference;@@ -2341,7 +2387,7 @@ async function startJobWithBody(req, res, body) {text_to_image_model: isImageMode ? null : textToImageModel,cold_start: cold,cold_start_seconds: cold ? coldStartSecondsFor(backendId) : undefined,- options: opts.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,eta_seconds: estimateEtaSeconds({ backendId, tier, cold }),estimated_credits: estimateCredits({ backendId, path, tier }),});@@ -2387,6 +2433,7 @@ async function startJobWithBody(req, res, body) {directedPrompt,opts,cacheKey,+ poseApplied,}))return;@@ -2434,6 +2481,7 @@ async function startJobWithBody(req, res, body) {directedPrompt,opts,cacheKey,+ poseApplied,}))return;@@ -2598,6 +2646,7 @@ async function startJobWithBody(req, res, body) {directedPrompt,opts,cacheKey,+ poseApplied,})) {return;@@ -2680,7 +2729,7 @@ async function startJobWithBody(req, res, body) {text_to_image_model: textToImageModel,cold_start: cold,cold_start_seconds: cold ? coldStartSecondsFor(backendId) : undefined,- options: opts.hasOptions ? summarizeForgeOptions(opts) : undefined,+ options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,eta_seconds: estimateEtaSeconds({ backendId, tier, cold }),estimated_credits: estimateCredits({ backendId, path, tier }),});diff --git a/tests/api/providers-meshy.test.js b/tests/api/providers-meshy.test.jsindex ee7350a62..1d95d830c 100644--- a/tests/api/providers-meshy.test.js+++ b/tests/api/providers-meshy.test.js@@ -50,6 +50,34 @@ describe('meshy provider: text→geometry submit', () => {expect(out).toEqual({ kind: 'text-to-3d', taskId: 'task-abc' });});+ it('honors an explicit targetPolycount override over the tier default', async () => {+ const bodies = [];+ globalThis.fetch = vi.fn(async (url, opts) => {+ bodies.push(JSON.parse(opts.body));+ return { ok: true, status: 200, json: async () => ({ result: 't' }) };+ });++ const provider = createMeshyProvider('msy_test');+ await provider.textToGeometry({ prompt: 'x', tier: TIER, targetPolycount: 80_000 });+ await provider.imageTo3d({ imageUrl: 'https://cdn.example.com/r.png', tier: TIER, targetPolycount: 80_000 });++ expect(bodies[0].target_polycount).toBe(80_000);+ expect(bodies[1].target_polycount).toBe(80_000);+ });++ it('still clamps an overridden targetPolycount into the accepted window', async () => {+ const bodies = [];+ globalThis.fetch = vi.fn(async (url, opts) => {+ bodies.push(JSON.parse(opts.body));+ return { ok: true, status: 200, json: async () => ({ result: 't' }) };+ });++ const provider = createMeshyProvider('msy_test');+ await provider.textToGeometry({ prompt: 'x', tier: TIER, targetPolycount: 5_000_000 });++ expect(bodies[0].target_polycount).toBe(300_000);+ });+it('clamps a tier poly budget into Meshy\'s accepted 100-300,000 window', async () => {const bodies = [];globalThis.fetch = vi.fn(async (url, opts) => {diff --git a/tests/api/providers-rodin.test.js b/tests/api/providers-rodin.test.jsnew file mode 100644index 000000000..7376f34bc--- /dev/null+++ b/tests/api/providers-rodin.test.js@@ -0,0 +1,119 @@+// Rodin (Hyper3D) BYOK provider (api/_providers/rodin.js): wire contract for+// the poly-budget override. Rodin's submit is multipart/form-data, so the+// target is read back off the posted FormData rather than a JSON body.+//+// global fetch is stubbed to model Rodin's real wire protocol (verified+// against their published API shapes); no network and no mocked product data.++import { describe, it, expect, vi, afterEach } from 'vitest';++// imageTo3d downloads the caller's reference image via fetchUpstreamPublic,+// which SSRF-checks the URL with a real DNS lookup (assertSafePublicUrl),+// irrelevant to the poly-budget override this file tests, and unreachable in+// a sandboxed test run. Stub just that one export; fetchUpstream (the submit+// call every test here actually exercises) stays real, driven by the+// global fetch mock, same as every other provider test in this suite.+vi.mock('../../api/_lib/upstream-fetch.js', async (importOriginal) => {+ const actual = await importOriginal();+ return {+ ...actual,+ fetchUpstreamPublic: vi.fn(async () => ({+ ok: true,+ status: 200,+ blob: async () => new Blob([new Uint8Array([1, 2, 3])]),+ })),+ };+});++import { createRodinProvider } from '../../api/_providers/rodin.js';++const ORIGINAL_FETCH = globalThis.fetch;+afterEach(() => {+ globalThis.fetch = ORIGINAL_FETCH;+ vi.restoreAllMocks();+});++const TIER = { id: 'standard', polycount: 30_000, pbr: false };++describe('rodin provider: construction', () => {+ it('refuses to construct without an API key', () => {+ expect(() => createRodinProvider('')).toThrowError(/key is required/i);+ });+});++describe('rodin provider: text→geometry poly override', () => {+ it('honors an explicit targetPolycount over the tier default', async () => {+ let form;+ globalThis.fetch = vi.fn(async (url, opts) => {+ form = opts.body;+ return {+ ok: true,+ status: 200,+ json: async () => ({ uuid: 'task-uuid', jobs: { subscription_key: 'sub-key' } }),+ };+ });++ const provider = createRodinProvider('rodin_test');+ const out = await provider.textToGeometry({ prompt: 'a brass telescope', tier: TIER, targetPolycount: 95_000 });++ expect(form.get('quality_override')).toBe('95000');+ expect(out).toEqual({ kind: 'sub-key', taskId: 'task-uuid' });+ });++ it('falls back to the tier polycount when no override is supplied', async () => {+ let form;+ globalThis.fetch = vi.fn(async (url, opts) => {+ form = opts.body;+ return {+ ok: true,+ status: 200,+ json: async () => ({ uuid: 'task-uuid', jobs: { subscription_key: 'sub-key' } }),+ };+ });++ const provider = createRodinProvider('rodin_test');+ await provider.textToGeometry({ prompt: 'x', tier: TIER });++ expect(form.get('quality_override')).toBe('30000');+ });++ it('clamps an overridden targetPolycount into Rodin\'s accepted 1,000-200,000 window', async () => {+ let form;+ globalThis.fetch = vi.fn(async (url, opts) => {+ form = opts.body;+ return {+ ok: true,+ status: 200,+ json: async () => ({ uuid: 'task-uuid', jobs: { subscription_key: 'sub-key' } }),+ };+ });++ const provider = createRodinProvider('rodin_test');+ await provider.textToGeometry({ prompt: 'x', tier: TIER, targetPolycount: 5_000_000 });++ expect(form.get('quality_override')).toBe('200000');+ });+});++describe('rodin provider: image→3D poly override', () => {+ it('honors targetPolycount on the image path too', async () => {+ let capturedForm;+ globalThis.fetch = vi.fn(async (url, opts) => {+ capturedForm = opts.body;+ return {+ ok: true,+ status: 200,+ json: async () => ({ uuid: 'img-uuid', jobs: { subscription_key: 'img-sub' } }),+ };+ });++ const provider = createRodinProvider('rodin_test');+ await provider.imageTo3d({+ imageUrl: 'https://cdn.example.com/reference.png',+ tier: { ...TIER, pbr: true },+ targetPolycount: 40_000,+ });++ expect(capturedForm.get('quality_override')).toBe('40000');+ });+});diff --git a/tests/forge-options.test.js b/tests/forge-options.test.jsindex 972325194..5e3f5e7e4 100644--- a/tests/forge-options.test.js+++ b/tests/forge-options.test.js@@ -3,8 +3,10 @@ import {normalizeForgeOptions,providerReconstructParams,summarizeForgeOptions,+ poseDirective,OUTPUT_FORMATS,TEXTURE_SIZES,+ POSE_VALUES,} from '../api/_lib/forge-options.js';describe('normalizeForgeOptions — backward compatibility', () => {@@ -104,6 +106,68 @@ describe('normalizeForgeOptions — texture size & polycount', () => {target_polycount: 40_000,});});++ it('accepts target_faces as an alias for target_polycount', () => {+ expect(normalizeForgeOptions({ target_faces: 40_000 }).targetPolycount).toBe(40_000);+ expect(normalizeForgeOptions({ target_faces: 5 }).errors[0].field).toBe('target_faces');+ expect(normalizeForgeOptions({ target_faces: 9_000_000 }).errors[0].field).toBe('target_faces');+ });++ it('prefers target_polycount when both target_polycount and target_faces are sent', () => {+ const o = normalizeForgeOptions({ target_polycount: 10_000, target_faces: 90_000 });+ expect(o.targetPolycount).toBe(10_000);+ });+});++describe('normalizeForgeOptions: bbox', () => {+ it('accepts a valid [x, y, z] bbox in meters', () => {+ const o = normalizeForgeOptions({ bbox: [1, 2, 0.5] });+ expect(o.bbox).toEqual([1, 2, 0.5]);+ expect(o.hasOptions).toBe(true);+ });++ it('defaults bbox to null when omitted', () => {+ expect(normalizeForgeOptions({}).bbox).toBeNull();+ });++ it('rejects a bbox that is not a 3-element array', () => {+ expect(normalizeForgeOptions({ bbox: [1, 2] }).errors[0].field).toBe('bbox');+ expect(normalizeForgeOptions({ bbox: 'big' }).errors[0].field).toBe('bbox');+ });++ it('rejects a bbox dimension outside the sane meter range', () => {+ expect(normalizeForgeOptions({ bbox: [0, 1, 1] }).errors[0].field).toBe('bbox');+ expect(normalizeForgeOptions({ bbox: [1, 1, 999] }).errors[0].field).toBe('bbox');+ expect(normalizeForgeOptions({ bbox: [1, 'x', 1] }).errors[0].field).toBe('bbox');+ });+});++describe('normalizeForgeOptions: pose', () => {+ it('accepts t and a, and treats none as no directive', () => {+ expect(normalizeForgeOptions({ pose: 't' }).pose).toBe('t');+ expect(normalizeForgeOptions({ pose: 'a' }).pose).toBe('a');+ expect(normalizeForgeOptions({ pose: 'none' }).pose).toBeNull();+ expect(normalizeForgeOptions({ pose: 'none' }).hasOptions).toBe(false);+ });++ it('is case-insensitive and defaults to null when omitted', () => {+ expect(normalizeForgeOptions({ pose: 'T' }).pose).toBe('t');+ expect(normalizeForgeOptions({}).pose).toBeNull();+ });++ it('rejects an unknown pose value', () => {+ expect(normalizeForgeOptions({ pose: 'sitting' }).errors[0].field).toBe('pose');+ });++ it('all advertised pose values validate or clear to null', () => {+ for (const p of POSE_VALUES) expect(normalizeForgeOptions({ pose: p }).errors).toEqual([]);+ });++ it('poseDirective returns pose-specific text for t/a and null otherwise', () => {+ expect(poseDirective('t')).toMatch(/T-pose/);+ expect(poseDirective('a')).toMatch(/A-pose/);+ expect(poseDirective(null)).toBeNull();+ });});describe('normalizeForgeOptions: view_labels & fill_other_sides', () => {@@ -182,6 +246,7 @@ describe('summarizeForgeOptions', () => {output_format: 'glb-draco',texture_size: 1024,target_polycount: null,+ target_faces: null,resolution: null,view_labels: null,fill_other_sides: false,@@ -190,9 +255,34 @@ describe('summarizeForgeOptions', () => {// says so, so a client can tell why its delivered file carries maps.derive_pbr: true,lods: false,+ bbox: null,+ pose: null,});});+ it('echoes target_faces as the same resolved value as target_polycount', () => {+ const o = normalizeForgeOptions({ target_faces: 40_000 });+ const s = summarizeForgeOptions(o);+ expect(s.target_polycount).toBe(40_000);+ expect(s.target_faces).toBe(40_000);+ });++ it('echoes bbox when supplied', () => {+ const o = normalizeForgeOptions({ bbox: [1, 2, 1] });+ expect(summarizeForgeOptions(o).bbox).toEqual([1, 2, 1]);+ });++ it('echoes pose and pose_applied only when pose was requested', () => {+ const requested = normalizeForgeOptions({ pose: 't' });+ expect(summarizeForgeOptions(requested, { poseApplied: true })).toMatchObject({ pose: 't', pose_applied: true });+ expect(summarizeForgeOptions(requested, { poseApplied: false })).toMatchObject({ pose: 't', pose_applied: false });++ const notRequested = normalizeForgeOptions({});+ const s = summarizeForgeOptions(notRequested, { poseApplied: true });+ expect(s.pose).toBeNull();+ expect(s).not.toHaveProperty('pose_applied');+ });+it('echoes lods when requested', () => {const o = normalizeForgeOptions({ lods: true });expect(summarizeForgeOptions(o).lods).toBe(true);diff --git a/tests/tripo-provider.test.js b/tests/tripo-provider.test.jsindex f764661ad..afb3b4f2e 100644--- a/tests/tripo-provider.test.js+++ b/tests/tripo-provider.test.js@@ -80,6 +80,40 @@ describe('createTripoProvider.imageTo3d — input routing', () => {expect(taskBody.file).toEqual({ type: 'png', url: 'https://cdn.example.com/selfie.png' });});+ it('honors an explicit targetPolycount override over the tier default face_limit', async () => {+ fetchMock.mockResolvedValueOnce(jsonResponse(200, { code: 0, data: { task_id: 'task-override' } }));++ const provider = createTripoProvider(KEY);+ await provider.textToGeometry({ prompt: 'a brass telescope', tier: { polycount: 30000 }, targetPolycount: 90_000 });++ const taskBody = JSON.parse(fetchMock.mock.calls[0][1].body);+ expect(taskBody.face_limit).toBe(90_000);+ });++ it('falls back to the tier polycount when no override is supplied', async () => {+ fetchMock.mockResolvedValueOnce(jsonResponse(200, { code: 0, data: { task_id: 'task-default' } }));++ const provider = createTripoProvider(KEY);+ await provider.textToGeometry({ prompt: 'a brass telescope', tier: { polycount: 30000 } });++ const taskBody = JSON.parse(fetchMock.mock.calls[0][1].body);+ expect(taskBody.face_limit).toBe(30000);+ });++ it('honors targetPolycount on the image_to_model path too', async () => {+ fetchMock.mockResolvedValueOnce(jsonResponse(200, { code: 0, data: { task_id: 'task-img-override' } }));++ const provider = createTripoProvider(KEY);+ await provider.imageTo3d({+ imageUrl: 'https://cdn.example.com/selfie.png',+ tier: { polycount: 30000, pbr: true },+ targetPolycount: 60_000,+ });++ const taskBody = JSON.parse(fetchMock.mock.calls[0][1].body);+ expect(taskBody.face_limit).toBe(60_000);+ });+it('maps an upload auth failure to invalid_key (401) and never submits a task', async () => {fetchMock.mockResolvedValueOnce(jsonResponse(401, { code: 1001, message: 'bad key' }));