Skip to content

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.

feat(forge): add target_faces, bbox, and pose generation controls

nirholasfa02fa82d184
diff --git a/api/_lib/forge-options.js b/api/_lib/forge-options.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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, opt
if (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, opt
regenerate: 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, opt
quality_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, opt
job_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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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' }));