tripo-cli 0.1.0

package/dist/knowledge/chains.js

@@ -0,0 +1,157 @@
+/**
+ * Task-chain legality — which processing step may consume which upstream task.
+ * Mirrors server-side handler constraints; violations are rejected locally
+ * before any credits are spent.
+ */
+/** Task types that produce a downloadable 3D model. */
+export const MODEL_PRODUCING_TYPES = new Set([
+    'text_to_model',
+    'image_to_model',
+    'multiview_to_model',
+    'refine_model',
+    'texture_model',
+    'stylize_model',
+    'convert_model',
+    'import_model',
+    'highpoly_to_lowpoly',
+    'mesh_segmentation',
+    'mesh_completion',
+    'animate_rig',
+    'animate_retarget',
+]);
+export const STEPS = [
+    { name: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false },
+    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'stylize', endpoint: '/v3/models/stylize', produces: 'stylize_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true },
+    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true },
+    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'] },
+    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true },
+    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'] },
+    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true },
+    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false },
+    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'] },
+    // smartsegment's `input` is file_token/URL only (the server does not resolve
+    // task ids here), so it cannot chain after a task. Type is refined to
+    // smartsegment_image|smartsegment_model at request-build time per seg_type.
+    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smartsegment_model', accepts: [], acceptsFile: true },
+];
+const stepIndex = new Map();
+for (const s of STEPS) {
+    stepIndex.set(s.name, s);
+    for (const a of s.aliases ?? [])
+        stepIndex.set(a, s);
+}
+export function getStep(name) {
+    return stepIndex.get(name);
+}
+/**
+ * Parse a --then expression: "texture,rig,convert:fbx" or
+ * "convert:format=fbx,texture_size=2048". A bare value after ":" is sugar for
+ * the step's primary argument (convert→format, retarget→animation,
+ * stylize→style, decimate→face_limit).
+ */
+export function parseThenExpression(expr) {
+    const out = [];
+    // Split on commas that are not inside a step's arg list (args use "=", so a
+    // comma always separates either steps or key=value pairs; a segment with "="
+    // and no known step prefix belongs to the previous step).
+    const rawParts = expr.split(',').map((p) => p.trim()).filter(Boolean);
+    for (const part of rawParts) {
+        const [head, ...rest] = part.split(':');
+        const stepName = (head ?? '').trim().toLowerCase();
+        const def = getStep(stepName);
+        if (!def) {
+            if (part.includes('=') && out.length > 0) {
+                // continuation of previous step's args: "k=v"
+                const prev = out[out.length - 1];
+                applyArg(prev.args, part);
+                continue;
+            }
+            throw new ChainError(`unknown step "${stepName}" (valid: ${STEPS.map((s) => s.name).join(', ')})`);
+        }
+        const args = {};
+        const argStr = rest.join(':').trim();
+        if (argStr) {
+            for (const token of argStr.split(/[,;]/).map((t) => t.trim()).filter(Boolean)) {
+                if (token.includes('='))
+                    applyArg(args, token);
+                else
+                    applyPrimaryArg(def.name, args, token);
+            }
+        }
+        out.push({ step: def.name, args });
+    }
+    return out;
+}
+function applyArg(args, token) {
+    const eq = token.indexOf('=');
+    const key = token.slice(0, eq).trim();
+    const raw = token.slice(eq + 1).trim();
+    args[key] = coerce(raw);
+}
+function applyPrimaryArg(step, args, value) {
+    const primary = {
+        convert: 'format',
+        retarget: 'animation',
+        stylize: 'style',
+        decimate: 'face_limit',
+        texture: 'texture_quality',
+        rig: 'rig_type',
+        segment: 'model',
+        smartsegment: 'granularity',
+    };
+    const key = primary[step];
+    if (!key)
+        throw new ChainError(`step "${step}" does not take a bare argument ("${value}")`);
+    args[key] = coerce(value);
+}
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+$/.test(raw))
+        return Number(raw);
+    if (/^-?\d*\.\d+$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+export class ChainError extends Error {
+}
+/**
+ * Validate that a chain is legal given the type of the first (source) task.
+ * Returns the list of task types the chain will produce, in order.
+ */
+export function validateChain(chain, sourceType) {
+    let currentType = sourceType;
+    const produced = [];
+    for (const { step } of chain) {
+        const def = getStep(step);
+        if (!def)
+            throw new ChainError(`unknown step "${step}"`);
+        if (def.accepts === 'any-model') {
+            if (!MODEL_PRODUCING_TYPES.has(currentType)) {
+                throw new ChainError(`step "${def.name}" needs a model-producing upstream task, but the previous step produces "${currentType}"`);
+            }
+        }
+        else if (!def.accepts.includes(currentType)) {
+            throw new ChainError(def.accepts.length === 0
+                ? `step "${def.name}" takes a file/URL input only and cannot follow another task in a chain`
+                : `step "${def.name}" only accepts ${def.accepts.join('/')} tasks, but the previous step produces "${currentType}"` +
+                    hintFor(def.name));
+        }
+        if (!def.passthrough)
+            currentType = def.produces;
+        produced.push(def.produces);
+    }
+    return produced;
+}
+function hintFor(step) {
+    const hints = {
+        refine: ' (refine only accepts a successful text-to-model task)',
+        complete: ' (run "segment" first: complete only accepts mesh segmentation tasks)',
+        retarget: ' (run "rig" first: retarget only accepts rigged tasks)',
+    };
+    return hints[step] ?? '';
+}

package/dist/knowledge/error-catalog.js

@@ -0,0 +1,91 @@
+/**
+ * V3 error-code catalog: human translations (zh/en), retryability, and the
+ * CLI exit code each error maps to.
+ *
+ * Source of truth: backend ErrorCode enum (platform-common .../error/ErrorCode.java,
+ * itself aligned with openapi-server errors.gen.go). Note the public docs page
+ * is stale for 1000/1001 — the server actually sends 1002 for auth failures;
+ * 1000/1001 are 5xx server-side errors.
+ */
+export const EXIT = {
+    OK: 0,
+    FATAL: 1,
+    USAGE: 2,
+    AUTH: 3,
+    BALANCE: 4,
+    CONTENT_POLICY: 5,
+    TASK_FAILED: 6,
+    NETWORK: 7,
+    NOT_FOUND: 8,
+    RATE_LIMIT: 9,
+};
+export const ERROR_CATALOG = [
+    { code: 1000, zh: '服务端未知错误,请携带 request_id 联系支持', en: 'Unknown server-side error; contact support with the request id', retryable: true, exitCode: EXIT.NETWORK },
+    { code: 1001, zh: '服务端严重错误,请携带 request_id 联系支持', en: 'Fatal server-side error; contact support with the request id', retryable: false, exitCode: EXIT.NETWORK },
+    { code: 1002, zh: '认证失败:API Key 无效或区域不匹配(国内 Key 打了海外 API?),运行 tripo doctor 自动诊断', en: 'Authentication failed: invalid key or wrong region (cn key against the ov API?) — run "tripo doctor" to auto-diagnose', retryable: false, exitCode: EXIT.AUTH },
+    { code: 1003, zh: '请求体格式不合法', en: 'The request body is malformed', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1004, zh: '一个或多个参数不合法,请对照文档检查', en: 'One or more parameters are invalid (check the docs)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1005, zh: '无权访问该资源,请检查账号权限', en: 'Not allowed to access this resource (check permissions)', retryable: false, exitCode: EXIT.AUTH },
+    { code: 1007, zh: '请求过于频繁,触发全局速率限制', en: 'Rate limit exceeded — too many requests in a short time', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2000, zh: '触发生成并发上限,同系列任务共享并发池', en: 'Generation concurrency limit hit (task families share a pool)', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2001, zh: '任务不存在(确认任务属于当前 Key、区域正确)', en: 'Task not found (same key that created it? right region?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2002, zh: '该任务类型不受支持', en: 'This task type is not supported', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2003, zh: '输入图片文件为空,请检查文件是否损坏', en: 'The image file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2004, zh: '不支持的图片文件类型', en: 'Unsupported image file type', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2005, zh: 'draft 任务不是成功状态,请用成功的任务重试', en: 'The draft task is not a success; retry with a successful one', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2006, zh: '上游任务类型不受支持,请检查任务链', en: 'The original task type is not supported for this operation', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2007, zh: '上游任务不是成功状态', en: 'The original task has not succeeded', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2008, zh: '输入违反内容政策,请更换输入', en: 'Input violates the content policy; change the input', retryable: false, exitCode: EXIT.CONTENT_POLICY },
+    { code: 2009, zh: 'prompt 含有非法字符,请修改后重试', en: 'The prompt contains invalid characters', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2010, zh: '积分不足', en: 'Insufficient credits', retryable: false, exitCode: EXIT.BALANCE },
+    { code: 2011, zh: 'rig-check 的输入任务没有模型产物', en: 'The rig-check input task has no model output', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2012, zh: 'retarget 只接受 rig 任务作为输入', en: 'retarget only accepts a rig task as input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2013, zh: 'priority 取值无效(更高优先级需联系支持)', en: 'Invalid priority (contact support for higher priority)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2014, zh: '内容审核过程出错,请联系支持', en: 'Error occurred during content auditing; contact support', retryable: false, exitCode: EXIT.FATAL },
+    { code: 2015, zh: '模型版本已弃用,请升级 model 参数', en: 'Model version deprecated; upgrade the model parameter', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2016, zh: '该请求类型已弃用,请改用其他类型', en: 'This request type is deprecated; use an alternative', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2017, zh: 'model 版本取值无效', en: 'The model version value is invalid', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2018, zh: '模型太复杂无法重网格化,降低 face_limit 或简化输入', en: 'Model too complex to remesh; lower face_limit or simplify input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2019, zh: '文件不存在,请确认上传是否成功、file_token 是否过期', en: 'File not found (upload succeeded? token expired?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2020, zh: '图片 URL 无效,请确认可公开访问', en: 'The image URL is invalid (must be publicly reachable)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2021, zh: '文件大小超过上限,请压缩后重试', en: 'File size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2022, zh: '图片尺寸超过上限,请缩小后重试', en: 'Image size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 4001, zh: '请求的接口不存在,请检查 API 路径', en: 'The requested endpoint does not exist (check the API path)', retryable: false, exitCode: EXIT.NOT_FOUND },
+];
+const byCode = new Map(ERROR_CATALOG.map((e) => [e.code, e]));
+export function lookupError(code) {
+    return byCode.get(code);
+}
+/** Map an API error code + HTTP status to a stable CLI exit code. */
+export function exitCodeFor(apiCode, httpStatus) {
+    if (apiCode !== undefined) {
+        const info = byCode.get(apiCode);
+        if (info)
+            return info.exitCode;
+    }
+    if (httpStatus === 401)
+        return EXIT.AUTH;
+    if (httpStatus === 403)
+        return EXIT.AUTH;
+    if (httpStatus === 404)
+        return EXIT.NOT_FOUND;
+    if (httpStatus === 429)
+        return EXIT.RATE_LIMIT;
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return EXIT.NETWORK;
+    if (httpStatus !== undefined && httpStatus >= 400)
+        return EXIT.USAGE;
+    return EXIT.FATAL;
+}
+export function isRetryable(apiCode, httpStatus) {
+    if (apiCode !== undefined) {
+        const info = byCode.get(apiCode);
+        if (info)
+            return info.retryable;
+    }
+    if (httpStatus === 429)
+        return true;
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return true;
+    return false;
+}

package/dist/knowledge/models.js

@@ -0,0 +1,158 @@
+/**
+ * Dual-model strategy — the single source of truth for 3D model selection.
+ *
+ * Rule (one branch, no exceptions): explicit low-poly intent or a face budget
+ * <= 20000 selects P1; everything else selects v3.1. Explicit --model wins but
+ * still goes through constraint validation.
+ */
+/**
+ * Wire values are what the server actually accepts (backend whitelist:
+ * v3.1-20260211, v3.0-20250812, v2.5-20250123, P1-20260311). The friendly
+ * `tripo-*` names from marketing docs are CLI-side aliases only — sending
+ * them raw returns 400 "invalid model".
+ */
+export const MODEL_V31 = 'v3.1-20260211';
+export const MODEL_P1 = 'P1-20260311';
+/** User-facing aliases normalized to the wire values above. */
+export const MODEL_ALIASES = {
+    'v3.1': MODEL_V31,
+    'v3.1-20260211': MODEL_V31,
+    'tripo-v3.1': MODEL_V31,
+    p1: MODEL_P1,
+    P1: MODEL_P1,
+    'P1-20260311': MODEL_P1,
+    'tripo-p1': MODEL_P1,
+    // Older whitelisted versions, alias → wire.
+    'v3.0': 'v3.0-20250812',
+    'tripo-v3.0': 'v3.0-20250812',
+    'v2.5': 'v2.5-20250123',
+    'tripo-v2.5': 'v2.5-20250123',
+};
+/** Older versions still on the server whitelist (explicit --model only). */
+export const LEGACY_3D_MODELS = ['v3.0-20250812', 'v2.5-20250123'];
+/** CN backend enforces min 50 (OV historically 48); 50 is safe in both regions. */
+export const P1_FACE_LIMIT = { min: 50, max: 20000 };
+/** Parameters the server rejects for P1 — stripped locally with a warning. */
+export const P1_FORBIDDEN_PARAMS = [
+    'quad',
+    'smart_low_poly',
+    'generate_parts',
+    'geometry_quality',
+];
+/** Rig wire versions (backend whitelist; marketing names rig-v1.0/rig-v2.0 are rejected). */
+export const RIG_MODEL_V1 = 'v1.0-20240301';
+export const RIG_MODEL_V25 = 'v2.5-20260210';
+/** Marketing rig names → wire versions the server actually accepts. */
+export const RIG_MODEL_ALIASES = {
+    'rig-v1.0': RIG_MODEL_V1,
+    'v1.0-20240301': RIG_MODEL_V1,
+    'rig-v2.0': RIG_MODEL_V25,
+    'rig-v2.5': RIG_MODEL_V25,
+    'v2.5-20260210': RIG_MODEL_V25,
+};
+export function normalizeRigModel(input) {
+    return RIG_MODEL_ALIASES[input] ?? input;
+}
+/** Default versions for non-generation capabilities. */
+export const CAPABILITY_DEFAULTS = {
+    texture: 'v3.0-20250812',
+    /** Server default is v1.0 (biped-only presets); the CLI defaults to the
+     *  v2.5 rig which has presets for all seven body types. */
+    rig: RIG_MODEL_V25,
+    segment: 'v1.0-20250506',
+    textToImage: 'seedream_v4',
+    imageToImage: 'seedream_v5',
+};
+export const RIG_TYPES = [
+    'biped',
+    'quadruped',
+    'hexapod',
+    'octopod',
+    'avian',
+    'serpentine',
+    'aquatic',
+];
+export const RIG_SPECS = ['tripo', 'mixamo'];
+/** Per-endpoint image model whitelists (ImageGenerationValidation):
+ *  image-to-image does NOT accept seedream_v4. */
+export const TEXT_TO_IMAGE_MODELS = [
+    'seedream_v4',
+    'seedream_v5',
+    'banana',
+    'banana_pro',
+    'banana2',
+    'chat_image_1',
+    'chat_image_1.5',
+    'chat_image_2',
+];
+export const IMAGE_TO_IMAGE_MODELS = [
+    'seedream_v5',
+    'banana',
+    'banana_pro',
+    'banana2',
+    'chat_image_1',
+    'chat_image_1.5',
+    'chat_image_2',
+];
+/** texture_model whitelist (ModelPostProcessValidation.ALLOWED_TEXTURE_MODELS). */
+export const TEXTURE_MODELS = ['v3.0-20250812', 'v2.5-20250123'];
+/** mesh_segmentation whitelist (ALLOWED_SEGMENT_MODELS). */
+export const SEGMENT_MODELS = ['v1.0-20250506', 'v2.0-20260430'];
+/** mesh/decimate whitelist (ALLOWED_DECIMATE_MODELS; blank/"default" → server default v2.0). */
+export const DECIMATE_MODELS = ['v2.0', 'v1.0'];
+/** Server whitelists differ per endpoint (ImageGenerationValidation). */
+export const TEXT_TO_IMAGE_TEMPLATES = [
+    'asset_extraction',
+    'character_completion',
+    't_pose',
+    'variants',
+    'figure',
+];
+export const IMAGE_TO_IMAGE_TEMPLATES = [
+    't_pose',
+    'character_completion',
+    '3d_enhance',
+    'variants',
+    'figure',
+];
+export const CONVERT_FORMATS = ['GLTF', 'USDZ', 'FBX', 'OBJ', 'STL', '3MF'];
+export const TEXTURE_FORMATS = [
+    'BMP',
+    'DPX',
+    'HDR',
+    'JPEG',
+    'OPEN_EXR',
+    'PNG',
+    'TARGA',
+    'TIFF',
+    'WEBP',
+];
+export const FBX_PRESETS = ['blender', '3dsmax', 'mixamo'];
+export const EXPORT_ORIENTATIONS = ['+x', '-x', '+y', '-y'];
+export const STYLIZE_STYLES = ['lego', 'voxel', 'voronoi', 'minecraft'];
+export const TEXTURE_QUALITIES = ['standard', 'detailed', 'extreme'];
+/** Normalize any accepted alias to the canonical wire value; unknown values pass through. */
+export function normalizeModel(input) {
+    return MODEL_ALIASES[input] ?? input;
+}
+export function isP1(model) {
+    return normalizeModel(model) === MODEL_P1;
+}
+/** The one rule. Returns the model plus a human-readable reason. */
+export function chooseModel(intent) {
+    if (intent.explicit) {
+        return { model: normalizeModel(intent.explicit), reason: 'explicit --model' };
+    }
+    if (intent.lowPoly) {
+        return { model: MODEL_P1, reason: 'low-poly intent → P1' };
+    }
+    if (intent.faceLimit !== undefined && intent.faceLimit <= P1_FACE_LIMIT.max) {
+        return { model: MODEL_P1, reason: `face budget ${intent.faceLimit} ≤ ${P1_FACE_LIMIT.max} → P1` };
+    }
+    return { model: MODEL_V31, reason: 'default high-fidelity → v3.1' };
+}
+/** Keywords that signal low-poly intent in a prompt (used by make/ai). */
+const LOW_POLY_HINTS = [/low[\s_-]?poly/i, /低模/, /低面/, /手游/, /voxel/i, /像素风/];
+export function detectLowPolyIntent(text) {
+    return LOW_POLY_HINTS.some((re) => re.test(text));
+}

package/dist/knowledge/params.js

@@ -0,0 +1,203 @@
+/**
+ * Parameter linkage rules distilled from server-side validation
+ * (TextImageModelValidation / ModelPostProcessValidation / handlers).
+ *
+ * Every rule here prevents a guaranteed 400 or a silently wasted credit.
+ * Rules marked [hard] mirror server enforcement; [soft] are CLI smart defaults.
+ */
+import { CONVERT_FORMATS, EXPORT_ORIENTATIONS, FBX_PRESETS, P1_FACE_LIMIT, P1_FORBIDDEN_PARAMS, TEXTURE_FORMATS, TEXTURE_QUALITIES, isP1, } from './models.js';
+const PROMPT_MAX = 1024;
+const NEGATIVE_PROMPT_MAX = 255;
+/** Validate + auto-fix parameters for 3D generation (text/image/multiview-to-model). */
+export function validateGenerationParams(model, input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    if (typeof params.prompt === 'string' && params.prompt.length > PROMPT_MAX) {
+        errors.push(`prompt exceeds ${PROMPT_MAX} characters (${params.prompt.length})`);
+    }
+    if (typeof params.negative_prompt === 'string' && params.negative_prompt.length > NEGATIVE_PROMPT_MAX) {
+        errors.push(`negative_prompt exceeds ${NEGATIVE_PROMPT_MAX} characters`);
+    }
+    // [hard] pbr=true forces texture=true (PBR is a superset of texturing).
+    if (params.pbr === true && params.texture === false) {
+        params.texture = true;
+        warnings.push('pbr=true forces texture=true (adjusted)');
+    }
+    // [hard] generate_parts outputs bare geometry: texture/pbr/quad must be off.
+    if (params.generate_parts === true) {
+        for (const key of ['texture', 'pbr', 'quad']) {
+            if (params[key] === true) {
+                params[key] = false;
+                warnings.push(`generate_parts=true disables ${key} (adjusted; run "tripo model texture" afterwards)`);
+            }
+        }
+    }
+    // [hard] P1 constraints: strip forbidden params, enforce face_limit range.
+    if (isP1(model)) {
+        for (const key of P1_FORBIDDEN_PARAMS) {
+            if (params[key] !== undefined) {
+                delete params[key];
+                warnings.push(`P1 does not support ${key} (removed)`);
+            }
+        }
+        const face = params.face_limit;
+        if (typeof face === 'number') {
+            if (face < P1_FACE_LIMIT.min || face > P1_FACE_LIMIT.max) {
+                errors.push(`P1 face_limit must be within ${P1_FACE_LIMIT.min}–${P1_FACE_LIMIT.max} (got ${face}); ` +
+                    `use tripo-v3.1 for higher budgets`);
+            }
+        }
+    }
+    else {
+        // [hard] smart_low_poly face_limit windows: 500–20000 tri / 500–10000 quad.
+        if (params.smart_low_poly === true && typeof params.face_limit === 'number') {
+            const max = params.quad === true ? 10000 : 20000;
+            if (params.face_limit < 500 || params.face_limit > max) {
+                errors.push(`smart_low_poly requires face_limit 500–${max}${params.quad === true ? ' (quad halves the budget)' : ''}`);
+            }
+        }
+    }
+    if (params.texture_quality !== undefined &&
+        !TEXTURE_QUALITIES.includes(params.texture_quality)) {
+        errors.push(`texture_quality must be one of ${TEXTURE_QUALITIES.join('/')}`);
+    }
+    // [hard] quad topology cannot be stored in GLB → output will be FBX.
+    if (params.quad === true) {
+        warnings.push('quad=true forces FBX output (quad topology cannot be stored in GLB)');
+    }
+    return { params, warnings, errors };
+}
+/** Validate parameters for models/convert. */
+export function validateConvertParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const format = typeof params.format === 'string' ? params.format.toUpperCase() : undefined;
+    if (!format) {
+        errors.push(`convert requires format (${CONVERT_FORMATS.join('/')})`);
+    }
+    else if (!CONVERT_FORMATS.includes(format)) {
+        errors.push(`unsupported format "${params.format}" (${CONVERT_FORMATS.join('/')})`);
+    }
+    else {
+        params.format = format;
+    }
+    // [hard] quad topology cannot live in GLTF/GLB.
+    if (params.quad === true && format === 'GLTF') {
+        errors.push('quad=true cannot export GLTF (quad topology is not storable in glTF); use FBX/OBJ/USDZ');
+    }
+    if (params.force_symmetry === true && params.quad !== true) {
+        delete params.force_symmetry;
+        warnings.push('force_symmetry only applies with quad=true (removed)');
+    }
+    if (params.texture_format !== undefined &&
+        !TEXTURE_FORMATS.includes(String(params.texture_format).toUpperCase())) {
+        errors.push(`texture_format must be one of ${TEXTURE_FORMATS.join('/')}`);
+    }
+    else if (typeof params.texture_format === 'string') {
+        params.texture_format = params.texture_format.toUpperCase();
+    }
+    // [hard] vertex colors only survive in OBJ/GLTF exports.
+    if (params.export_vertex_colors === true && format && !['OBJ', 'GLTF'].includes(format)) {
+        delete params.export_vertex_colors;
+        warnings.push(`export_vertex_colors only applies to OBJ/GLTF (removed for ${format})`);
+    }
+    if (params.fbx_preset !== undefined) {
+        if (!FBX_PRESETS.includes(params.fbx_preset)) {
+            errors.push(`fbx_preset must be one of ${FBX_PRESETS.join('/')}`);
+        }
+        else if (format !== 'FBX') {
+            delete params.fbx_preset;
+            warnings.push('fbx_preset only applies to FBX exports (removed)');
+        }
+    }
+    if (params.export_orientation !== undefined &&
+        !EXPORT_ORIENTATIONS.includes(params.export_orientation)) {
+        errors.push(`export_orientation must be one of ${EXPORT_ORIENTATIONS.join('/')}`);
+    }
+    // [soft] cost transparency: any non-default option upgrades billing to
+    // convert_model_complex.
+    const defaults = {
+        texture_size: 4096,
+        texture_format: 'JPEG',
+        bake: true,
+        pack_uv: false,
+        export_vertex_colors: false,
+        pivot_to_center_bottom: false,
+        scale_factor: 1,
+        with_animation: true,
+        animate_in_place: false,
+        export_orientation: '+x',
+        fbx_preset: 'blender',
+        quad: false,
+        flatten_bottom: false,
+        force_symmetry: false,
+    };
+    const complex = Object.entries(defaults).some(([k, dv]) => params[k] !== undefined && params[k] !== dv) || params.face_limit !== undefined || params.part_names !== undefined;
+    if (complex) {
+        warnings.push('non-default convert options use the "complex convert" price tier');
+    }
+    return { params, warnings, errors };
+}
+/**
+ * Validate parameters for mesh/decimate (ModelPostProcessValidation):
+ * v2.0 (default): face_limit 500–20000 tri / 500–10000 quad.
+ * v1.0: face_limit REQUIRED, 500–2,000,000 tri / 500–150,000 quad; no bake/part_names.
+ */
+export function validateDecimateParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const model = typeof params.model === 'string' ? params.model.toLowerCase() : undefined;
+    if (model !== undefined && !['v1.0', 'v2.0', 'default'].includes(model)) {
+        errors.push(`decimate model must be v2.0 or v1.0 (got "${String(params.model)}")`);
+    }
+    const isV1 = model === 'v1.0';
+    const quad = params.quad === true;
+    const face = params.face_limit;
+    if (isV1) {
+        const max = quad ? 150_000 : 2_000_000;
+        if (typeof face !== 'number') {
+            errors.push(`decimate model v1.0 requires face_limit (500–${max}${quad ? ', quad' : ''})`);
+        }
+        else if (face < 500 || face > max) {
+            errors.push(`decimate v1.0 face_limit must be within 500–${max}${quad ? ' (quad mesh)' : ''}`);
+        }
+        for (const key of ['bake', 'part_names']) {
+            if (params[key] !== undefined) {
+                delete params[key];
+                warnings.push(`decimate v1.0 does not support ${key} (removed)`);
+            }
+        }
+    }
+    else {
+        const max = quad ? 10_000 : 20_000;
+        if (typeof face === 'number' && (face < 500 || face > max)) {
+            errors.push(`decimate face_limit must be within 500–${max}${quad ? ' (quad halves the budget)' : ''}`);
+        }
+    }
+    return { params, warnings, errors };
+}
+/** Validate retarget animations list. */
+export function validateRetargetParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const anims = params.animations;
+    if (Array.isArray(anims)) {
+        if (anims.length === 0)
+            errors.push('animations must not be empty');
+        if (anims.length > 5)
+            errors.push(`retarget accepts at most 5 animations per task (got ${anims.length}); billing is per animation`);
+        if (anims.length === 1) {
+            // Server accepts either `animation` (single) or `animations` (list).
+            params.animation = anims[0];
+            delete params.animations;
+        }
+    }
+    else if (typeof params.animation !== 'string') {
+        errors.push('retarget requires animation (single) or animations (list)');
+    }
+    return { params, warnings, errors };
+}