tripo-cli 0.5.2 → 0.6.0

package/README.md

@@ -35,7 +35,7 @@ Works with both Tripo regions from the same install — international (`openapi.
 | `tripo login / logout / whoami / use` | device flow: browser approves, key arrives automatically (paste fallback); stored 0600 in `~/.tripo/config.json`; `use` switches accounts |
 | `tripo topup / balance / usage` | open the billing page + detect the credits arriving; check spend |
 | `tripo generate <endpoint>` | deterministic access to all 8 generation endpoints |
-| `tripo model / anim / mesh <step>` | refine, texture, stylize, convert, import, rig-check, rig, retarget, segment, complete, decimate, smartsegment |
+| `tripo model / anim / mesh <step>` | refine, texture, stylize, convert, import, rig-check, rig, retarget, segment, complete, decimate, uv, smartsegment |
 | `tripo task get/list/watch` | query and stream task progress (NDJSON in `--json` mode) |
 | `tripo files upload` | upload a file, print the `file_token` |
 | `tripo batch run <manifest.yaml>` | bulk pipelines with concurrency, retries, and resume |

package/dist/commands/completion.js

@@ -11,7 +11,7 @@ const SUBS = {
     generate: ['text-to-model', 'image-to-model', 'multiview-to-model', 'text-to-image', 'image-to-image', 'image-to-multiview', 'edit-multiview', 'image-to-splat'],
     model: ['refine', 'texture', 'stylize', 'convert', 'import'],
     anim: ['check', 'rig', 'retarget'],
-    mesh: ['segment', 'complete', 'decimate', ...(isMeshEditEnabled() ? ['edit'] : []), 'smartsegment'],
+    mesh: ['segment', 'complete', 'decimate', 'uv', ...(isMeshEditEnabled() ? ['edit'] : []), 'smartsegment'],
     task: ['get', 'list', 'watch'],
     files: ['upload'],
     batch: ['run'],

package/dist/commands/process-groups.js

@@ -77,7 +77,9 @@ function collectStepArgs(step, flags) {
         case 'retarget':
             return pick(['animation', 'out_format', 'animate_in_place']);
         case 'decimate':
-            return pick(['face_limit', 'quad', 'bake']);
+            return pick(['model', 'face_limit', 'quad', 'smart_uv', 'bake']);
+        case 'uv':
+            return pick(['bake', 'export_orientation']);
         case 'segment':
             return pick(['model']);
         case 'complete':
@@ -147,7 +149,7 @@ export function registerProcessCommands(program) {
         await makeStepAction('retarget')(input, flags);
     });
     // ---- tripo mesh ----
-    const mesh = program.command('mesh').description('mesh ops: segment / complete / decimate / smartsegment');
+    const mesh = program.command('mesh').description('mesh ops: segment / complete / decimate / uv / smartsegment');
     withTaskOptions(mesh.command('segment [input]').description('segment a model into parts').option('--model <v>', 'v1.0-20250506|v2.0-20260430')).action(makeStepAction('segment'));
     withTaskOptions(mesh
         .command('complete [input]')
@@ -156,9 +158,16 @@ export function registerProcessCommands(program) {
     withTaskOptions(mesh
         .command('decimate [input]')
         .description('high-poly → low-poly (bakes textures by default)')
+        .option('--model <v>', 'v3.0|v2.0|v1.0 (default v2.0)')
         .option('--face-limit <n>', 'target faces 500–20000 tri / 500–10000 quad', (v) => Number(v))
         .option('--quad', 'quad output')
+        .option('--smart-uv', 'unwrap UVs in the same task (v3.0 only; selects v3.0 when --model is omitted)')
         .option('--no-bake', 'skip baking textures onto the low-poly')).action(makeStepAction('decimate'));
+    withTaskOptions(mesh
+        .command('uv [input]')
+        .description('smart UV unwrap; remaps textures/rig/animation (input ≤80k equivalent triangles)')
+        .option('--no-bake', 'skip baking textures onto the new UV layout (geometry + UVs only)')
+        .option('--export-orientation <o>', '+x|-x|+y|-y')).action(makeStepAction('uv'));
     // Hidden until /v3/mesh/edit is live server-side (see isMeshEditEnabled).
     if (isMeshEditEnabled()) {
         withTaskOptions(mesh

package/dist/core/download.js

@@ -73,7 +73,8 @@ export async function downloadArtifacts(task, outputDir, historyEntry, options =
         const ext = extname(name).toLowerCase();
         if (!modelFile && MODEL_EXTS.has(ext))
             modelFile = dest;
-        if (!preview && (IMAGE_EXTS.has(ext) || /rendered|preview/i.test(field)))
+        // uv_render (mesh/uv) is a flat UV atlas, not a render of the model.
+        if (!preview && !/uv_render/.test(field) && (IMAGE_EXTS.has(ext) || /rendered|preview/i.test(field)))
             preview = dest;
     }
     // Normalize the preview name so agents can rely on preview.png existing.

package/dist/knowledge/chains.js

@@ -17,6 +17,7 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'mesh_segmentation',
     'mesh_completion',
     'mesh_edit',
+    'mesh_uv',
     'animate_rig',
     'animate_retarget',
 ]);
@@ -32,6 +33,7 @@ export const STEPS = [
     { 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' } },
     // 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)' } },
     // smartsegment's `input` is file_token/URL only (the server does not resolve

package/dist/knowledge/models.js

@@ -109,7 +109,7 @@ 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'];
+export const DECIMATE_MODELS = ['v3.0', 'v2.0', 'v1.0'];
 /** Server whitelists differ per endpoint (ImageGenerationValidation). */
 export const TEXT_TO_IMAGE_TEMPLATES = [
     'asset_extraction',

package/dist/knowledge/params.js

@@ -5,7 +5,7 @@
  * 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, MODEL_P2, P1_FACE_LIMIT, P1_FORBIDDEN_PARAMS, P2_FACE_LIMIT, P2_FORBIDDEN_PARAMS, TEXTURE_FORMATS, TEXTURE_QUALITIES, isP1, isP2, normalizeModel, } from './models.js';
+import { CONVERT_FORMATS, DECIMATE_MODELS, EXPORT_ORIENTATIONS, FBX_PRESETS, MODEL_P2, P1_FACE_LIMIT, P1_FORBIDDEN_PARAMS, P2_FACE_LIMIT, P2_FORBIDDEN_PARAMS, TEXTURE_FORMATS, TEXTURE_QUALITIES, isP1, isP2, normalizeModel, } from './models.js';
 const PROMPT_MAX = 1024;
 const NEGATIVE_PROMPT_MAX = 255;
 /** Validate + auto-fix parameters for 3D generation (text/image/multiview-to-model). */
@@ -168,7 +168,8 @@ export function validateConvertParams(input) {
 }
 /**
  * Validate parameters for mesh/decimate (ModelPostProcessValidation):
- * v2.0 (default): face_limit 500–20000 tri / 500–10000 quad.
+ * v2.0 (default) / v3.0: face_limit 500–20000 tri / 500–10000 quad.
+ * v3.0 only: smart_uv (UV unwrap in the same task).
  * v1.0: face_limit REQUIRED, 500–2,000,000 tri / 500–150,000 quad; no bake/part_names.
  */
 export function validateDecimateParams(input) {
@@ -176,8 +177,18 @@ export function validateDecimateParams(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)}")`);
+    if (model !== undefined && model !== 'default' && !DECIMATE_MODELS.includes(model)) {
+        errors.push(`decimate model must be ${DECIMATE_MODELS.join('/')} (got "${String(params.model)}")`);
+    }
+    // [hard] smart_uv is v3.0-only (server: 1004 on v1.0/v2.0); [soft] no model given → v3.0.
+    if (params.smart_uv === true) {
+        if (model === undefined) {
+            params.model = 'v3.0';
+            warnings.push('smart_uv requires decimate v3.0: using model=v3.0 (35 credits tri / 40 quad; v2.0 is 30)');
+        }
+        else if (model !== 'v3.0') {
+            errors.push(`smart_uv only works with decimate model v3.0 (got "${String(params.model)}")`);
+        }
     }
     const isV1 = model === 'v1.0';
     const quad = params.quad === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Tripo 3D intelligent CLI — turn a prompt or an image into engine-ready 3D assets from your terminal (Tripo V3 API)",
   "keywords": [
     "tripo",

package/skill/SKILL.md

@@ -50,7 +50,7 @@ tripo make @last --then convert:fbx --json --yes          # continue from last t
 ```
 
 - `--for` scenario presets: `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`
-- `--then` chain steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate smartsegment`
+- `--then` chain steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate uv smartsegment`
   - step args: `convert:format=FBX,texture_size=2048` (bare value = primary arg: `convert:fbx`, `stylize:lego`, `decimate:5000`)
 - Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["preview"],["chain"],["credits_breakdown"]}` — with `--then`, `credits_consumed` is the **total** for the run and `credits_breakdown` itemizes every task (`[{task_id,type,credits_consumed}]`, generation first)
 

package/skill/commands/make.md

@@ -40,7 +40,7 @@ In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no
 ## Options
 
 - `--for <scenario>` — `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`. Sets model+params+chain+format from the domain knowledge base.
-- `--then <steps>` — processing chain, comma-separated. Steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `stylize:lego` → style, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
+- `--then <steps>` — processing chain, comma-separated. Steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate uv smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `stylize:lego` → style, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
 - `--model <m>` — force `tripo-v3.1` (high fidelity, default), `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped) or `tripo-p2` (P-series preview; adds quad, face_limit 48–50000 tri / 48–25000 quad; never auto-selected). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311` / `P2-20260801`) the server actually accepts. Full table with status (GA / Preview / Legacy) and official links: `tripo docs --topic commands/generate` → "Models & Versions".
 - `-n, --candidates <n>` — up to 4 parallel candidates with different seeds (interactive pick when chaining).
 - `--seed <n>` — fixed model_seed for reproducible geometry.

package/skill/commands/process.md

@@ -92,7 +92,8 @@ All prefixed `preset:biped:`
 ```bash
 tripo mesh segment [input] [--model v1.0-20250506|v2.0-20260430]
 tripo mesh complete [input] [--completion-mode ai_completion|quick_cap]   # needs a segment task
-tripo mesh decimate [input] --face-limit 5000 [--quad] [--no-bake]        # 500–20000 tri / 500–10000 quad
+tripo mesh decimate [input] --face-limit 5000 [--model v3.0|v2.0|v1.0] [--quad] [--smart-uv] [--no-bake]   # 500–20000 tri / 500–10000 quad
+tripo mesh uv [input] [--no-bake] [--export-orientation +x|-x|+y|-y]     # input ≤ 80,000 equivalent triangles
 tripo mesh smartsegment <file-or-url> [--seg-type image|model] [--granularity coarse|medium|fine] [--hint "..."]
 ```
 
@@ -100,9 +101,12 @@ tripo mesh smartsegment <file-or-url> [--seg-type image|model] [--granularity co
 | --- | --- | --- |
 | `segment` | task / file / URL | `model` `v1.0-20250506` (default, geometry-based) / `v2.0-20260430` (Beta, semantic labels + geometry). **v2 only**: `segmentation_granularity` simple/balanced/detailed (default balanced), `split_by_connectivity` (default true), `ref_image` file_token/URL — when `ref_image` is set the other two are ignored; setting `ref_image` on v1 → `1004` |
 | `complete` | **segment task only** | `completion_mode` `ai_completion` (AI diffusion, default) / `quick_cap` (fast hole-fill, no AI); `part_names` (default: all parts); `model` `v1.0-20250506` (only version) |
-| `decimate` | task / file | `face_limit` (docs quote 1000–20000; CLI accepts 500–20000 tri / 500–10000 quad); `quad`; `bake` (default true — bake textures onto the low-poly, right for LODs); `part_names`. `-p model=v1.0`: up to 2,000,000 tri / 150,000 quad but `face_limit` becomes required and `bake`/`part_names` are unsupported |
+| `decimate` | task / file / URL | `model` `v2.0` (default, smart retopology, 30 credits) / `v3.0` (newest retopology, 35 credits tri / 40 quad) / `v1.0` (basic decimation, 10 credits); `face_limit` (v2.0/v3.0: optional, 500–20000 tri / 500–10000 quad, adaptive if omitted); `quad`; `bake` (default true — bake textures onto the low-poly, right for LODs); `part_names`; `smart_uv` (**v3.0 only**, default false — unwrap UVs in the same task, no extra cost, no UV atlas image; `--smart-uv` without `--model` selects v3.0, an explicit v1.0/v2.0 is rejected locally because the server answers `1004`). `--model v1.0`: up to 2,000,000 tri / 150,000 quad but `face_limit` becomes required and `bake`/`part_names` are unsupported |
+| `uv` | task / file / URL | re-unwraps UVs and remaps the existing textures, rig and animation onto the new layout; **20 credits**. `bake` (default true; `--no-bake` returns geometry + UVs only); `export_orientation` `+x`/`-x`/`+y`/`-y`; `compress` `geometry` (meshopt, `-p compress=geometry`); `model` `default` (only value). **Input ≤ 80,000 equivalent triangles** (a quad counts as two): larger inputs are accepted, then the task fails and refunds — decimate first |
 | `smartsegment` | **file / URL only (no task ids)** | `seg_type` `image` (photo → auto-model → segment, **85 credits**) / `model` (existing **GLB only** → segment, **55 credits**; CLI default); `granularity` coarse/medium/fine (default medium); `hint` free text describing the parts; `transform` 4×4 column-major matrix required for `model` — the CLI auto-fills identity |
 
 - `segment` vs `smartsegment`: segment only splits an existing model; smartsegment is the end-to-end pipeline (asset → auto modelling → segmentation).
 - smartsegment output: `prompt` (comma-separated part labels), `mask_url` (PNG semantic mask), `seg_model_url` (segmented GLB), `seg_task_id` (inner segmentation task), `model_task_id` (inner image_to_model / import task). Task types: `smartsegment_image` / `smartsegment_model`.
 - `mesh complete` only accepts segmentation tasks; segmented / completed parts can then be exported selectively via `convert -p 'part_names=[...]'`.
+- UVs in one task or two: `decimate --smart-uv` (v3.0) unwraps during retopology — one task, no atlas image. `uv` is its own task that also returns the UV atlas; run it on models that are already under the limit, e.g. `--then decimate:20000,uv`.
+- uv output: the model plus `uv_render.webp` (the UV atlas). It is a flat layout, not a render of the model, so the CLI does not copy it to `preview.png`.

package/skill/common-errors.md

@@ -4,7 +4,7 @@
 | --- | --- | --- | --- |
 | 3 | 1002 | authentication failed (invalid/missing API key) | set `TRIPO_API_KEY` or run `tripo login`; check the key wasn't revoked |
 | 3 | 1005 | forbidden (no permission for this resource) | check account permissions |
-| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, non-GLB input to smartsegment `model` / rig-check. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
+| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, `smart_uv=true` on decimate v1.0/v2.0, non-GLB input to smartsegment `model` / rig-check. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
 | 9 | 1007 | per-API-key rate limit | wait and retry with backoff; honour `Retry-After` / `X-RateLimit-Reset` headers |
 | 9 | 2000 | per-account concurrency pool full (see table below) | wait for a task in that category to finish, or lower `--concurrency` in batch; other categories are unaffected |
 | 8 | 2001 | task not found | task ids are account-scoped — same key that created it? right region (ov/cn)? |
@@ -42,6 +42,7 @@ Pools are independent: a full H-series pool does not block P-series or image tas
 - `complete` only accepts a `segment` task; `retarget` only accepts a `rig` task
 - quad + GLTF export → rejected (quads cannot be stored in glTF); use FBX/OBJ/USDZ
 - P1 + face_limit outside 50–20000 → rejected with a suggestion to use v3.1
+- decimate `smart_uv` on an explicit v1.0/v2.0 → rejected (v3.0 only); with no model given the CLI selects v3.0
 - multiview without a front view → rejected (name a file "front" or pass it first)
 - `-n` with `--then` needs an interactive terminal (pick the winner first, then chain)
 
@@ -57,3 +58,4 @@ All of these surface in `tripo make ... --dry-run --json` as `errors` (blocking)
 - A downstream step after a generation that used `export_orientation` succeeds but comes out **wrongly oriented** — no error is raised. Set the orientation on the final `convert` step instead.
 - `generate_parts` with `smart_low_poly=true` silently produces no parts (smart_low_poly wins); with `quad=true` the parts are triangles.
 - `image-to-splat` yields a `.splat`, not a mesh — texture / rig / convert steps cannot follow it.
+- `uv` accepts any model at creation, but an input over 80,000 equivalent triangles fails at run time (credits refunded) — decimate first: `--then decimate:20000,uv`.