tripo-cli 0.7.3 → 0.8.0

package/dist/core/requests.js

@@ -5,8 +5,8 @@
  * `parameters`), so new API options work without a CLI release.
  */
 import { getStep } from '../knowledge/chains.js';
-import { applyTextureV35, validateConvertParams, validateDecimateParams, validateGenerationParams, validateMeshEditParams, validateRetargetParams, } from '../knowledge/params.js';
-import { CAPABILITY_DEFAULTS, SEGMENT_MODELS, TEXTURE_MODELS, normalizeModel, normalizeRigModel, } from '../knowledge/models.js';
+import { applyTextureV35, validateConvertParams, validateDecimateParams, validateGenerationParams, validateImageParams, validateMeshEditParams, validateRetargetParams, } from '../knowledge/params.js';
+import { CAPABILITY_DEFAULTS, RIG_MODEL_V1, RIG_MODEL_V25, RIG_MODEL_V30, RIG_SPECS, RIG_TYPES, SEGMENT_MODELS, TEXTURE_MODELS, normalizeModel, normalizeRigModel, } from '../knowledge/models.js';
 import { UsageError } from './errors.js';
 function ensure(result) {
     if (result.errors.length > 0) {
@@ -15,12 +15,12 @@ function ensure(result) {
 }
 /** 3D generation: text-to-model. */
 export function buildTextToModel(prompt, model, params) {
-    const validated = validateGenerationParams(model, params);
+    const validated = validateGenerationParams(model, { prompt, ...params });
     ensure(validated);
     return {
         request: {
             endpoint: '/v3/generation/text-to-model',
-            payload: { prompt, model: normalizeModel(model), ...validated.params },
+            payload: { prompt, ...validated.params, model: normalizeModel(model) },
         },
         taskType: 'text_to_model',
         warnings: validated.warnings,
@@ -33,7 +33,7 @@ export function buildImageToModel(input, model, params) {
     return {
         request: {
             endpoint: '/v3/generation/image-to-model',
-            payload: { input, model: normalizeModel(model), ...validated.params },
+            payload: { input, ...validated.params, model: normalizeModel(model) },
         },
         taskType: 'image_to_model',
         warnings: validated.warnings,
@@ -62,7 +62,7 @@ export function buildMultiviewToModel(views, model, params) {
     return {
         request: {
             endpoint: '/v3/generation/multiview-to-model',
-            payload: { inputs, model: normalizeModel(model), ...validated.params },
+            payload: { inputs, ...validated.params, model: normalizeModel(model) },
         },
         taskType: 'multiview_to_model',
         warnings: validated.warnings,
@@ -72,28 +72,38 @@ export function buildMultiviewToModel(views, model, params) {
  * Server task types (TaskType enum): text-to-image → `text_to_image`,
  * image-to-image → `generate_image`. */
 export function buildTextToImage(prompt, params) {
+    const validated = validateImageParams(params, false);
+    ensure(validated);
     return {
         request: {
             endpoint: '/v3/generation/text-to-image',
-            payload: { prompt, model: params.model ?? CAPABILITY_DEFAULTS.textToImage, ...omit(params, ['model']) },
+            payload: { prompt, ...validated.params },
         },
         taskType: 'text_to_image',
-        warnings: [],
+        warnings: validated.warnings,
     };
 }
 /** One reference image goes as `input`, several as `inputs` (prompt cites them as image[1], image[2], ...). */
 export function buildImageToImage(inputs, params) {
+    const validated = validateImageParams(params, true);
+    ensure(validated);
+    const model = String(validated.params.model);
+    const maxInputs = model.startsWith('seedream') ? 4 : model.startsWith('banana') ? 10 : 16;
+    if (inputs.length === 0)
+        throw new UsageError('image-to-image requires at least one reference image');
+    if (inputs.length > maxInputs) {
+        throw new UsageError(`${model} accepts at most ${maxInputs} reference images (got ${inputs.length})`);
+    }
     return {
         request: {
             endpoint: '/v3/generation/image-to-image',
             payload: {
                 ...(inputs.length > 1 ? { inputs } : { input: inputs[0] }),
-                model: params.model ?? CAPABILITY_DEFAULTS.imageToImage,
-                ...omit(params, ['model']),
+                ...validated.params,
             },
         },
         taskType: 'generate_image',
-        warnings: [],
+        warnings: validated.warnings,
     };
 }
 export function buildImageToMultiview(input, params) {
@@ -117,6 +127,27 @@ export function buildImageToSplat(input, params) {
         warnings: [],
     };
 }
+/** Validate deterministic request and rig/preset constraints before any earlier task runs. */
+export function validateChainRequests(chain) {
+    let rigModel;
+    for (const spec of chain) {
+        const built = buildStepRequest(spec.step, '<upstream>', spec.args);
+        if (built.taskType === 'animate_retarget' && rigModel) {
+            const { animation, animations } = built.request.payload;
+            const requested = Array.isArray(animations) ? animations : [animation];
+            for (const preset of requested) {
+                if (typeof preset !== 'string' || !preset.startsWith('preset:'))
+                    continue;
+                if ((rigModel === RIG_MODEL_V1) !== preset.startsWith('preset:biped:')) {
+                    throw new UsageError(`preset ${preset} is incompatible with rig model ${rigModel}; v1.0 uses preset:biped:*, v2.5/v3.0 use generic or body-type presets`);
+                }
+            }
+        }
+        if (!getStep(spec.step)?.passthrough) {
+            rigModel = built.taskType === 'animate_rig' ? String(built.request.payload.model) : undefined;
+        }
+    }
+}
 /**
  * Processing step (texture/convert/rig/...): validate per step, then build.
  * `input` must already be a task_id / file_token / URL.
@@ -161,6 +192,25 @@ export function buildStepRequest(stepName, input, args) {
             params.model = params.model === undefined
                 ? CAPABILITY_DEFAULTS.rig
                 : normalizeRigModel(String(params.model));
+            if (![RIG_MODEL_V1, RIG_MODEL_V25, RIG_MODEL_V30].includes(String(params.model))) {
+                throw new UsageError('unsupported rig model');
+            }
+            const rigType = params.rig_type === undefined ? 'biped' : params.rig_type;
+            if (!RIG_TYPES.includes(rigType))
+                throw new UsageError('unsupported rig_type');
+            if (params.model === RIG_MODEL_V1 && rigType !== 'biped')
+                throw new UsageError('rig v1.0 only supports biped');
+            if (rigType === 'others' && params.model !== RIG_MODEL_V30)
+                throw new UsageError('rig_type others requires rig v3.0');
+            if (params.spec !== undefined) {
+                if (!RIG_SPECS.includes(params.spec))
+                    throw new UsageError('unsupported rig spec');
+                if (rigType !== 'biped')
+                    throw new UsageError('rig spec only applies to biped');
+                if (!['tripo', 'mixamo'].includes(String(params.spec)) && params.model !== RIG_MODEL_V30) {
+                    throw new UsageError('spec actorcore/unity/unreal/vrm requires rig v3.0');
+                }
+            }
             break;
         }
         case 'texture': {
@@ -209,9 +259,3 @@ export function buildStepRequest(stepName, input, args) {
         warnings,
     };
 }
-function omit(obj, keys) {
-    const out = { ...obj };
-    for (const k of keys)
-        delete out[k];
-    return out;
-}

package/dist/core/task-service.js

@@ -8,13 +8,12 @@ import { basename } from 'node:path';
 import { resolvePlatformBaseUrl, resolveRegion } from '../config/config.js';
 import { loadContext, updateContext } from '../config/context.js';
 import { RefError, appendHistory, readHistory, resolveReference, slugify, updateHistoryStatus } from '../config/history.js';
-import { t } from '../i18n.js';
 import { detectInput } from '../util/input-detect.js';
 import { notifyDone } from '../util/notify.js';
 import { createSpinner } from '../util/spinner.js';
 import { defaultOutputDir, downloadArtifacts } from './download.js';
 import { taskOrigin } from './analytics.js';
-import { ApiError, CliError, TaskFailedError, UsageError, balanceSuggestion } from './errors.js';
+import { ApiError, ArtifactDownloadError, CliError, TaskFailedError, UsageError, balanceSuggestion } from './errors.js';
 import { isQuiet, log, warn } from './output.js';
 import { uploadLocalFile } from './upload.js';
 /** Placeholder `input` value for a local file that a dry run would upload. */
@@ -75,10 +74,7 @@ export async function precheckBalance(client) {
         throw new ApiError({ apiCode: 2010, suggestion: balanceSuggestion(undefined, balance) });
     }
     if (balance < 30) {
-        warn(t({
-            zh: `余额仅剩 ${balance} 积分,任务可能因余额不足失败(tripo topup 充值)`,
-            en: `balance is down to ${balance} credits; tasks may fail (run "tripo topup")`,
-        }));
+        warn(`balance is down to ${balance} credits; tasks may fail (run "tripo topup")`);
     }
 }
 /** Submit one task and (by default) watch it to completion + download. */
@@ -87,6 +83,8 @@ export async function runTask(options) {
     if (options.precheckBalance !== false)
         await precheckBalance(client);
     const taskId = await client.createTask(request.endpoint, request.payload, taskType);
+    // Report the task before any local bookkeeping that can throw: batch decides retry safety from it.
+    options.onCreated?.({ task_id: taskId, type: taskType });
     const name = uniqueName(slugify(options.name));
     const entry = {
         analytics_origin: taskOrigin(request.payload.model),
@@ -99,8 +97,13 @@ export async function runTask(options) {
         payload: request.payload,
     };
     appendHistory(entry);
-    updateContext({ last_task_id: taskId });
-    log(t({ zh: `任务已创建 ${taskId} (@${name})`, en: `task created ${taskId} (@${name})` }));
+    try {
+        updateContext({ last_task_id: taskId });
+    }
+    catch (err) {
+        warn(`could not update .tripo/context.json (${err instanceof Error ? err.message : String(err)})`);
+    }
+    log(`task created ${taskId} (@${name})`);
     if (options.noWait) {
         return { task_id: taskId, type: taskType, status: 'queued' };
     }
@@ -121,17 +124,14 @@ export async function runTask(options) {
             updateHistoryStatus(taskId, 'failed');
         }
         else if (err instanceof CliError) {
-            err.suggestion = t({
-                zh: `任务仍在服务端运行,成功后照常扣费;用 tripo task watch ${taskId} --download 继续等待,不要重新提交`,
-                en: `the task keeps running server-side and is billed if it succeeds; resume with "tripo task watch ${taskId} --download" instead of resubmitting`,
-            });
+            err.suggestion = `the task keeps running server-side and is billed if it succeeds; resume with "tripo task watch ${taskId} --download" instead of resubmitting`;
         }
         throw err;
     }
     updateHistoryStatus(taskId, 'success', { credits_consumed: task.credits_consumed });
     spinner.succeed(`${taskType} · ${taskId}` +
         (task.credits_consumed !== undefined
-            ? t({ zh: ` · 消耗 ${task.credits_consumed} 积分`, en: ` · ${task.credits_consumed} credits` })
+            ? ` · ${task.credits_consumed} credits`
             : ''));
     const result = {
         task_id: taskId,
@@ -144,12 +144,12 @@ export async function runTask(options) {
     if (!options.noDownload) {
         const baseDir = options.outDir ?? loadContext().output_dir ?? process.cwd();
         const dir = defaultOutputDir(baseDir, name, taskId);
-        const dlSpinner = createSpinner(t({ zh: '下载产物…', en: 'downloading artifacts…' }), isQuiet());
+        const dlSpinner = createSpinner('downloading artifacts…', isQuiet());
         try {
             const artifacts = await downloadArtifacts(task, dir, entry, {
-                onFile: (f) => dlSpinner.update(t({ zh: `下载 ${f}`, en: `downloading ${f}` })),
+                onFile: (f) => dlSpinner.update(`downloading ${f}`),
             });
-            dlSpinner.succeed(t({ zh: `产物已保存 ${artifacts.outputDir}`, en: `artifacts saved to ${artifacts.outputDir}` }));
+            dlSpinner.succeed(`artifacts saved to ${artifacts.outputDir}`);
             result.output_dir = artifacts.outputDir;
             result.files = artifacts.files.map((f) => basename(f));
             result.model_file = artifacts.modelFile;
@@ -157,13 +157,12 @@ export async function runTask(options) {
             updateHistoryStatus(taskId, 'success', { output_dir: artifacts.outputDir });
         }
         catch (err) {
-            dlSpinner.fail(t({ zh: '产物下载失败(任务本身已成功)', en: 'artifact download failed (the task itself succeeded)' }));
-            warn(String(err instanceof Error ? err.message : err));
-            warn(t({ zh: `可重试:tripo task get ${taskId} --download`, en: `retry with: tripo task get ${taskId} --download` }));
+            dlSpinner.fail('artifact download failed (the task itself succeeded)');
+            throw new ArtifactDownloadError(taskId, result, err instanceof Error ? err.message : String(err));
         }
     }
     if (options.notify) {
-        notifyDone('Tripo', t({ zh: `${taskType} 完成`, en: `${taskType} finished` }));
+        notifyDone('Tripo', `${taskType} finished`);
     }
     return result;
 }

package/dist/knowledge/chains.js

@@ -22,22 +22,22 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'animate_retarget',
 ]);
 export const STEPS = [
-    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '重新生成贴图 / PBR 材质', en: 'regenerate textures / PBR materials' } },
-    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '转换输出格式 / 贴图尺寸 / 朝向', en: 'convert format / texture size / orientation' } },
-    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true, describe: { zh: '导入本地模型文件作为加工起点', en: 'import a local model file as the chain source' } },
-    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'], describe: { zh: '检查是否可绑骨(不产出模型,不可绑则止损)', en: 'check riggability (no model output; stops the chain if not riggable)' } },
-    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true, describe: { zh: '自动绑定骨骼', en: 'auto-rig a skeleton' } },
-    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'], describe: { zh: '把预设动画重定向到绑骨模型', en: 'retarget preset animations onto the rigged model' } },
-    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true, describe: { zh: '把网格分割成部件', en: 'segment the mesh into parts' } },
-    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false, describe: { zh: '补全分割后的部件', en: 'complete the segmented parts' } },
-    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'], describe: { zh: '减面到目标面数', en: 'decimate to a target face count' } },
-    { name: 'uv', endpoint: '/v3/mesh/uv', produces: 'mesh_uv', accepts: 'any-model', acceptsFile: true, describe: { zh: '智能展 UV,原贴图/骨骼/动画映射到新布局', en: 'smart UV unwrap; remaps textures/rig/animation onto the new layout' } },
+    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true, describe: 'regenerate textures / PBR materials' },
+    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true, describe: 'convert format / texture size / orientation' },
+    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true, describe: 'import a local model file as the chain source' },
+    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'], describe: 'check riggability (no model output; stops the chain if not riggable)' },
+    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true, describe: 'auto-rig a skeleton' },
+    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'], describe: 'retarget preset animations onto the rigged model' },
+    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true, describe: 'segment the mesh into parts' },
+    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false, describe: 'complete the segmented parts' },
+    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'], describe: 'decimate to a target face count' },
+    { name: 'uv', endpoint: '/v3/mesh/uv', produces: 'mesh_uv', accepts: 'any-model', acceptsFile: true, describe: 'smart UV unwrap; remaps textures/rig/animation onto the new layout' },
     // mesh/edit: local retry/refine inside a bbox, P2 pipeline (model fixed to P2-20260801).
-    { name: 'edit', endpoint: '/v3/mesh/edit', produces: 'mesh_edit', accepts: 'any-model', acceptsFile: true, describe: { zh: '在 bbox 区域内局部重做(P2 管线)', en: 'redo one bbox region locally (P2 pipeline)' } },
+    { name: 'edit', endpoint: '/v3/mesh/edit', produces: 'mesh_edit', accepts: 'any-model', acceptsFile: true, describe: 'redo one bbox region locally (P2 pipeline)' },
     // 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, describe: { zh: '智能语义分割', en: 'smart semantic segmentation' } },
+    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smartsegment_model', accepts: [], acceptsFile: true, describe: 'smart semantic segmentation' },
 ];
 const stepIndex = new Map();
 for (const s of STEPS) {

package/dist/knowledge/error-catalog.js

@@ -1,5 +1,5 @@
 /**
- * V3 error-code catalog: human translations (zh/en), retryability, and the
+ * V3 error-code catalog: human-readable messages, retryability, and the
  * CLI exit code each error maps to.
  *
  * Source of truth: backend ErrorCode enum (platform-common .../error/ErrorCode.java,
@@ -20,37 +20,37 @@ export const EXIT = {
     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: 'Unsupported request parameter (check field names and values)', retryable: false, exitCode: EXIT.USAGE },
-    { code: 2003, zh: '输入文件为空,请检查文件是否损坏', en: 'The input file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
-    { code: 2004, zh: '不支持的文件类型', en: 'Unsupported 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 },
+    { code: 1000, message: 'Unknown server-side error; contact support with the request id', retryable: true, exitCode: EXIT.NETWORK },
+    { code: 1001, message: 'Fatal server-side error; contact support with the request id', retryable: false, exitCode: EXIT.NETWORK },
+    { code: 1002, message: '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, message: 'The request body is malformed', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1004, message: 'One or more parameters are invalid (check the docs)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 1005, message: 'Not allowed to access this resource (check permissions)', retryable: false, exitCode: EXIT.AUTH },
+    { code: 1007, message: 'Rate limit exceeded — too many requests in a short time', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2000, message: 'Generation concurrency limit hit (task families share a pool)', retryable: true, exitCode: EXIT.RATE_LIMIT },
+    { code: 2001, message: 'Task not found (same key that created it? right region?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2002, message: 'Unsupported request parameter (check field names and values)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2003, message: 'The input file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2004, message: 'Unsupported file type', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2005, message: 'The draft task is not a success; retry with a successful one', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2006, message: 'The original task type is not supported for this operation', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2007, message: 'The original task has not succeeded', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2008, message: 'Input violates the content policy; change the input', retryable: false, exitCode: EXIT.CONTENT_POLICY },
+    { code: 2009, message: 'The prompt contains invalid characters', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2010, message: 'Insufficient credits', retryable: false, exitCode: EXIT.BALANCE },
+    { code: 2011, message: 'The rig-check input task has no model output', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2012, message: 'retarget only accepts a rig task as input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2013, message: 'Invalid priority (contact support for higher priority)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2014, message: 'Error occurred during content auditing; contact support', retryable: false, exitCode: EXIT.FATAL },
+    { code: 2015, message: 'Model version deprecated; upgrade the model parameter', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2016, message: 'This request type is deprecated; use an alternative', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2017, message: 'The model version value is invalid', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2018, message: 'Model too complex to remesh; lower face_limit or simplify input', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2019, message: 'File not found (upload succeeded? token expired?)', retryable: false, exitCode: EXIT.NOT_FOUND },
+    { code: 2020, message: 'The image URL is invalid (must be publicly reachable)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2021, message: 'File size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2022, message: 'Image size exceeds the limit; reduce and retry', retryable: false, exitCode: EXIT.USAGE },
+    { code: 4001, message: '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) {

package/dist/knowledge/models.js

@@ -1,9 +1,9 @@
 /**
- * Dual-model strategy — the single source of truth for 3D model selection.
+ * Model routing — the single source of truth for 3D generation 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.
+ * H3.1 is the official default (flagship, highest fidelity) and also covers dense
+ * geometry and H-only parameters. Real-time, editable and topology-constrained
+ * assets route to P2.
  */
 /**
  * Wire values are what the server actually accepts (backend whitelist:
@@ -13,24 +13,28 @@
  */
 export const MODEL_V31 = 'v3.1-20260211';
 export const MODEL_P1 = 'P1-20260311';
-/** P-series upgrade (Preview): adds quad output; explicit --model only, never auto-selected. */
+/** P-series model: editable low-poly topology and quad output. */
 export const MODEL_P2 = 'P2-20260801';
-/** User-facing aliases normalized to the wire values above. */
+/** User-facing aliases normalized to the wire values above (matched case-insensitively). */
 export const MODEL_ALIASES = {
+    'H3.1': MODEL_V31,
+    'P1.0': MODEL_P1,
+    'P2.0': MODEL_P2,
+    'P2.0 Preview': MODEL_P2,
     '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,
-    p2: MODEL_P2,
     P2: MODEL_P2,
     'P2-20260801': MODEL_P2,
     'tripo-p2': MODEL_P2,
     // Older whitelisted versions, alias → wire.
+    'H3.0': 'v3.0-20250812',
     'v3.0': 'v3.0-20250812',
     'tripo-v3.0': 'v3.0-20250812',
+    'H2.5': 'v2.5-20250123',
     'v2.5': 'v2.5-20250123',
     'tripo-v2.5': 'v2.5-20250123',
 };
@@ -105,7 +109,6 @@ export const TEXT_TO_IMAGE_MODELS = [
     'banana',
     'banana_pro',
     'banana2',
-    'chat_image_1',
     'chat_image_1.5',
     'chat_image_2',
     'chat_image_2.5_flare',
@@ -116,7 +119,6 @@ export const IMAGE_TO_IMAGE_MODELS = [
     'banana',
     'banana_pro',
     'banana2',
-    'chat_image_1',
     'chat_image_1.5',
     'chat_image_2',
     'chat_image_2.5_flare',
@@ -161,9 +163,10 @@ export const FBX_PRESETS = ['blender', '3dsmax', 'mixamo', 'bake_scale'];
 export const EXPORT_ORIENTATIONS = ['+x', '-x', '+y', '-y'];
 /** `fast` only works with texture model v3.5 (other versions → 1004). */
 export const TEXTURE_QUALITIES = ['fast', 'standard', 'detailed', 'extreme'];
-/** Normalize any accepted alias to the canonical wire value; unknown values pass through. */
+const MODEL_ALIAS_LOOKUP = new Map(Object.entries(MODEL_ALIASES).map(([alias, wire]) => [alias.toLowerCase(), wire]));
+/** Normalize any accepted alias to the canonical wire value; unknown values pass through for validation to reject. */
 export function normalizeModel(input) {
-    return MODEL_ALIASES[input] ?? input;
+    return MODEL_ALIAS_LOOKUP.get(input.trim().toLowerCase()) ?? input;
 }
 export function isP1(model) {
     return normalizeModel(model) === MODEL_P1;
@@ -171,21 +174,117 @@ export function isP1(model) {
 export function isP2(model) {
     return normalizeModel(model) === MODEL_P2;
 }
-/** The one rule. Returns the model plus a human-readable reason. */
+function hRequirement(intent) {
+    const params = intent.params ?? {};
+    const quad = intent.quad === true || params.quad === true;
+    if (intent.denseGeometry)
+        return 'dense geometry';
+    if (params.geometry_quality !== undefined)
+        return 'geometry_quality';
+    if (params.smart_low_poly === true)
+        return 'smart_low_poly';
+    if (params.generate_parts === true)
+        return 'generate_parts';
+    if (typeof intent.faceLimit === 'number' && intent.faceLimit > (quad ? P2_FACE_LIMIT.quadMax : P2_FACE_LIMIT.triMax)) {
+        return `face budget exceeds P2 ${quad ? 'quad' : 'triangle'} limit`;
+    }
+    if (typeof intent.faceLimit === 'number' && intent.faceLimit > 0 && intent.faceLimit < P2_FACE_LIMIT.min) {
+        return 'face budget below P2 minimum';
+    }
+    return undefined;
+}
+/** Select a generation model from explicit choice, geometry requirements and intended use. */
 export function chooseModel(intent) {
-    if (intent.explicit) {
-        return { model: normalizeModel(intent.explicit), reason: 'explicit --model' };
+    const paramModel = typeof intent.params?.model === 'string' ? intent.params.model : undefined;
+    const explicit = intent.explicit ?? paramModel;
+    if (explicit) {
+        return {
+            model: normalizeModel(explicit),
+            reason: intent.explicit ? 'explicit --model' : 'explicit model parameter',
+        };
+    }
+    const hOnly = hRequirement(intent);
+    if (hOnly) {
+        return { model: MODEL_V31, reason: `${hOnly} → v3.1` };
     }
-    if (intent.lowPoly) {
-        return { model: MODEL_P1, reason: 'low-poly intent → P1' };
+    if (intent.preferred) {
+        const preferred = normalizeModel(intent.preferred);
+        if (preferred !== MODEL_P1)
+            return { model: preferred, reason: 'scenario preference' };
     }
-    if (intent.faceLimit !== undefined && intent.faceLimit <= P1_FACE_LIMIT.max) {
-        return { model: MODEL_P1, reason: `face budget ${intent.faceLimit} ≤ ${P1_FACE_LIMIT.max} → P1` };
+    const params = intent.params ?? {};
+    if (intent.lowPoly || intent.realtime || intent.editable || intent.quad === true || params.quad === true || intent.faceLimit !== undefined) {
+        return { model: MODEL_P2, reason: 'real-time or editable topology → P2' };
     }
-    return { model: MODEL_V31, reason: 'default high-fidelity → v3.1' };
+    return { model: MODEL_V31, reason: 'official default → v3.1' };
+}
+/**
+ * Official list price per generation task in credits, identical on the ov and cn
+ * model pages. Tiers: [no texture, standard/fast, detailed, extreme]. P1 and the
+ * legacy models publish no price, so they are never estimated.
+ */
+const GENERATION_CREDITS = {
+    [MODEL_V31]: {
+        text_to_model: [10, 20, 30, 40],
+        image_to_model: [20, 30, 40, 50],
+        multiview_to_model: [20, 30, 40, 50],
+    },
+    [MODEL_P2]: {
+        text_to_model: [100, 110, 120, 130],
+        image_to_model: [100, 110, 120, 130],
+        multiview_to_model: [100, 110, 120, 130],
+    },
+};
+/** List-price credits for one generation task from its validated payload; undefined when no price is published. */
+export function estimateGenerationCredits(model, taskType, params) {
+    const wire = normalizeModel(model);
+    const tiers = GENERATION_CREDITS[wire]?.[taskType];
+    if (!tiers)
+        return undefined;
+    let credits = tiers[params.texture === false ? 0 : params.texture_quality === 'extreme' ? 3 : params.texture_quality === 'detailed' ? 2 : 1];
+    if (wire === MODEL_V31) {
+        if (params.geometry_quality === 'detailed')
+            credits += 20;
+        if (params.quad === true)
+            credits += 5;
+        if (params.smart_low_poly === true)
+            credits += 10;
+        if (params.generate_parts === true)
+            credits += 20;
+    }
+    return credits;
 }
 /** Keywords that signal low-poly intent in a prompt (used by make/ai). */
 const LOW_POLY_HINTS = [/low[\s_-]?poly/i, /低模/, /低面/, /低多边形/, /手游/, /voxel/i, /像素风/];
+/** Physical games, product nouns (gaming PC, console) and animation *styles* are not real-time intent. */
+const REALTIME_HINTS = [
+    /\b(?:(?<!\b(?:board|card|tabletop|dice|party)[\s_-]?)games?|gameplay|real[\s_-]?time|unity|unreal(?:\s+engine)?|godot|three\.?js|webgl)\b/i,
+    /\b(?:editable|edit[\s_-]?friendly|topology|retopo(?:logy)?|quad(?:s)?|rig(?:[\s_-]?ready|ged|ging)?|animat(?:e|ions?)(?![\s_-]?styl))\b/i,
+    /(?<!棋盘|桌面)游戏|手游|端游|实时|引擎|可编辑|可修改|拓扑|重拓扑|四边面|四边形|绑定|骨骼|动画(?![风片])|虚幻/,
+];
+const DENSE_GEOMETRY_HINTS = [
+    /\b(?:dense|high[\s_-]?density|high[\s_-]?detail(?:ed)?)\s+(?:mesh|geometry|topology)\b/i,
+    /\bhigh[\s_-]?poly(?:gon(?:al)?)?\b/i,
+    /\bnanite\b/i,
+    /\b(?:million|millions)\s+of\s+(?:faces|triangles|polygons)\b/i,
+    /高模|高面数|高多边形|高密度(?:网格|几何)|密集(?:网格|几何)|稠密(?:网格|几何)|高精度(?:网格|几何)|百万(?:面|三角面)/,
+];
 export function detectLowPolyIntent(text) {
     return LOW_POLY_HINTS.some((re) => re.test(text));
 }
+/** Detect uses that benefit from P-series topology without treating visual quality as mesh density. */
+export function detectRealtimeIntent(text) {
+    return REALTIME_HINTS.some((re) => re.test(text));
+}
+/** Detect only explicit dense-geometry requirements; phrases such as "high quality" do not match. */
+export function detectDenseGeometryIntent(text) {
+    // Match each mention independently: negating one must not hide a later positive requirement.
+    return DENSE_GEOMETRY_HINTS.some((re) => Array.from(text.matchAll(new RegExp(re.source, `${re.flags}g`))).some((match) => {
+        const before = text.slice(0, match.index);
+        const after = text.slice(match.index + match[0].length);
+        const negatedBefore = /(?:\b(?:no|not|without|avoid|exclude)\s+(?:(?:a|an|any|the)\s+)?|\b(?:do\s+not|don't|does\s+not|doesn't)\s+(?:need|want|require|use)\s+(?:(?:a|an|any|the)\s+)?|\bno\s+need\s+for\s+(?:(?:a|an|any|the)\s+)?|(?:不要|不需要|无需|不用|不使用|避免|非)\s*)$/i.test(before);
+        const negatedAfter = /^\s*(?:(?:mesh|geometry|topology)\s+)?(?:is\s+not|isn't|not)\s+(?:needed|required|wanted)\b/i.test(after)
+            || /^\s*(?:不需要|不要|无需)/.test(after);
+        return !negatedBefore && !negatedAfter;
+    }));
+}