tripo-cli 0.3.2 → 0.5.0

package/dist/knowledge/chains.js

@@ -16,25 +16,28 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'highpoly_to_lowpoly',
     'mesh_segmentation',
     'mesh_completion',
+    'mesh_edit',
     'animate_rig',
     'animate_retarget',
 ]);
 export const STEPS = [
-    { name: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false },
-    { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true },
-    { name: 'stylize', endpoint: '/v3/models/stylize', produces: 'stylize_model', accepts: 'any-model', acceptsFile: true },
-    { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true },
-    { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true },
-    { name: 'rig-check', endpoint: '/v3/animations/rig-check', produces: 'animate_prerigcheck', accepts: 'any-model', acceptsFile: true, passthrough: true, aliases: ['check', 'rigcheck'] },
-    { name: 'rig', endpoint: '/v3/animations/rig', produces: 'animate_rig', accepts: 'any-model', acceptsFile: true },
-    { name: 'retarget', endpoint: '/v3/animations/retarget', produces: 'animate_retarget', accepts: ['animate_rig'], acceptsFile: false, aliases: ['animate'] },
-    { name: 'segment', endpoint: '/v3/mesh/segment', produces: 'mesh_segmentation', accepts: 'any-model', acceptsFile: true },
-    { name: 'complete', endpoint: '/v3/mesh/complete', produces: 'mesh_completion', accepts: ['mesh_segmentation'], acceptsFile: false },
-    { name: 'decimate', endpoint: '/v3/mesh/decimate', produces: 'highpoly_to_lowpoly', accepts: 'any-model', acceptsFile: true, aliases: ['lowpoly'] },
+    { 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: 'stylize', endpoint: '/v3/models/stylize', produces: 'stylize_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '按风格重塑模型(lego/voxel/...)', en: 'restyle the model (lego/voxel/...)' } },
+    { 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' } },
+    // 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
     // 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 },
+    { name: 'smartsegment', endpoint: '/v3/mesh/smartsegment', produces: 'smartsegment_model', accepts: [], acceptsFile: true, describe: { zh: '智能语义分割', en: 'smart semantic segmentation' } },
 ];
 const stepIndex = new Map();
 for (const s of STEPS) {
@@ -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/dist/pipeline/make.js

@@ -53,7 +53,7 @@ export async function planMake(client, options) {
         case 'image':
         case 'url-image': {
             const raw = classified.values[0].value;
-            const { value } = await resolveInputValue(client, raw);
+            const { value } = await resolveInputValue(client, raw, { dryRun: options.dryRun });
             const choice = chooseModel({
                 explicit: options.model ?? scenario?.model,
                 faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
@@ -69,7 +69,7 @@ export async function planMake(client, options) {
             };
         }
         case 'multiview': {
-            const views = await assignViews(client, classified.values.map((v) => v.value));
+            const views = await assignViews(client, classified.values.map((v) => v.value), { dryRun: options.dryRun });
             const choice = chooseModel({
                 explicit: options.model ?? scenario?.model,
                 faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
@@ -86,7 +86,7 @@ export async function planMake(client, options) {
         }
         case 'model': {
             const raw = classified.values[0].value;
-            const { value } = await resolveInputValue(client, raw);
+            const { value } = await resolveInputValue(client, raw, { dryRun: options.dryRun });
             const generation = buildStepRequest('import', value, {});
             if (chain.length === 0) {
                 warnings.push(t({
@@ -116,24 +116,31 @@ export async function planMake(client, options) {
         }
     }
 }
+/**
+ * Chain legality against the plan's upstream task type (throws UsageError).
+ * Skipped when the upstream type is unknown (raw task id without local history).
+ */
+export function checkPlanChain(plan) {
+    if (plan.chain.length === 0)
+        return;
+    const upstream = plan.generation?.taskType ?? plan.sourceType;
+    if (!upstream)
+        return;
+    try {
+        validateChain(plan.chain, upstream);
+    }
+    catch (error) {
+        if (error instanceof ChainError)
+            throw new UsageError(error.message);
+        throw error;
+    }
+}
 /** Execute a plan produced by planMake. */
 export async function executeMake(client, plan, options) {
     for (const w of plan.warnings)
         warn(w);
     // Validate chain legality up front so an illegal plan spends zero credits.
-    if (plan.chain.length > 0) {
-        const upstream = plan.generation?.taskType ?? plan.sourceType;
-        if (upstream) {
-            try {
-                validateChain(plan.chain, upstream);
-            }
-            catch (error) {
-                if (error instanceof ChainError)
-                    throw new UsageError(error.message);
-                throw error;
-            }
-        }
-    }
+    checkPlanChain(plan);
     await precheckBalance(client);
     let sourceTaskId;
     let sourceType;
@@ -195,7 +202,7 @@ export async function executeMake(client, plan, options) {
  * Map 2–4 images to views. Filename hints (front/back/left/right, 前/后/左/右)
  * win; remaining slots fill positionally in [front, left, back, right] order.
  */
-export async function assignViews(client, files) {
+export async function assignViews(client, files, opts = {}) {
     if (files.length < 2 || files.length > 4) {
         throw new UsageError(`multiview needs 2–4 images (got ${files.length})`);
     }
@@ -227,7 +234,7 @@ export async function assignViews(client, files) {
     }
     const resolved = {};
     for (const [view, file] of Object.entries(views)) {
-        resolved[view] = (await resolveInputValue(client, file)).value;
+        resolved[view] = (await resolveInputValue(client, file, { dryRun: opts.dryRun })).value;
     }
     return resolved;
 }

package/package.json

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

@@ -30,13 +30,14 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 
 ## Behavior rules (read first)
 
-1. **`tripo make` is synchronous and blocking.** It submits the task, polls, downloads artifacts, then exits. Wait for the process to finish and read the final JSON from stdout. Do NOT re-implement polling, do NOT add your own timeout shorter than 15 minutes, do NOT stop just because you saw a task_id in the logs.
+1. **`tripo make` is synchronous and blocking.** It prints a plan card on stderr (one numbered line per API call: endpoint, purpose, args), then submits, polls, downloads artifacts, and exits. In a TTY it asks "Run this plan?" first; `--yes` (auto-enabled when headless) skips the prompt but still prints the card. Wait for the process to finish and read the final JSON from stdout. Do NOT re-implement polling, do NOT add your own timeout shorter than 15 minutes, do NOT stop just because you saw a task_id in the logs.
 2. **stdout is the contract; stderr is commentary.** With `--json` (auto-enabled when piped), stdout carries exactly one final JSON line. Progress/logs go to stderr.
 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. **Validate before spending: `--dry-run --json`.** Same command plus `--dry-run` prints the plan as JSON with zero network calls and no credits: the chosen `model`, the completed `steps[].payload` for every API call, `warnings` (auto-adjustments) and `errors` (blocking; exit 2). When `valid` is true, re-run without `--dry-run`. Details: `tripo docs --topic commands/make` § "Dry run".
+7. **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). `tripo-*` names are CLI aliases — the CLI sends the dated wire value (`tripo-p2` → `P2-20260801`); the API rejects the alias itself with 1004. Alias ↔ wire ↔ status table: `tripo docs --topic commands/generate` ("Models & Versions").
 
 ## The one command you usually need
 
@@ -51,7 +52,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`
   - 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"]}`
+- 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)
 
 ## Pipes (composing steps yourself)
 
@@ -77,6 +78,7 @@ tripo make cat.png --json | tripo anim rig --json | tripo anim retarget --param
 ## Detailed docs in this package
 
 - `commands/` — one file per command with every flag and parameter
+  - model versions · H series (`tripo-v3.x`) · P series (`tripo-p1`, `tripo-p2` Preview) · alias → wire value · GA / Preview / Legacy status · quad → `commands/generate` § "Models & Versions" (also the P Series endpoint entry points)
 - `examples/` — copy-paste recipes per scenario (game/print/animation/...)
 - `common-errors.md` — error table with fixes
 

package/skill/commands/generate.md

@@ -1,23 +1,94 @@
 # 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
 
 ```bash
-tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1] [-p face_limit=15000] ...
+tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1|tripo-p2] [-p face_limit=15000] ...
 tripo generate image-to-model photo.png [-p texture_alignment=original_image] [-p orientation=align_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)
+### P Series (`tripo-p1` / `tripo-p2`) — same endpoints, different model
+
+The P series (low-poly, clean topology) uses the **same three endpoints**; only the `model` value changes. The official docs document it as a separate "P Series" tab on each generation page — this is the direct entry point:
+
+```bash
+tripo generate text-to-model "a low poly knight" --model tripo-p1 -p face_limit=8000          # → model: P1-20260311
+tripo generate image-to-model photo.png --model tripo-p2 -p quad=true -p face_limit=12000      # → model: P2-20260801 (Preview)
+tripo generate multiview-to-model front.png back.png --model tripo-p1
+```
+
+| endpoint | H series (standard) page | P series page |
+| --- | --- | --- |
+| `POST /v3/generation/text-to-model` | `…/docs/generation-text-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-text-to-model/p> |
+| `POST /v3/generation/image-to-model` | `…/docs/generation-image-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-image-to-model/p> |
+| `POST /v3/generation/multiview-to-model` | `…/docs/generation-multiview-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-multiview-to-model/p> |
+
+(cn: replace `developers.tripo3d.ai/en` with `developers.tripo3d.com/zh`.) P-series constraints — face_limit ranges, unsupported params, P2's `quad` — are in the table below; the CLI enforces them locally.
+
+### 3D models (`--model`) — Models & Versions
+
+Keywords: model versions · H series (v3.x) · P series (P1 / P2) · Preview · quad · alias → wire value.
+
+| alias (what you type) | wire value (what the API receives) | status | positioning | notes |
+| --- | --- | --- | --- | --- |
+| `tripo-v3.1` (default) | `v3.1-20260211` | GA | latest high-precision; AAA / 3D printing | full feature set |
+| `tripo-p1` | `P1-20260311` | GA | 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` | **Preview** (2026-08) | P1 upgrade (P series) | 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 | previous generations | only when the human asks |
+
+**Alias vs wire value.** `tripo-*`, `p1`, `p2`, `v3.1` … are CLI-side aliases; the CLI always sends the dated wire value in the `model` field (`--model tripo-p2` → `"model": "P2-20260801"`). The v3 server whitelist accepts wire values only — sending an alias straight to the API returns 1004 `invalid model` with the allowed list. `task.json` records the wire value that was actually used. `tripo-turbo` / `tripo-v2.0` appear in some docs but are **not** on the v3 whitelist (400).
+
+Official docs (ov / cn):
+- Models & Versions: <https://developers.tripo3d.ai/en/docs/models-and-versions> · <https://developers.tripo3d.com/zh/docs/models-and-versions>
+- P Series model detail: <https://developers.tripo3d.ai/en/models/p1> · <https://developers.tripo3d.com/zh/models/p1>
+- P Series endpoints: `…/docs/generation-text-to-model/p`, `…/docs/generation-image-to-model/p`, `…/docs/generation-multiview-to-model/p` (the `/standard` tab on each page is the H-series version)
+
+### 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 +100,32 @@ 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 | status | notes |
+| --- | --- | --- | --- |
+| `seedream_v4` | ByteDance | GA | text-to-image default (balanced); **not accepted by image-to-image** |
+| `seedream_v5` | ByteDance | GA | image-to-image default; higher quality |
+| `gemini-2.5-flash` / `gemini-3-pro` / `gemini-3.1-flash` | Google | GA | fast / high quality / latest fast. Backend aliases `banana` / `banana_pro` / `banana2` are also accepted |
+| `chat_image_1` / `chat_image_1.5` | OpenAI | retiring 2026-10-23 / 2026-12-01 | GPT image; 1.5 = higher quality — move to `chat_image_2` |
+| `chat_image_2` | OpenAI | GA | GPT latest |
+
+Image model ids are sent as-is (no alias normalization). Full list with retirement dates: <https://developers.tripo3d.ai/en/docs/models-and-versions>.
+
+### 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.