tripo-cli 0.3.2 → 0.4.0

package/README.md

@@ -20,7 +20,7 @@ Works with both Tripo regions from the same install — international (`openapi.
 ## Why this CLI
 
 - **One magic command.** `tripo make <anything>` detects what you gave it — prompt text, an image, 2–4 view images, a model file, a URL, a task id, or `@last` — picks the right endpoint, model, and parameters, then waits and downloads the artifacts. No file_token, no polling loops.
-- **A 3D domain brain, not a thin API wrapper.** Model choice is a fixed rule (low-poly intent or face budget ≤ 20000 → `tripo-p1`, everything else → `tripo-v3.1`), P1's illegal parameters are stripped locally, quad + GLB is rejected before it costs you credits, and 7 scenario presets (`--for game-mobile|game-pc|film|print|ar-web|anim|toy`) encode sane parameters + processing chains + delivery formats.
+- **A 3D domain brain, not a thin API wrapper.** Model choice is a fixed rule (low-poly intent or face budget ≤ 20000 → `tripo-p1`, everything else → `tripo-v3.1`; opt into the P-series preview with `--model tripo-p2` for quad low-poly), P-series illegal parameters are stripped locally, quad + GLB is rejected before it costs you credits, and 7 scenario presets (`--for game-mobile|game-pc|film|print|ar-web|anim|toy`) encode sane parameters + processing chains + delivery formats.
 - **Agent-native.** Non-TTY runs are automatically headless (`--json --yes --no-open`), stdout carries exactly one JSON line per command, progress goes to stderr, exit codes are stable, and NDJSON pipes compose: `tripo make cat.png | tripo model texture | tripo anim rig`. An LLM-facing skill package ships inside the npm package (`tripo docs --llm`).
 
 ## Commands

package/dist/ai/experts.js

@@ -7,12 +7,12 @@
  * result is re-validated locally before anything is spent.
  */
 import { getLocale, t, tList } from '../i18n.js';
-import { parseThenExpression, validateChain, STEPS } from '../knowledge/chains.js';
+import { availableSteps, parseThenExpression, validateChain } from '../knowledge/chains.js';
 import { chooseModel, detectLowPolyIntent, RIG_MODEL_V25 } from '../knowledge/models.js';
 import { getScenario, SCENARIOS } from '../knowledge/scenarios.js';
 import { chatJson } from './llm.js';
 const SCENARIO_TABLE = SCENARIOS.map((s) => `- ${s.id}: ${s.description.en} | model=${s.model} | chain=${s.chain.map((c) => c.step).join('→') || 'none'} | deliver=${s.deliverables.join('/')}`).join('\n');
-const STEP_TABLE = STEPS.map((s) => s.name).join(', ');
+const STEP_TABLE = availableSteps().map((s) => s.name).join(', ');
 const PRODUCER_SYSTEM = `You are the producer/router of the Tripo 3D generation CLI.
 Classify the user's request into exactly one scenario and extract a clean English 3D generation prompt.
 

package/dist/commands/completion.js

@@ -1,5 +1,6 @@
 /** `tripo completion <shell>` — static shell completion scripts. */
 import { UsageError } from '../core/errors.js';
+import { isMeshEditEnabled } from '../knowledge/chains.js';
 const COMMANDS = [
     'login', 'logout', 'whoami', 'use', 'balance', 'usage', 'topup',
     'make', 'view', 'redo', 'ai',
@@ -10,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', 'smartsegment'],
+    mesh: ['segment', 'complete', 'decimate', ...(isMeshEditEnabled() ? ['edit'] : []), 'smartsegment'],
     task: ['get', 'list', 'watch'],
     files: ['upload'],
     batch: ['run'],

package/dist/commands/make.js

@@ -18,7 +18,7 @@ export function registerMakeCommand(program) {
         .argument('<input...>', 'prompt text, image file(s), model file, URL, task id, or @last')
         .option('--for <scenario>', `scenario preset: ${scenarioIds().join('|')}`)
         .option('--then <steps>', 'processing chain, e.g. "texture,rig,convert:fbx"')
-        .option('--model <model>', 'force model version (tripo-v3.1 / tripo-p1 / ...)')
+        .option('--model <model>', 'force model version (tripo-v3.1 / tripo-p1 / tripo-p2 / ...)')
         .option('-n, --candidates <n>', 'generate N candidates in parallel', (v) => Number(v), 1)
         .option('--seed <n>', 'model_seed for reproducible geometry', (v) => Number(v));
     withTaskOptions(cmd);

package/dist/commands/mcp.js

@@ -26,7 +26,7 @@ const TOOLS = [
                 input: { type: 'string', description: 'prompt text, image file path, image URL, or task id' },
                 scenario: { type: 'string', enum: scenarioIds(), description: 'production scenario preset' },
                 then: { type: 'string', description: 'processing chain, e.g. "texture,rig,convert:fbx"' },
-                model: { type: 'string', description: 'force model: tripo-v3.1 or tripo-p1' },
+                model: { type: 'string', description: 'force model: tripo-v3.1, tripo-p1 or tripo-p2 (P-series preview with quad)' },
                 output_dir: { type: 'string', description: 'directory for artifacts' },
             },
             required: ['input'],

package/dist/commands/process-groups.js

@@ -9,7 +9,7 @@ import { log, warn } from '../core/output.js';
 import { buildStepRequest } from '../core/requests.js';
 import { resolveInputValue, runTask } from '../core/task-service.js';
 import { t } from '../i18n.js';
-import { getStep } from '../knowledge/chains.js';
+import { getStep, isMeshEditEnabled } from '../knowledge/chains.js';
 import { readPipedTask } from '../pipeline/stdin.js';
 import { newClient, printTaskResult, withTaskOptions } from './shared.js';
 async function resolveStepInput(client, raw) {
@@ -84,6 +84,8 @@ function collectStepArgs(step, flags) {
             return pick(['completion_mode']);
         case 'smartsegment':
             return pick(['seg_type', 'granularity', 'hint']);
+        case 'edit':
+            return pick(['bbox', 'face_limit', 'ref_image', 'model']);
         default:
             return {};
     }
@@ -157,6 +159,22 @@ export function registerProcessCommands(program) {
         .option('--face-limit <n>', 'target faces 500–20000 tri / 500–10000 quad', (v) => Number(v))
         .option('--quad', 'quad output')
         .option('--no-bake', 'skip baking textures onto the low-poly')).action(makeStepAction('decimate'));
+    // Hidden until /v3/mesh/edit is live server-side (see isMeshEditEnabled).
+    if (isMeshEditEnabled()) {
+        withTaskOptions(mesh
+            .command('edit [input]')
+            .description('local retry/refine inside a bounding box (P2 pipeline, model P2-20260801)')
+            .option('--bbox <x1,y1,z1,x2,y2,z2>', 'required 2×3 axis-aligned bbox in model space')
+            .option('--face-limit <n>', 'output face limit (≥100)', (v) => Number(v))
+            .option('--ref-image <file-or-url>', 'reference image for semantic guidance')
+            .option('--model <v>', 'P2-20260801 (only supported value)')).action(async (input, flags) => {
+            // --ref-image may be a local file: upload it to a file_token first.
+            if (typeof flags.refImage === 'string') {
+                flags.refImage = (await resolveInputValue(newClient(), flags.refImage)).value;
+            }
+            await makeStepAction('edit')(input, flags);
+        });
+    }
     withTaskOptions(mesh
         .command('smartsegment [input]')
         .description('smart segmentation (image or model pipeline)')

package/dist/core/requests.js

@@ -5,7 +5,7 @@
  * `parameters`), so new API options work without a CLI release.
  */
 import { getStep } from '../knowledge/chains.js';
-import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateRetargetParams, } from '../knowledge/params.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 { UsageError } from './errors.js';
 function ensure(result) {
@@ -135,6 +135,13 @@ export function buildStepRequest(stepName, input, args) {
             warnings.push(...v.warnings);
             break;
         }
+        case 'edit': {
+            const v = validateMeshEditParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
         case 'rig': {
             // Marketing names (rig-v1.0/rig-v2.0) are rejected by the server; normalize to wire versions.
             params.model = params.model === undefined

package/dist/knowledge/chains.js

@@ -16,6 +16,7 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'highpoly_to_lowpoly',
     'mesh_segmentation',
     'mesh_completion',
+    'mesh_edit',
     'animate_rig',
     'animate_retarget',
 ]);
@@ -31,6 +32,8 @@ export const STEPS = [
     { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true },
     { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false },
     { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'] },
+    // 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 },
     // 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.
@@ -42,8 +45,25 @@ for (const s of STEPS) {
     for (const a of s.aliases ?? [])
         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.
+ */
+export function isMeshEditEnabled() {
+    return process.env.TRIPO_EXPERIMENTAL_MESH_EDIT === '1';
+}
+const EXPERIMENTAL_STEPS = new Set(['edit']);
+function isStepAvailable(def) {
+    return !EXPERIMENTAL_STEPS.has(def.name) || isMeshEditEnabled();
+}
+/** Steps usable right now (experimental ones only when opted in). */
+export function availableSteps() {
+    return STEPS.filter(isStepAvailable);
+}
 export function getStep(name) {
-    return stepIndex.get(name);
+    const def = stepIndex.get(name);
+    return def && isStepAvailable(def) ? def : undefined;
 }
 /**
  * Parse a --then expression: "texture,rig,convert:fbx" or
@@ -68,7 +88,7 @@ export function parseThenExpression(expr) {
                 applyArg(prev.args, part);
                 continue;
             }
-            throw new ChainError(`unknown step "${stepName}" (valid: ${STEPS.map((s) => s.name).join(', ')})`);
+            throw new ChainError(`unknown step "${stepName}" (valid: ${availableSteps().map((s) => s.name).join(', ')})`);
         }
         const args = {};
         const argStr = rest.join(':').trim();
@@ -100,11 +120,13 @@ function applyPrimaryArg(step, args, value) {
         rig: 'rig_type',
         segment: 'model',
         smartsegment: 'granularity',
+        // bbox as "x1/y1/z1/x2/y2/z2" (slashes: commas already separate --then tokens)
+        edit: 'bbox',
     };
     const key = primary[step];
     if (!key)
         throw new ChainError(`step "${step}" does not take a bare argument ("${value}")`);
-    args[key] = coerce(value);
+    args[key] = key === 'bbox' ? value : coerce(value);
 }
 function coerce(raw) {
     if (raw === 'true')

package/dist/knowledge/models.js

@@ -7,12 +7,14 @@
  */
 /**
  * Wire values are what the server actually accepts (backend whitelist:
- * v3.1-20260211, v3.0-20250812, v2.5-20250123, P1-20260311). The friendly
- * `tripo-*` names from marketing docs are CLI-side aliases only — sending
- * them raw returns 400 "invalid model".
+ * v3.1-20260211, v3.0-20250812, v2.5-20250123, P1-20260311, P2-20260801).
+ * The friendly `tripo-*` names from marketing docs are CLI-side aliases only —
+ * sending them raw returns 400 "invalid model".
  */
 export const MODEL_V31 = 'v3.1-20260211';
 export const MODEL_P1 = 'P1-20260311';
+/** P-series upgrade (Preview): adds quad output; explicit --model only, never auto-selected. */
+export const MODEL_P2 = 'P2-20260801';
 /** User-facing aliases normalized to the wire values above. */
 export const MODEL_ALIASES = {
     'v3.1': MODEL_V31,
@@ -22,6 +24,10 @@ export const MODEL_ALIASES = {
     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.
     'v3.0': 'v3.0-20250812',
     'tripo-v3.0': 'v3.0-20250812',
@@ -39,6 +45,10 @@ export const P1_FORBIDDEN_PARAMS = [
     'generate_parts',
     'geometry_quality',
 ];
+/** P2 face_limit windows (official docs): 48–50000 triangles, 48–25000 with quad=true. */
+export const P2_FACE_LIMIT = { min: 48, triMax: 50000, quadMax: 25000 };
+/** Parameters the server rejects for P2 (quad is allowed, unlike P1). */
+export const P2_FORBIDDEN_PARAMS = ['smart_low_poly', 'generate_parts', 'geometry_quality'];
 /** Rig wire versions (backend whitelist; marketing names rig-v1.0/rig-v2.0 are rejected). */
 export const RIG_MODEL_V1 = 'v1.0-20240301';
 export const RIG_MODEL_V25 = 'v2.5-20260210';
@@ -138,6 +148,9 @@ export function normalizeModel(input) {
 export function isP1(model) {
     return normalizeModel(model) === MODEL_P1;
 }
+export function isP2(model) {
+    return normalizeModel(model) === MODEL_P2;
+}
 /** The one rule. Returns the model plus a human-readable reason. */
 export function chooseModel(intent) {
     if (intent.explicit) {

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, P1_FACE_LIMIT, P1_FORBIDDEN_PARAMS, TEXTURE_FORMATS, TEXTURE_QUALITIES, isP1, } from './models.js';
+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';
 const PROMPT_MAX = 1024;
 const NEGATIVE_PROMPT_MAX = 255;
 /** Validate + auto-fix parameters for 3D generation (text/image/multiview-to-model). */
@@ -19,6 +19,26 @@ export function validateGenerationParams(model, input) {
     if (typeof params.negative_prompt === 'string' && params.negative_prompt.length > NEGATIVE_PROMPT_MAX) {
         errors.push(`negative_prompt exceeds ${NEGATIVE_PROMPT_MAX} characters`);
     }
+    // [hard] P-series unsupported params are stripped first, so an unsupported
+    // generate_parts cannot cascade into disabling texture/pbr/quad below.
+    if (isP1(model)) {
+        for (const key of P1_FORBIDDEN_PARAMS) {
+            if (params[key] !== undefined) {
+                delete params[key];
+                warnings.push(key === 'quad'
+                    ? 'P1 does not support quad (removed); need a quad low-poly? use --model tripo-p2'
+                    : `P1 does not support ${key} (removed)`);
+            }
+        }
+    }
+    else if (isP2(model)) {
+        for (const key of P2_FORBIDDEN_PARAMS) {
+            if (params[key] !== undefined) {
+                delete params[key];
+                warnings.push(`P2 does not support ${key} (removed)`);
+            }
+        }
+    }
     // [hard] pbr=true forces texture=true (PBR is a superset of texturing).
     if (params.pbr === true && params.texture === false) {
         params.texture = true;
@@ -33,14 +53,8 @@ export function validateGenerationParams(model, input) {
             }
         }
     }
-    // [hard] P1 constraints: strip forbidden params, enforce face_limit range.
+    // [hard] P1 face_limit range.
     if (isP1(model)) {
-        for (const key of P1_FORBIDDEN_PARAMS) {
-            if (params[key] !== undefined) {
-                delete params[key];
-                warnings.push(`P1 does not support ${key} (removed)`);
-            }
-        }
         const face = params.face_limit;
         if (typeof face === 'number') {
             if (face < P1_FACE_LIMIT.min || face > P1_FACE_LIMIT.max) {
@@ -49,6 +63,18 @@ export function validateGenerationParams(model, input) {
             }
         }
     }
+    else if (isP2(model)) {
+        // [hard] P2 face_limit range: quad halves the budget.
+        const face = params.face_limit;
+        if (typeof face === 'number') {
+            const quad = params.quad === true;
+            const max = quad ? P2_FACE_LIMIT.quadMax : P2_FACE_LIMIT.triMax;
+            if (face < P2_FACE_LIMIT.min || face > max) {
+                errors.push(`P2 face_limit must be within ${P2_FACE_LIMIT.min}–${max}${quad ? ' with quad=true' : ''} (got ${face}); ` +
+                    `use tripo-v3.1 for higher budgets`);
+            }
+        }
+    }
     else {
         // [hard] smart_low_poly face_limit windows: 500–20000 tri / 500–10000 quad.
         if (params.smart_low_poly === true && typeof params.face_limit === 'number') {
@@ -201,3 +227,53 @@ export function validateRetargetParams(input) {
     }
     return { params, warnings, errors };
 }
+const MESH_EDIT_FACE_MIN = 100;
+/**
+ * Normalize a bbox given as [[x,y,z],[x,y,z]], a flat 6-number array, or a
+ * string "x1/y1/z1/x2/y2/z2" (also comma-separated) into the 2×3 wire shape.
+ * Returns undefined when the input is not 6 finite numbers.
+ */
+function normalizeBbox(raw) {
+    let flat;
+    if (typeof raw === 'string') {
+        flat = raw.split(/[/,;\s]+/).filter(Boolean).map(Number);
+    }
+    else if (Array.isArray(raw)) {
+        flat = raw.flat();
+    }
+    else {
+        return undefined;
+    }
+    if (flat.length !== 6 || !flat.every((n) => typeof n === 'number' && Number.isFinite(n)))
+        return undefined;
+    const nums = flat;
+    return [nums.slice(0, 3), nums.slice(3, 6)];
+}
+/** Validate parameters for mesh/edit (P2 pipeline): model fixed to P2, bbox required (2×3), face_limit ≥ 100. */
+export function validateMeshEditParams(input) {
+    const params = { ...input };
+    const warnings = [];
+    const errors = [];
+    const model = params.model === undefined ? MODEL_P2 : normalizeModel(String(params.model));
+    if (model !== MODEL_P2) {
+        errors.push(`mesh edit only supports model ${MODEL_P2} (got "${String(params.model)}")`);
+    }
+    params.model = model;
+    if (params.bbox === undefined) {
+        errors.push('mesh edit requires bbox (x1/y1/z1/x2/y2/z2 or [[x1,y1,z1],[x2,y2,z2]])');
+    }
+    else {
+        const bbox = normalizeBbox(params.bbox);
+        if (!bbox)
+            errors.push('bbox must be 6 finite numbers: x1/y1/z1/x2/y2/z2');
+        else
+            params.bbox = bbox;
+    }
+    if (params.face_limit !== undefined) {
+        const face = params.face_limit;
+        if (typeof face !== 'number' || face < MESH_EDIT_FACE_MIN) {
+            errors.push(`mesh edit face_limit must be an integer ≥ ${MESH_EDIT_FACE_MIN} (got ${String(face)})`);
+        }
+    }
+    return { params, warnings, errors };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.3.2",
+  "version": "0.4.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

@@ -35,8 +35,8 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 3. **Artifacts are local files.** The result JSON has `output_dir`, `model_file`, `preview`. Look at `preview.png` to judge quality; re-roll with `tripo redo` if needed.
 4. **Exit codes are stable** — branch on them:
    - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded) · 7 network · 8 not found · 9 rate limit (retry with backoff)
-5. **Never invent parameters.** Unknown `--param key=value` pairs pass through to the API; stick to documented ones (see `commands/`).
-6. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks.
+5. **Never invent parameters.** Unknown `--param key=value` pairs pass through to the API; stick to documented ones. The full parameter/model/preset reference from the official API docs is bundled: `tripo docs --topic commands/generate` (3D + image generation) and `tripo docs --topic commands/process` (texture/convert/rig/retarget/mesh) — read those instead of browsing the website.
+6. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks (e.g. `--model tripo-p2` for the P-series preview with quad support, or `tripo-v3.0` / `tripo-v2.5` for reproducing old projects).
 
 ## The one command you usually need
 

package/skill/commands/generate.md

@@ -1,6 +1,7 @@
 # tripo generate — deterministic endpoint access
 
 Use `tripo make` unless you need exact endpoint control. All subcommands accept the shared task options (`--json --yes -o --no-wait --no-download --timeout --name -p key=value`).
+Everything below is the full parameter reference from the official API docs — you should not need to consult the website.
 
 ## 3D
 
@@ -10,14 +11,59 @@ tripo generate image-to-model photo.png [-p texture_alignment=original_image] [-
 tripo generate multiview-to-model front.png back.png [left.png right.png]
 ```
 
-Key params (hard rules enforced locally):
-- `pbr=true` implies `texture=true`
-- `generate_parts=true` excludes texture/pbr/quad (bare geometry; re-texture afterwards)
-- `quad=true` forces FBX output (quads cannot be stored in GLB)
-- P1: `face_limit` 50–20000; `quad`/`smart_low_poly`/`generate_parts`/`geometry_quality` unsupported
-- model aliases (`tripo-v3.1`/`tripo-p1`/`v3.0`/`v2.5`) are normalized to server wire versions automatically
-- `smart_low_poly=true`: face_limit 500–20000 (500–10000 with quad)
-- seeds: `image_seed` / `model_seed` / `texture_seed` — record them for reproducibility (task.json does this automatically)
+### 3D models (`--model`)
+
+| alias | wire value sent | positioning | notes |
+| --- | --- | --- | --- |
+| `tripo-v3.1` (default) | `v3.1-20260211` | latest high-precision; AAA / 3D printing | full feature set |
+| `tripo-p1` | `P1-20260311` | best low-poly; games / UGC / mobile | face_limit 48–20000 (CLI enforces ≥50); **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; ~2s mesh; extra `export_uv` |
+| `tripo-p2` | `P2-20260801` | P1 upgrade (P series, Preview) | adds `quad` (forces FBX); face_limit 48–50000 tri / 48–25000 quad (validated locally); still **no** `smart_low_poly` `generate_parts` `geometry_quality` (stripped with a warning); credits 100 (no texture) / 110 / 120 / 130 for standard / detailed / extreme. Explicit `--model` only — the CLI never auto-selects it |
+| `tripo-v3.0` / `tripo-v2.5` | `v3.0-20250812` / `v2.5-20250123` | legacy | only when the human asks |
+
+`tripo-turbo` / `tripo-v2.0` appear in some docs but are **not** on the v3 server whitelist (400).
+
+### Parameters (text / image / multiview-to-model)
+
+| param | default | applies to | notes |
+| --- | --- | --- | --- |
+| `prompt` | — | text | ≤1024 chars |
+| `negative_prompt` | — | text | ≤255 chars |
+| `input` | — | image | `file_` token, `http(s)://` URL or `task_` id (e.g. a text-to-image task) — the CLI uploads local files for you |
+| `inputs` | — | multiview | see "multiview inputs" below |
+| `model_seed` / `image_seed` / `texture_seed` | random | all | geometry / text-to-image stage / texture seeds — the key to reproducibility (`task.json` records them) |
+| `face_limit` | adaptive | all | max polycount; P1 48–20000, P2 48–50000 |
+| `texture` | `true` | all | set `false` for bare geometry (print / re-texture later) — saves credits |
+| `pbr` | `true` | all | PBR maps; **forces `texture=true`** |
+| `texture_quality` | `standard` | all | `standard` / `detailed` / `extreme` (price tiers) |
+| `geometry_quality` | `standard` | v3.x | `detailed` = Ultra mode (extra HD credit) |
+| `auto_size` | `false` | all | scale to real-world metres |
+| `quad` | `false` | v3.x, P2 | quad mesh; **forces FBX output** (quads cannot live in GLB) |
+| `smart_low_poly` | `false` | v3.x | hand-crafted-style low-poly; face_limit 500–20000 tri / 500–10000 quad |
+| `generate_parts` | `false` | v3.x | editable segmented parts — see rules below |
+| `compress` | — | v3.x | `geometry` = meshopt compression |
+| `export_orientation` | `+x` | all | forward axis `+x` / `-x` / `+y` / `-y` — see warning below |
+| `export_uv` | `true` | P series only | `false` = faster, smaller file (no UV unwrap) |
+| `enable_image_autofix` | `false` | image | auto-repair low-quality inputs |
+| `texture_alignment` | `original_image` | image, multiview | `original_image` (match the picture) / `geometry` (match the mesh) |
+| `orientation` | `default` | image, multiview | `align_image` = align the model to the input viewpoint |
+
+Only valid when `model >= tripo-v3.0`: `texture_quality` `geometry_quality` `auto_size` `quad` `smart_low_poly` `generate_parts` `compress`.
+
+**`generate_parts` rules (server-enforced):**
+- `texture=true` or `pbr=true` (including simply omitting `texture`, which defaults to true) → request rejected with `1004`. The CLI flips both to `false` for you and warns; re-texture afterwards with `tripo model texture`.
+- `quad=true` → quad is ignored; parts come back as triangle meshes.
+- `smart_low_poly=true` → smart_low_poly wins and **no parts are produced**.
+
+**`export_orientation` warning:** it applies to this generation only. Downstream tasks (texture, rig, retarget, convert, …) do **not** inherit it — they read the model in default orientation and produce a wrongly-oriented result while still reporting `success`. If you will post-process, leave it unset and set `export_orientation` on the final `convert` step instead.
+
+### Multiview inputs
+
+The API accepts three `inputs` shapes (never mix them):
+- **view-key (recommended)**: `[{"front":…},{"back":…}]` with keys `front/left/back/right`; `front` required, ≥2 views, order irrelevant.
+- **legacy positional**: exactly 4 strings `[front, left, back, right]`, `""` skips a slot.
+- **task_id**: `[{"task_id":"<image-to-multiview or edit-multiview task>"}]` to reuse a 4-view sheet (source task must be `success`).
+
+The CLI builds view-key payloads from your files: filename hints (`front|back|left|right`, or 正面/背面/左/右) win; otherwise positional order front, left, back, right. A front view is mandatory.
 
 ## Images (2D pipeline before 3D)
 
@@ -29,6 +75,29 @@ tripo generate edit-multiview <multiview-task-id> -p 'prompts=[{"view":"front","
 tripo generate image-to-splat photo.png         # gaussian splat
 ```
 
-- image models: `seedream_v4` (t2i default) `seedream_v5` (i2i default) `banana` `banana_pro` `banana2` `chat_image_1` `chat_image_1.5` `chat_image_2`
-- templates — text-to-image: `asset_extraction character_completion t_pose variants figure`; image-to-image: `t_pose character_completion 3d_enhance variants figure`
-- `template=t_pose` is the golden pre-step for the animation pipeline
+### Image models (`--model`)
+
+| model | provider | notes |
+| --- | --- | --- |
+| `seedream_v4` | ByteDance | text-to-image default (balanced); **not accepted by image-to-image** |
+| `seedream_v5` | ByteDance | image-to-image default; higher quality |
+| `gemini-2.5-flash` / `gemini-3-pro` / `gemini-3.1-flash` | Google | fast / high quality / latest fast. Backend aliases `banana` / `banana_pro` / `banana2` are also accepted |
+| `chat_image_1` / `chat_image_1.5` / `chat_image_2` | OpenAI | GPT image; 1.5 = higher quality, 2 = latest |
+
+### Image parameters
+
+| param | default | endpoint | notes |
+| --- | --- | --- | --- |
+| `prompt` | — | t2i (required), i2i | ≤1024 chars; i2i: required unless `template` is set |
+| `input` | — | i2i, i2mv, edit-mv, splat | `file_` token / URL (i2i also accepts a `task_` id) |
+| `inputs` | — | i2i | multiple reference images: seedream ≤4, gemini ≤10 (gpt ≤16); reference them in the prompt as `[image 1]`, `[image 2]`… |
+| `template` | — | t2i, i2i | `asset_extraction` `character_completion` `t_pose` `head_extraction` `3d_enhance` `variants` `print_clay` `figure` |
+| `t_pose` | `false` | t2i, i2i | boolean shortcut: convert the subject to a T-pose |
+| `sketch_to_render` | `false` | t2i, i2i | turn a sketch into a rendered image |
+| `model_seed` | random | splat | same seed + same image = repeatable `.splat` |
+
+- `template=t_pose` (or `t_pose=true`) is the golden pre-step for the animation pipeline; `3d_enhance` cleans a photo before image-to-model; `print_clay` previews a single-colour print look.
+- Sizes are billed in 1K / 2K / 4K tiers; `aspect_ratio` is only honoured by the gemini family.
+- `image-to-multiview` output: `front_view_url` `left_view_url` `back_view_url` `right_view_url` — feed them (or the task id, see above) to `multiview-to-model`.
+- `edit-multiview` takes a successful `image-to-multiview` task; `prompts` is 1–4 `{view, prompt}` objects.
+- `image-to-splat` returns a `.splat` file in `output.model_url` (not a mesh — no texture / rig / convert downstream). Fixed **30 credits**, ~4 minutes. Input PNG / JPEG / WebP ≤20 MB, ≥256×256 px, subject clear and centred. Use image-to-model when you need an editable mesh.

package/skill/commands/make.md

@@ -20,7 +20,7 @@ tripo make <input...> [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.
-- `--model <m>` — force `tripo-v3.1` (high fidelity, default) or `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311`) the server actually accepts.
+- `--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.
 - `-n, --candidates <n>` — up to 4 parallel candidates with different seeds (interactive pick when chaining).
 - `--seed <n>` — fixed model_seed for reproducible geometry.
 - `-p, --param key=value` — extra API parameter, repeatable. Common: `texture=false pbr=false` (bare geometry, cheaper), `texture_quality=detailed`, `face_limit=15000`, `quad=true` (forces FBX), `auto_size=true`, `negative_prompt=...`.

package/skill/commands/process.md

@@ -2,6 +2,7 @@
 
 All subcommands take input as: explicit argument (task id / @last / @name / file / URL) > piped stdin JSON > `@last`.
 Shared options: `--json --yes -o --no-wait --no-download --timeout --name -p key=value`.
+Any API parameter without a first-class flag can be passed with `-p key=value` (JSON values allowed: `-p 'part_names=["head","body"]'`).
 
 ## tripo model
 
@@ -17,7 +18,37 @@ tripo model convert [input] --format GLTF|USDZ|FBX|OBJ|STL|3MF \
 tripo model import <file-or-url>            # GLB/GLTF/FBX/OBJ/STL ≤150MB
 ```
 
-Notes: quad cannot export GLTF; vertex colors only in OBJ/GLTF; any non-default convert option bills as "complex convert".
+| step | input accepted | params |
+| --- | --- | --- |
+| `refine` | successful `text_to_model` task only | `model` (default `tripo-v3.1`) |
+| `texture` | task / file / URL (file/URL is imported implicitly) | `model` `v3.0-20250812` (default) / `v2.5-20250123`; `texture_quality` standard/detailed/extreme; `pbr` (default true); `texture_seed`; `texture_alignment` original_image/geometry |
+| `stylize` | task / file (no URL) | `style` lego/voxel/voronoi/minecraft; `block_size` 32–128 (minecraft only, default 80) |
+| `convert` | task / file | see table below; `format` required |
+| `import` | file / URL | GLB / GLTF / FBX / OBJ / STL ≤150 MB. `.gltf` references external files, so it only works as a URL — upload `.glb` |
+
+### convert parameters (full)
+
+| group | param | default | notes |
+| --- | --- | --- | --- |
+| basic | `format` | — | `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single colour) |
+| mesh | `quad` | false | quad remesh; **cannot export GLTF** — use FBX/OBJ/USDZ |
+| mesh | `force_symmetry` | false | only with `quad=true` |
+| mesh | `face_limit` | keep original | target polycount |
+| mesh | `flatten_bottom` / `flatten_bottom_threshold` | false / 0.01 | flat base for printing |
+| texture | `texture_size` | 4096 | diffuse size in px |
+| texture | `texture_format` | JPEG | `BMP` `DPX` `HDR` `JPEG` `OPEN_EXR` `PNG` `TARGA` `TIFF` `WEBP` |
+| texture | `bake` | true | bake advanced materials into base textures |
+| texture | `pack_uv` | false | pack all UVs into one layout |
+| texture | `export_vertex_colors` | false | **OBJ / GLTF only** |
+| export | `pivot_to_center_bottom` | false | pivot at bottom centre |
+| export | `scale_factor` | 1 | uniform scale |
+| export | `with_animation` | true | keep skeleton + animation data |
+| export | `animate_in_place` | false | strip root motion |
+| export | `part_names` | — | export only these parts (names from a segment task) |
+| export | `export_orientation` | `+x` | forward axis `+x` / `-x` / `+y` / `-y` — set orientation **here**, as the last step (generation-time `export_orientation` is not inherited by other steps) |
+| export | `fbx_preset` | blender | `blender` / `3dsmax` / `mixamo` (FBX only) |
+
+Billing: any non-default convert option bills as "complex convert" (pricier than a plain format swap).
 
 ## tripo anim
 
@@ -29,12 +60,32 @@ tripo anim retarget [input] --animation preset:walk [preset:run ...] \
     [--out-format glb|fbx] [--animate-in-place]
 ```
 
-- retarget only accepts a rig task id; ≤5 animations, billed per animation
-- rig model wire versions: `v2.5-20260210` (CLI default) / `v1.0-20240301`; marketing names `rig-v1.0`/`rig-v2.0` are normalized automatically
-- v2.5 rig presets (all body types): `preset:idle walk run dive climb jump slash shoot hurt fall turn` (+ body-specific like `preset:quadruped:*`)
-- v1.0 rig presets (biped only): `preset:biped:idle` etc. (90+)
-- Mixamo/Unity Humanoid → `--spec mixamo` (+ `--fbx-preset mixamo` at convert time)
-- game code drives movement → `--animate-in-place`
+| step | input accepted | params |
+| --- | --- | --- |
+| `check` (rig-check) | task / file / URL — **GLB only**, ≤150 MB | none. Output: `riggable` (bool) + recommended `rig_type` (one of the 7 below). Run it first: not riggable → stop before spending rig credits |
+| `rig` | task / file | `model`: `rig-v2.0` (wire `v2.5-20260210`, **CLI default**, presets for all body types) / `rig-v1.0` (wire `v1.0-20240301`, server default, biped-only presets); `rig_type` biped/quadruped/hexapod/octopod/avian/serpentine/aquatic (default biped — use rig-check's value); `spec` tripo/mixamo; `out_format` glb/fbx |
+| `retarget` | **rig task id only** | `animation` (one) or `animations` (list, ≤5, billed per animation); `out_format` glb/fbx; `bake_animation` (default true, glb only); `export_with_geometry` (default true); `animate_in_place` (default false) |
+
+- Marketing names `rig-v1.0` / `rig-v2.0` are normalized to the wire versions automatically (sending them raw is a 400).
+- Mixamo / Unity Humanoid → `--spec mixamo` (+ `--fbx-preset mixamo` at convert time).
+- Game code drives movement → `--animate-in-place`.
+- The preset set depends on **which rig model the upstream rig task used**.
+
+### Presets for rig v2.0 / v2.5 (all rig types)
+
+`preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` `preset:fall` `preset:turn`
+Body-specific: `preset:quadruped:walk` `preset:hexapod:walk` `preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march`
+
+### Presets for rig v1.0 (biped only, 90+)
+
+All prefixed `preset:biped:`
+- basic: `idle` `walk` `run` `run_upstairs` `turn` `jump` `jump_down` `jump_rope_01` `jump_rope_02` `fall` `climb` `dive` `swim` `surf` `flip` `sit` `standing_relax` `look_around` `wait` `swagger`
+- dance: `dance_01` … `dance_06` `freaky`
+- performance: `sing_01` … `sing_04` `cheer`
+- emotion: `clap` `bow` `greet_01` … `greet_04` `wave_goodbye_01` `wave_goodbye_02` `agree` `heart_pose` `hug` `fold_arms` `laugh_01` `laugh_02` `cry` `sob` `afraid` `frightened` `scared_01` `scared_02` `angry_01` … `angry_03` `depressed` `frustrated_01` `frustrated_02` `complain_01` `complain_02` `victory_celebration` `defeat_02` `defeat_03`
+- daily: `scratch` `make_a_call_01` `make_a_call_02` `play_mobile_game` `play_video_game` `dig` `chop` `shovel` `lift_heavy`
+- sports: `warm_up` `press-up` `cross_body_crunch` `basketball_shot` `crossover_dribble` `dribble` `pitch_baseball` `golf` `volleyball` `football_catch` `football_save` `football_pass`
+- combat: `box_01` … `box_03` `front_kick_01` `front_kick_02` `slash` `shoot` `fire` `cast_a_spell` `hurt` `hit_to_body_01` `hit_to_body_02` `hit_to_head` `hit_to_side` `hit_to_stomach` `flee_01` `flee_02`
 
 ## tripo mesh
 
@@ -45,6 +96,13 @@ tripo mesh decimate [input] --face-limit 5000 [--quad] [--no-bake]        # 500
 tripo mesh smartsegment <file-or-url> [--seg-type image|model] [--granularity coarse|medium|fine] [--hint "..."]
 ```
 
-- decimate bakes textures onto the low-poly by default (right for LODs); `-p model=v1.0` allows up to 2M faces but requires `face_limit` and does not support bake/part_names
-- `mesh complete` only accepts segmentation tasks
-- smartsegment takes a file/URL only (no task ids); `--seg-type model` needs a GLB and a 4×4 transform — the CLI auto-fills the identity matrix
+| step | input accepted | params |
+| --- | --- | --- |
+| `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 |
+| `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=[...]'`.

package/skill/common-errors.md

@@ -4,8 +4,9 @@
 | --- | --- | --- | --- |
 | 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 |
-| 9 | 1007/2000 | rate or concurrency limit (task families share pools) | wait and retry with backoff; lower `--concurrency` in batch |
+| 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 |
+| 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)? |
 | 2 | 2003 | empty input file / unreachable URL | verify the file isn't empty and the URL is publicly accessible |
 | 2 | 2004 | unsupported file type | images: PNG/JPEG/WebP/BMP/TIFF ≤20MB; models: GLB/FBX/OBJ/STL ≤150MB (.gltf not uploadable — use .glb or a URL) |
@@ -22,6 +23,19 @@
 | 6 | — | task failed server-side | frozen credits auto-refund; `tripo redo` often succeeds with a new seed |
 | 7 | — | network/5xx | auto-retried 3×; check `tripo doctor`; region mismatch (ov/cn) is a common cause |
 
+## Concurrency pools (default per account; error 2000 when full)
+
+| category | task types | default concurrency |
+| --- | --- | --- |
+| 3D generation — H series | text/image/multiview-to-model on `tripo-v3.x` / `v2.5` | 10 |
+| 3D generation — P series | text/image/multiview-to-model on `tripo-p1` / P2 | 5 |
+| image generation | text-to-image, image-to-image, image-to-multiview, edit-multiview | **1** |
+| animation | rig-check, rig, retarget | 10 |
+| model processing | texture, convert, refine | 5 |
+| mesh operations | segment, complete, decimate | 10 |
+
+Pools are independent: a full H-series pool does not block P-series or image tasks. Image generation is serial by default — do not fan out text-to-image jobs. Higher limits are granted on request via support.
+
 ## Frequent local validations (caught before spending credits)
 
 - `refine` only accepts a successful `text_to_model` task
@@ -36,3 +50,8 @@
 - `model_url` in task output points to a file that may be named `pbr_model` etc. — normal, just download it (the CLI does).
 - Output URLs expire in ~5 minutes — never cache them; re-run `tripo task get <id> --download`.
 - `frozen` balance = holds for running tasks; it settles or refunds automatically.
+- `credits_consumed` / `balance` / `frozen` are decimals (e.g. `48.00`) — parse as float, never as int.
+- Task status can also be `banned` (content policy — change the input) or `expired` (output files gone — regenerate); the CLI treats both as terminal failures.
+- 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.