tripo-cli 0.7.2 → 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 { 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,27 +33,36 @@ 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,
     };
 }
-/** 3D generation: multiview-to-model. Views ordered [front, left, back, right]. */
+/**
+ * 3D generation: multiview-to-model. Views ordered [front, left, back, right],
+ * or `{task_id}` of an image-to-multiview / edit-multiview task to reuse its 4 views.
+ */
 export function buildMultiviewToModel(views, model, params) {
     const validated = validateGenerationParams(model, params);
     ensure(validated);
-    const inputs = ['front', 'left', 'back', 'right']
-        .filter((v) => views[v])
-        .map((v) => ({ [v]: views[v] }));
-    if (!views.front)
-        throw new UsageError('multiview requires a front view');
-    if (inputs.length < 2)
-        throw new UsageError('multiview requires at least 2 views');
+    let inputs;
+    if ('task_id' in views) {
+        inputs = [{ task_id: views.task_id }];
+    }
+    else {
+        inputs = ['front', 'left', 'back', 'right']
+            .filter((v) => views[v])
+            .map((v) => ({ [v]: views[v] }));
+        if (!views.front)
+            throw new UsageError('multiview requires a front view');
+        if (inputs.length < 2)
+            throw new UsageError('multiview requires at least 2 views');
+    }
     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,
@@ -63,23 +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,
     };
 }
-export function buildImageToImage(input, params) {
+/** 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: { input, model: params.model ?? CAPABILITY_DEFAULTS.imageToImage, ...omit(params, ['model']) },
+            payload: {
+                ...(inputs.length > 1 ? { inputs } : { input: inputs[0] }),
+                ...validated.params,
+            },
         },
         taskType: 'generate_image',
-        warnings: [],
+        warnings: validated.warnings,
     };
 }
 export function buildImageToMultiview(input, params) {
@@ -103,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.
@@ -147,16 +192,40 @@ 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': {
-            const model = params.model === undefined
-                ? CAPABILITY_DEFAULTS.texture
-                : normalizeModel(String(params.model));
-            if (!TEXTURE_MODELS.includes(model)) {
-                throw new UsageError(`texture model must be one of ${TEXTURE_MODELS.join('/')} (got "${String(params.model)}")`);
+            if (params.model !== undefined) {
+                const model = normalizeModel(String(params.model));
+                if (!TEXTURE_MODELS.includes(model)) {
+                    throw new UsageError(`texture model must be one of ${TEXTURE_MODELS.join('/')} (got "${String(params.model)}")`);
+                }
+                params.model = model;
             }
-            params.model = model;
+            const errors = [];
+            applyTextureV35(params, 'model', warnings, errors);
+            ensure({ params, warnings, errors });
+            if (params.model === undefined)
+                params.model = CAPABILITY_DEFAULTS.texture;
             break;
         }
         case 'segment': {
@@ -190,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,
@@ -139,15 +139,17 @@ export async function runTask(options) {
         status: task.status,
         credits_consumed: task.credits_consumed,
     };
+    if (typeof task.output?.normalize_scale === 'number')
+        result.normalize_scale = task.output.normalize_scale;
     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;
@@ -155,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/core/upload.js

@@ -5,6 +5,8 @@ import { UsageError } from './errors.js';
 import { IMAGE_EXTS, MODEL_EXTS } from '../util/input-detect.js';
 const IMAGE_MAX = 20 * 1024 * 1024;
 const MODEL_MAX = 150 * 1024 * 1024;
+/** Above this size the docs recommend the presigned direct upload. */
+const PRESIGN_THRESHOLD = 60 * 1024 * 1024;
 const MIME = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -25,18 +27,34 @@ export async function uploadLocalFile(client, filePath) {
     if (!isImage && !isModel) {
         throw new UsageError(`unsupported file type "${ext}" for upload`);
     }
-    // The server's upload whitelist has no gltf: a .gltf references external
-    // .bin/texture files, so a single-file upload would be incomplete anyway.
-    if (ext === '.gltf') {
-        throw new UsageError('the upload API does not accept .gltf (it references external files) — export as .glb, or host it and pass the URL');
-    }
     const info = await stat(filePath);
     const limit = isImage ? IMAGE_MAX : MODEL_MAX;
     if (info.size > limit) {
         throw new UsageError(`${basename(filePath)} is ${(info.size / 1024 / 1024).toFixed(1)}MB, exceeding the ${limit / 1024 / 1024}MB ${isImage ? 'image' : 'model'} limit`);
     }
     const bytes = await readFile(filePath);
+    // .gltf goes through presign: the multipart whitelist has rejected it, the presign one lists it.
+    if (ext === '.gltf')
+        assertSelfContainedGltf(filePath, bytes);
+    if (ext === '.gltf' || info.size > PRESIGN_THRESHOLD) {
+        const { file_token } = await client.uploadFileViaPresign(ext.slice(1), new Blob([bytes]));
+        return file_token;
+    }
     const blob = new Blob([bytes], { type: MIME[ext] ?? 'application/octet-stream' });
     const { file_token } = await client.uploadFile(basename(filePath), blob);
     return file_token;
 }
+/** A single-file upload cannot carry a .gltf's external .bin/texture files. */
+function assertSelfContainedGltf(filePath, bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new UsageError(`${basename(filePath)} is not valid glTF JSON`);
+    }
+    const external = [...(doc.buffers ?? []), ...(doc.images ?? [])].some((ref) => typeof ref.uri === 'string' && !ref.uri.startsWith('data:'));
+    if (external) {
+        throw new UsageError(`${basename(filePath)} references external files (.bin/textures) — export as .glb, or host it and pass the URL`);
+    }
+}

package/dist/core/watch.js

@@ -36,6 +36,9 @@ export async function watchTask(client, taskId, options = {}) {
     }
 }
 function extractFailureReason(task) {
+    if (task.error_message) {
+        return task.error_code !== undefined ? `${task.error_message} (code ${task.error_code})` : task.error_message;
+    }
     const out = task.output ?? {};
     const candidate = out.message ?? out.error ?? out.reason;
     return typeof candidate === 'string' ? candidate : undefined;

package/dist/knowledge/chains.js

@@ -22,23 +22,22 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'animate_retarget',
 ]);
 export const STEPS = [
-    { name: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false, describe: { zh: '精修文生模型的几何细节', en: 'refine geometry of a text-to-model result' } },
-    { 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) {
@@ -47,9 +46,10 @@ for (const s of STEPS) {
         stepIndex.set(a, s);
 }
 /**
- * `/v3/mesh/edit` is documented but not yet deployed (cn returns 4001). The
- * step stays hidden until the backend ships; set TRIPO_EXPERIMENTAL_MESH_EDIT=1
- * to opt in early. Flip this default once the endpoint is live.
+ * `/v3/mesh/edit` has a reference page that is still left out of the docs
+ * index, and cn returned 4001 when last checked. The step stays hidden; set
+ * TRIPO_EXPERIMENTAL_MESH_EDIT=1 to opt in. Flip this default once the
+ * endpoint is listed and live.
  */
 export function isMeshEditEnabled() {
     return process.env.TRIPO_EXPERIMENTAL_MESH_EDIT === '1';
@@ -171,7 +171,6 @@ export function validateChain(chain, sourceType) {
 }
 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)',
     };

package/dist/knowledge/error-catalog.js

@@ -1,11 +1,11 @@
 /**
- * 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,
- * 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.
+ * itself aligned with openapi-server errors.gen.go). The public docs call
+ * 1000/1001 auth errors while the backend sends 1002 for auth failures and
+ * 1000/1001 for 5xx server errors — so HTTP 401 wins over the code table.
  */
 export const EXIT = {
     OK: 0,
@@ -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: '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 },
+    { 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) {
@@ -58,13 +58,13 @@ export function lookupError(code) {
 }
 /** Map an API error code + HTTP status to a stable CLI exit code. */
 export function exitCodeFor(apiCode, httpStatus) {
+    if (httpStatus === 401)
+        return EXIT.AUTH;
     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)
@@ -78,6 +78,8 @@ export function exitCodeFor(apiCode, httpStatus) {
     return EXIT.FATAL;
 }
 export function isRetryable(apiCode, httpStatus) {
+    if (httpStatus === 401)
+        return false;
     if (apiCode !== undefined) {
         const info = byCode.get(apiCode);
         if (info)