tripo-cli 0.7.3 → 0.8.1

package/dist/pipeline/make.js

@@ -1,22 +1,38 @@
 /**
  * The `make` orchestrator — one entry point that turns any input (text /
  * image / multiview / model file / task ref) into finished artifacts,
- * applying the dual-model rule, scenario presets, and the processing chain.
+ * applying model routing, scenario presets, and the processing chain.
  * Shared by `tripo make`, `tripo ai`, `tripo redo`, batch, and the MCP server.
  */
 import { basename } from 'node:path';
 import { UsageError } from '../core/errors.js';
 import { log, warn } from '../core/output.js';
-import { buildImageToModel, buildMultiviewToModel, buildStepRequest, buildTextToModel, } from '../core/requests.js';
+import { buildImageToModel, buildMultiviewToModel, buildStepRequest, buildTextToModel, validateChainRequests, } from '../core/requests.js';
 import { precheckBalance, resolveInputValue, runTask } from '../core/task-service.js';
-import { t } from '../i18n.js';
 import { validateChain, ChainError } from '../knowledge/chains.js';
-import { chooseModel, detectLowPolyIntent } from '../knowledge/models.js';
+import { chooseModel, detectDenseGeometryIntent, detectLowPolyIntent, detectRealtimeIntent } from '../knowledge/models.js';
 import { getScenario } from '../knowledge/scenarios.js';
 import { classifyInputs } from '../util/input-detect.js';
 import { runChain, assertSourceReady } from './runner.js';
-/** Build the full plan (no network calls except none): what model, what chain, why. */
+function chooseGenerationModel(options, scenario, genParams, prompt) {
+    return chooseModel({
+        explicit: options.model,
+        preferred: scenario?.model,
+        faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
+        quad: genParams.quad === true,
+        lowPoly: prompt ? detectLowPolyIntent(prompt) : false,
+        realtime: prompt ? detectRealtimeIntent(prompt) : false,
+        denseGeometry: prompt ? detectDenseGeometryIntent(prompt) : false,
+        params: genParams,
+    });
+}
+/** Validate the entire plan without side effects before resolving uploads. */
 export async function planMake(client, options) {
+    const preview = await prepareMake(client, { ...options, dryRun: true });
+    checkPlanChain(preview);
+    return options.dryRun ? preview : prepareMake(client, options);
+}
+async function prepareMake(client, options) {
     const classified = classifyInputs(options.inputs);
     const scenario = options.scenario ? getScenario(options.scenario) : undefined;
     if (options.scenario && !scenario) {
@@ -25,25 +41,21 @@ export async function planMake(client, options) {
     const userParams = options.params ?? {};
     const genParams = { ...(scenario?.genParams ?? {}), ...userParams };
     const chain = options.chain && options.chain.length > 0 ? options.chain : (scenario?.chain ?? []);
+    // --then replaces the scenario chain, so its dual-delivery promise no longer holds.
+    const downloadGeneration = scenario?.downloadGeneration === true && !(options.chain && options.chain.length > 0);
     const warnings = [];
     if (options.chain && options.chain.length > 0 && scenario && scenario.chain.length > 0) {
-        warnings.push(t({
-            zh: `--then 覆盖了 ${scenario.id} 场景默认加工链`,
-            en: `--then overrides the default ${scenario.id} processing chain`,
-        }));
+        warnings.push(`--then overrides the default ${scenario.id} processing chain`);
     }
     switch (classified.kind) {
         case 'text': {
             const prompt = classified.values[0].value;
-            const choice = chooseModel({
-                explicit: options.model ?? scenario?.model,
-                faceLimit: typeof genParams.face_limit === 'number' ? genParams.face_limit : undefined,
-                lowPoly: detectLowPolyIntent(prompt),
-            });
+            const choice = chooseGenerationModel(options, scenario, genParams, prompt);
             const generation = buildTextToModel(prompt, choice.model, genParams);
             return {
                 generation,
                 chain,
+                downloadGeneration,
                 model: choice.model,
                 modelReason: choice.reason,
                 name: options.name ?? prompt,
@@ -54,14 +66,12 @@ export async function planMake(client, options) {
         case 'url-image': {
             const raw = classified.values[0].value;
             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,
-            });
+            const choice = chooseGenerationModel(options, scenario, genParams);
             const generation = buildImageToModel(value, choice.model, genParams);
             return {
                 generation,
                 chain,
+                downloadGeneration,
                 model: choice.model,
                 modelReason: choice.reason,
                 name: options.name ?? basename(raw),
@@ -70,14 +80,12 @@ export async function planMake(client, options) {
         }
         case 'multiview': {
             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,
-            });
+            const choice = chooseGenerationModel(options, scenario, genParams);
             const generation = buildMultiviewToModel(views, choice.model, genParams);
             return {
                 generation,
                 chain,
+                downloadGeneration,
                 model: choice.model,
                 modelReason: choice.reason,
                 name: options.name ?? basename(classified.values[0].value),
@@ -89,10 +97,7 @@ export async function planMake(client, options) {
             const { value } = await resolveInputValue(client, raw, { dryRun: options.dryRun });
             const generation = buildStepRequest('import', value, {});
             if (chain.length === 0) {
-                warnings.push(t({
-                    zh: '导入模型后没有加工步骤;用 --then 指定(如 --then texture,rig)',
-                    en: 'importing a model with no processing steps; add --then (e.g. --then texture,rig)',
-                }));
+                warnings.push('importing a model with no processing steps; add --then (e.g. --then texture,rig)');
             }
             return {
                 generation,
@@ -121,6 +126,7 @@ export async function planMake(client, options) {
  * Skipped when the upstream type is unknown (raw task id without local history).
  */
 export function checkPlanChain(plan) {
+    validateChainRequests(plan.chain);
     if (plan.chain.length === 0)
         return;
     const upstream = plan.generation?.taskType ?? plan.sourceType;
@@ -147,7 +153,7 @@ export async function executeMake(client, plan, options) {
     let primary;
     if (plan.generation) {
         if (plan.model && plan.modelReason) {
-            log(t({ zh: `模型选择:${plan.model}(${plan.modelReason})`, en: `model: ${plan.model} (${plan.modelReason})` }));
+            log(`model: ${plan.model} (${plan.modelReason})`);
         }
         primary = await runTask({
             client,
@@ -156,10 +162,11 @@ export async function executeMake(client, plan, options) {
             name: plan.name,
             outDir: options.outDir,
             noWait: options.noWait,
-            noDownload: options.noDownload || plan.chain.length > 0,
+            noDownload: options.noDownload || (plan.chain.length > 0 && !plan.downloadGeneration),
             timeoutMs: options.timeoutMs,
             notify: options.notify && plan.chain.length === 0,
             precheckBalance: false,
+            onCreated: options.onTaskCreated,
         });
         if (options.noWait)
             return { primary, chainResults: [] };
@@ -183,6 +190,7 @@ export async function executeMake(client, plan, options) {
         outDir: options.outDir,
         notify: false,
         timeoutMs: options.timeoutMs,
+        onTaskCreated: options.onTaskCreated,
     });
     // If the chain stopped early (not riggable) and no step downloaded a model,
     // fetch the source artifacts so the user still gets their model.

package/dist/pipeline/runner.js

@@ -5,14 +5,14 @@
  */
 import { UsageError } from '../core/errors.js';
 import { log, warn } from '../core/output.js';
-import { buildStepRequest } from '../core/requests.js';
+import { buildStepRequest, validateChainRequests } from '../core/requests.js';
 import { runTask } from '../core/task-service.js';
-import { t } from '../i18n.js';
 import { getStep, validateChain } from '../knowledge/chains.js';
 import { NON_BIPED_PRESETS } from '../knowledge/models.js';
 export async function runChain(options) {
     const { client, chain } = options;
     validateChain(chain, options.sourceType);
+    validateChainRequests(chain);
     const results = [];
     let currentTaskId = options.sourceTaskId;
     let rigTypeRecommendation;
@@ -22,7 +22,7 @@ export async function runChain(options) {
         const args = { ...spec.args };
         if (spec.step === 'rig' && rigTypeRecommendation && args.rig_type === undefined) {
             args.rig_type = rigTypeRecommendation;
-            log(t({ zh: `采用 rig-check 推荐体型:${rigTypeRecommendation}`, en: `using rig-check recommendation: ${rigTypeRecommendation}` }));
+            log(`using rig-check recommendation: ${rigTypeRecommendation}`);
         }
         if (spec.step === 'rig')
             rigType = String(args.rig_type ?? 'biped');
@@ -33,7 +33,7 @@ export async function runChain(options) {
             if (requested.length > 0 && requested.every((a) => /^preset:[^:]+$/.test(a))) {
                 delete args.animation;
                 args.animations = bodyPresets;
-                log(t({ zh: `体型为 ${rigType},双足预设换成 ${bodyPresets.join(', ')}`, en: `rig type is ${rigType}: biped presets swapped for ${bodyPresets.join(', ')}` }));
+                log(`rig type is ${rigType}: biped presets swapped for ${bodyPresets.join(', ')}`);
             }
         }
         // avian/others have no preset animations: the rigged model is the final output.
@@ -52,13 +52,11 @@ export async function runChain(options) {
             // Intermediate steps skip download; final step downloads.
             noDownload: i < chain.length - 1 && spec.step !== 'rig-check' && !noPresets,
             precheckBalance: false, // checked once by the caller
+            onCreated: options.onTaskCreated,
         });
         results.push(result);
         if (noPresets) {
-            const message = t({
-                zh: `体型 ${rigType} 没有预设动画,已跳过 retarget,产物为绑骨模型`,
-                en: `rig type ${rigType} has no preset animations; skipped retarget and kept the rigged model`,
-            });
+            const message = `rig type ${rigType} has no preset animations; skipped retarget and kept the rigged model`;
             warn(message);
             return { results, stoppedEarly: message };
         }
@@ -68,10 +66,7 @@ export async function runChain(options) {
             const riggable = output.riggable;
             rigTypeRecommendation = typeof output.rig_type === 'string' ? output.rig_type : undefined;
             if (riggable === false) {
-                const message = t({
-                    zh: 'rig-check 判定该模型不可绑骨,动画链止损停止(后续步骤未执行,未扣积分)',
-                    en: 'rig-check says this model is not riggable; stopping the chain early (no further credits spent)',
-                });
+                const message = 'rig-check says this model is not riggable; stopping the chain early (no further credits spent)';
                 warn(message);
                 return { results, stoppedEarly: message };
             }

package/dist/pipeline/stdin.js

@@ -2,12 +2,48 @@
  * NDJSON pipe support: downstream commands read the upstream task result from
  * stdin, enabling `tripo make cat.png | tripo model texture | tripo anim rig`.
  */
-/** Read piped NDJSON/JSON from stdin; returns undefined on a TTY. */
+import { CliError, UsageError } from '../core/errors.js';
+import { EXIT } from '../knowledge/error-catalog.js';
+/**
+ * Read piped NDJSON/JSON from stdin; returns undefined only on a TTY.
+ * Piped input that carries an upstream error or no task throws, so a broken
+ * pipeline never falls back to some other task and spends credits on it.
+ */
 export async function readPipedTask() {
     if (process.stdin.isTTY)
         return undefined;
     const raw = await readAll(process.stdin);
-    return parsePipedText(raw);
+    const upstream = parsePipedError(raw);
+    if (upstream) {
+        const code = upstream.exit_code;
+        const exitCode = code !== undefined && Number.isInteger(code) && code >= 1 && code <= 9 ? code : EXIT.USAGE;
+        throw new CliError(`upstream command failed${code !== undefined ? ` (exit ${code})` : ''}: ${upstream.error}; nothing was submitted`, exitCode);
+    }
+    const task = parsePipedText(raw);
+    if (!task) {
+        throw new UsageError('no task on stdin (piped input was empty or carried no task_id); nothing was submitted', 'pass the input explicitly, e.g. "tripo model texture @last" or a task id');
+    }
+    return task;
+}
+/** The upstream error when the last JSON line is an error object (`{"error","exit_code"}`). */
+export function parsePipedError(raw) {
+    const lines = raw.trim().split('\n').map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let obj;
+        try {
+            obj = JSON.parse(lines[i]);
+        }
+        catch {
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null)
+            continue;
+        const { error, exit_code: exitCode } = obj;
+        if (typeof error !== 'string')
+            return undefined;
+        return { error, exit_code: typeof exitCode === 'number' ? exitCode : undefined };
+    }
+    return undefined;
 }
 /** Parse piped text: JSON object, NDJSON (last task line wins), or a bare task id. */
 export function parsePipedText(raw) {
@@ -18,7 +54,8 @@ export function parsePipedText(raw) {
     for (let i = lines.length - 1; i >= 0; i--) {
         try {
             const obj = JSON.parse(lines[i]);
-            if (typeof obj.task_id === 'string') {
+            // Error JSON may name the failed task; it is never an input.
+            if (typeof obj.task_id === 'string' && obj.error === undefined) {
                 return { task_id: obj.task_id, type: typeof obj.type === 'string' ? obj.type : undefined };
             }
         }

package/dist/program.js

@@ -13,16 +13,15 @@ import { registerGenerateCommands } from './commands/generate.js';
 import { registerHomeAction } from './commands/home.js';
 import { registerMakeCommand } from './commands/make.js';
 import { registerMcpCommand } from './commands/mcp.js';
+import { registerModelsCommand } from './commands/models.js';
 import { registerProcessCommands } from './commands/process-groups.js';
 import { registerTaskCommands } from './commands/task.js';
 import { registerTopupCommand } from './commands/topup.js';
 import { notifyIfOutdated, registerUpdateCommand } from './commands/update.js';
 import { registerViewCommands } from './commands/view.js';
-import { loadConfig } from './config/config.js';
 import { RefError } from './config/history.js';
-import { ApiError, CliError, UsageError } from './core/errors.js';
+import { ApiError, ArtifactDownloadError, CliError, TaskFailedError, UsageError } from './core/errors.js';
 import { configureOutput, errorLine, isJsonMode } from './core/output.js';
-import { setLocale, t } from './i18n.js';
 import { EXIT } from './knowledge/error-catalog.js';
 import { cliVersion } from './version.js';
 import { beginOperation, finishOperation } from './core/analytics.js';
@@ -30,10 +29,7 @@ export function buildProgram() {
     const program = new Command();
     program
         .name('tripo')
-        .description(t({
-        zh: 'Tripo 3D 智能 CLI — 一句话/一张图,直出可进引擎的 3D 资产\n高频: make(生成) ai(专家规划) view(预览) topup(充值)',
-        en: 'Tripo 3D intelligent CLI — turn a sentence or an image into engine-ready 3D assets\ntop commands: make · ai · view · topup',
-    }))
+        .description('Tripo 3D intelligent CLI — turn a sentence or an image into engine-ready 3D assets\ntop commands: make · ai · view · topup')
         .version(cliVersion(), '-v, --version')
         .option('--json', 'machine-readable output on stdout (auto-enabled when piped)')
         .option('--yes', 'skip confirmations (auto-enabled when headless)')
@@ -54,13 +50,10 @@ export function buildProgram() {
         const profile = resolveGlobalString(actionCommand, 'profile');
         if (profile)
             process.env.TRIPO_PROFILE = profile;
-        const lang = loadConfig().language;
-        if (lang)
-            setLocale(lang);
         const path = [];
         for (let command = actionCommand; command && command !== program; command = command.parent)
             path.unshift(command.name());
-        const excluded = ['mcp', 'docs', 'completion', 'config', 'update', 'use', 'logout', 'home'];
+        const excluded = ['mcp', 'docs', 'completion', 'config', 'update', 'use', 'logout', 'home', 'models'];
         if (actionCommand.name() !== 'mcp')
             beginOperation(path.join(':'), path.length === 0 || excluded.includes(path[0]) || actionCommand.opts().dryRun === true, undefined, actionCommand.opts().region === 'cn' || actionCommand.opts().region === 'ov' ? actionCommand.opts().region : undefined);
         // Startup version hint (cached, non-blocking). `update` reports on its
@@ -75,6 +68,7 @@ export function buildProgram() {
     registerAuthCommands(program);
     registerTopupCommand(program);
     registerAccountCommands(program);
+    registerModelsCommand(program);
     registerGenerateCommands(program);
     registerProcessCommands(program);
     registerTaskCommands(program);
@@ -158,6 +152,7 @@ export function handleError(err) {
                 ...(err instanceof ApiError
                     ? { api_code: err.apiCode, request_id: err.requestId, http_status: err.httpStatus }
                     : {}),
+                ...(err instanceof TaskFailedError || err instanceof ArtifactDownloadError ? { task_id: err.taskId } : {}),
                 ...(err.suggestion ? { suggestion: err.suggestion } : {}),
             }) + '\n');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Tripo 3D intelligent CLI — turn a prompt or an image into engine-ready 3D assets from your terminal (Tripo V3 API)",
   "keywords": [
     "tripo",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "skill",
+    "CHANGELOG.md",
     "README.md"
   ],
   "engines": {
@@ -48,7 +49,7 @@
     "@clack/prompts": "^1.7.0",
     "commander": "^15.0.0",
     "picocolors": "^1.1.1",
-    "undici": "^6.28.0",
+    "undici": "^6.29.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -1,5 +1,19 @@
+---
+name: tripo-cli
+description: Generate and process 3D models with the Tripo API through the tripo CLI - text or images to GLB/FBX/OBJ/STL/USDZ, texturing, rigging, animation, mesh tools and format conversion, with plan cards and credit estimates. Use when the user wants to create, convert, rig, animate or 3D-print a 3D asset, or mentions Tripo.
+---
+
 # Tripo CLI Skill
 
+**Bundled with tripo-cli 0.8.1.**
+
+- Display aliases `H3.1`, `H3.0`, `H2.5`, `P1.0`, `P2.0` (case-insensitive) normalize before validation; unknown 3D/image model IDs fail locally.
+- `make` validates deterministic later steps before uploading or generating.
+- Plan cards and `--dry-run` JSON (`generation_credits_estimate`) show the official list-price estimate for the generation step; P1, legacy models and `--then` chain steps are **not estimated**, which never means zero credits.
+- Do not interpret `valid=true` as a quotation or proof that arbitrary passthrough fields are supported. Check warnings and the normalized payload: unsupported P-series fields are removed with warnings, not sent to the API.
+- Image model `chat_image_1` is retired and rejected; `chat_image_1.5` is still valid (announced retirement 2026-12-01).
+- Never automatically swap models and resubmit a paid task.
+
 You (an AI coding agent) can generate production-ready 3D assets with the `tripo` CLI.
 One command turns a text prompt or an image into local files: a 3D model (glb/fbx/stl/...), a `preview.png` render, and a `task.json` record.
 
@@ -49,13 +63,23 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 ## Behavior rules (read first)
 
 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.
+2. **stdout is the contract; stderr is commentary.** With `--json` (auto-enabled when piped), every result command prints exactly one JSON line on stdout (`docs`/`completion` print text, `mcp` speaks JSON-RPC). 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. Ask the human before re-rolling: `tripo redo` submits a new paid task at once, with no plan card and no confirmation.
 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; on `timeout` it is still running — `tripo task watch <id>`, never redo) · 7 network (a failed submit is never resent and may already exist — check `tripo balance` before re-running) · 8 not found · 9 rate limit (retry with backoff)
+   - 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; on `timeout` it is still running — `tripo task watch <id>`, never redo)
+   - 7 network: a failed submit is never resent and may already exist — check `tripo balance` before re-running. If the task succeeded but its download failed, the error JSON carries `task_id` — run `tripo task get <task_id> --download`, never re-make.
+   - 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. 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").
+7. **Route models by use, topology, and geometry.**
+   - Explicit `--model` always wins.
+   - `tripo-v3.1` (H3.1) is the official default flagship model; the CLI also requires it for dense/high-poly geometry, `smart_low_poly=true`, `generate_parts=true`, any explicit `geometry_quality`, or a face budget outside P2's range (below 48, above 50000, or above 25000 with quad).
+   - Next, a `--for` preset outranks prompt hints: `film` and `print` use H3.1; `game-mobile`, `game-pc`, `ar-web`, `anim` and `toy` use P2.
+   - Without a preset, the CLI selects `tripo-p2` for real-time/game/editable assets, low-poly or voxel requests, quad topology, and a face budget within P2's range; anything else stays on H3.1.
+   - P2 costs 100–130 credits per generation versus 10–50 for H3.1 before add-ons, so before running P2, relay the plan card's estimate to the human and get confirmation.
+   - `tripo-p1` is an explicit lower-cost option. Only use legacy `tripo-v3.0` / `tripo-v2.5` to reproduce 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
 
@@ -67,10 +91,10 @@ tripo make hero.glb --then texture,rig --json --yes       # import + process
 tripo make @last --then convert:fbx --json --yes          # continue from last task
 ```
 
-- `--for` scenario presets: `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`
+- `--for` scenario presets: `film` `print` → H3.1; `game-mobile` `game-pc` `ar-web` `anim` `toy` → P2 (the preset outranks prompt hints; `--model` and H-only requirements still win)
 - `--then` chain steps: `texture 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`, `decimate:5000`)
-- Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["preview"],["normalize_scale"],["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)
+- Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["source_model_file"],["preview"],["normalize_scale"],["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)
   - `normalize_scale` appears when the input was a model file / URL: the import rescaled it (final size = original size × normalize_scale; `1` = untouched) and nothing scales it back — divide by it to recover the original size
 
 ## Pipes (composing steps yourself)
@@ -81,23 +105,26 @@ Downstream commands read the upstream task from stdin:
 tripo make cat.png --json | tripo anim rig --json | tripo anim retarget --param animation=preset:walk --json
 ```
 
+If an upstream command fails or prints no task, the downstream submits nothing and exits with the upstream's exit code (or 2). Without a terminal on stdin, process commands never fall back to `@last`; pass the input explicitly.
+
 ## Other commands
 
 | command | purpose |
 | --- | --- |
 | `tripo task get/watch <id> --download` | inspect / block on / download an existing task |
 | `tripo balance` / `tripo usage` | credits: `{"balance","frozen"}` / recent spend |
+| `tripo models` | accepted model ids per capability, defaults and aliases (local, no API call) |
 | `tripo redo [@last]` | same request, new seed |
 | `tripo view [@last]` | (humans) open a local 3D preview; agents read `preview.png` instead |
 | `tripo files upload <path>` | get a `file_token` |
-| `tripo batch run manifest.yaml` | bulk jobs, resumable |
+| `tripo batch run manifest.yaml` | bulk jobs, resumable; no plan card, so estimate and confirm first (`commands/batch` § Cost) |
 | `tripo mcp` | run as an MCP server (tools: tripo_make, tripo_task_get, tripo_task_wait, tripo_balance, tripo_history) |
 | `tripo docs --topic commands/<name>` | print detailed docs for any command |
 
 ## 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)
+  - model versions · H series (`tripo-v3.x`) · P series (`tripo-p1`, `tripo-p2`) · alias → wire value · GA / 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/account.md

@@ -54,7 +54,7 @@ tripo config context default_scenario=game-mobile output_dir=./assets   # per-di
 ```
 
 Env overrides: `TRIPO_API_KEY` `TRIPO_PROFILE` `TRIPO_REGION` `TRIPO_API_BASE_URL` `TRIPO_LLM_BASE_URL` `TRIPO_LLM_API_KEY` `TRIPO_LLM_MODEL`.
-`region`/`api_base_url`/`platform_base_url` are stored per profile; `language`/`llm.*`/`default_output_dir` are shared.
+`region`/`api_base_url`/`platform_base_url` are stored per profile; `llm.*`/`default_output_dir` are shared.
 
 ## tripo doctor
 

package/skill/commands/batch.md

@@ -26,8 +26,18 @@ jobs:
     params: { texture_quality: detailed }
 ```
 
+## Cost
+
+- Every job is a full `make` that runs without a plan card or confirmation.
+- The five P2 presets (`game-mobile` `game-pc` `ar-web` `anim` `toy`) cost 100–130 credits per job for the generation step alone; the example's default `game-mobile` is at least 110 per job, before chain steps.
+- Before running, dry-run one job per preset/params combination with the matching `make` flags (`tripo make "a bronze sword" --for game-mobile --then texture,convert:fbx --dry-run --json`), multiply `generation_credits_estimate` by the number of jobs that share it (`null` means not estimated, never zero), relay the total to the human and get confirmation.
+
 ## Behavior
 
-- State is saved next to the manifest (`assets.yaml.state.json`) after every job. Re-running the same command **skips succeeded jobs** (resume). `--fresh` starts over.
-- Failed jobs retry up to `--retries` times, then are reported; exit code 6 if any job stays failed.
-- Final stdout JSON: `{"total","success","failed","state_file","jobs":{...}}`.
+- State is saved next to the manifest (`assets.yaml.state.json`) after every job and as soon as each paid task is created. Re-running the same command **skips succeeded jobs** (resume). `--fresh` starts over.
+- A job is retried (up to `--retries` times) only when the failed attempt left no paid task behind: it failed before anything was submitted, or its only task failed server-side (failed/cancelled tasks are refunded).
+- Anything else stops the job as `needs_attention`, and it is **never resubmitted automatically**, not even on re-run: a create request whose response was lost (the task may exist and be billed), a timeout, a failed artifact download, or a failure after an earlier task of the job succeeded.
+  - Its state entry records `tasks` (every task created for the job, in order), `error`, and `suggestion` (the next step, e.g. `tripo task get <id> --download`, or `tripo make <task_id> --then ...` to continue from the last successful task).
+- To resubmit a `needs_attention` job on purpose, delete its entry from the state file, or use `--fresh` to rerun everything.
+- Exit code 6 if any job stays `failed` or `needs_attention`.
+- Final stdout JSON: `{"total","success","failed","needs_attention","state_file","jobs":{...}}`.

package/skill/commands/generate.md

@@ -14,12 +14,12 @@ tripo generate multiview-to-model @last          # reuse the 4 views of an image
 
 ### 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:
+The P series (editable low-poly 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
+tripo generate text-to-model "a low poly knight for a game" -p face_limit=8000                 # → model: P2-20260801
+tripo generate image-to-model photo.png --model tripo-p2 -p quad=true -p face_limit=12000      # → model: P2-20260801
+tripo generate multiview-to-model front.png back.png --model tripo-p1                           # explicit lower-cost P-series choice
 ```
 
 | endpoint | H series (standard) page | P series page |
@@ -32,17 +32,25 @@ tripo generate multiview-to-model front.png back.png --model tripo-p1
 
 ### 3D models (`--model`) — Models & Versions
 
-Keywords: model versions · H series (v3.x) · P series (P1 / P2) · Preview · quad · alias → wire value.
+Keywords: model versions · H series (v3.x) · P series (P1 / P2) · 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 50–20000; **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; ~2s mesh |
-| `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.1` | `v3.1-20260211` | GA | official default flagship model; dense geometry, H-only topology features, film / print | full feature set; 10–40 credits (text) or 20–50 (image / multiview) by texture tier, plus `geometry_quality=detailed` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 |
+| `tripo-p1` | `P1-20260311` | GA | explicit lower-cost low-poly choice | face_limit 50–20000; **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; no published price, so plans leave it unestimated |
+| `tripo-p2` | `P2-20260801` | GA (2026-08) | automatic choice for real-time, game, editable, low-poly, voxel, quad, or a face budget within P2's range | 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). 100–130 credits for every input by texture tier, no add-ons; confirm the plan card's estimate with the human before spending |
 | `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).
 
+**Automatic routing.**
+
+- Explicit `--model` always wins, followed by `-p model=<string>`; both are normalized and checked against the selected model's capabilities.
+- With neither form, dense/high-poly geometry, `smart_low_poly=true`, `generate_parts=true`, any explicit `geometry_quality`, and a face budget outside P2's range (below 48, above 50000, or above 25000 with quad) select H3.1 first.
+- A scenario preset is the next preference and outranks prompt hints: film and print use H3.1, while game-mobile, game-pc, ar-web, anim, and toy use P2.
+- Without a preset, real-time/game/editable/topology hints, low-poly/voxel intent, `quad=true`, or a face budget within P2's range select P2.
+- Everything else uses H3.1, the official default model.
+
 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>
@@ -111,14 +119,31 @@ tripo generate image-to-splat photo.png         # gaussian splat
 | `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 |
 | `banana` / `banana_pro` / `banana2` | Google | GA | fast / higher quality / latest fast |
-| `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` or 2.5 |
+| `chat_image_1` | OpenAI | retired 2026-10-23 | rejected locally; explicitly choose a replacement, never auto-resubmit |
+| `chat_image_1.5` | OpenAI | active; retiring 2026-12-01 | remains supported until retirement |
 | `chat_image_2` | OpenAI | GA | GPT, best quality |
 | `chat_image_2.5_flare` / `chat_image_2.5_sunburst` | OpenAI | GA | 2.5 series: flare = speed tier (chat_image_2 quality, much faster); sunburst = refined tier (keeps unedited areas closest to the original) |
 
-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 model ids are endpoint-whitelisted and sent as-is (no Gemini/display alias mapping). Unknown IDs fail locally. Since 0.8.0 the CLI rejects retired `chat_image_1` without automatic replacement; `chat_image_1.5` remains valid as of 2026-10-27. Full list with retirement dates: <https://developers.tripo3d.ai/en/docs/models-and-versions>.
 
 ### Image parameters
 
+- Since 0.8.0 the CLI validates `model`, `quality`, `background`, `output_format` and known `size` rules on both image endpoints.
+- Image editing preflights these and reference counts (Seedream ≤4, Banana ≤10, Chat Image ≤16) before uploading any local file.
+- Standalone image/multiview-to-model likewise validates known model/face/quad constraints before uploads; text-to-model validates the effective prompt's 1024-character limit.
+- Non-2.5 `background` is removed with an ignored warning (matching the documented server behavior); 2.5 transparency rejects JPEG. `quality=auto` is rejected.
+- Unspecified values remain unspecified; the CLI does not invent provider fields or silently change models.
+
+Size rules (official tabs, checked 2026-10-27):
+- `banana`: fixed `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672`. Omitted size is left to the service; the documented default differs from its explicit fixed-size list.
+- `banana_pro`: `1K` / `2K` / `4K` or positive integer `WxH`; no undocumented pixel limits are invented.
+- `banana2`: `0.5K` / `1K` / `2K` / `4K` only.
+- `seedream_v4`: `2K` / `4K`; `seedream_v5`: `2K` / `3K`; explicit `WxH` requires aspect ratio 1:16–16:1. The official MP ranges are rounded (v4 approximately 3.69–16.78 MP; v5 3.69–10.40 MP); exact pixel-count cutoffs are not asserted by the CLI and still require server validation.
+- `chat_image_1.5`: `1024x1024` / `1024x1536` / `1536x1024` / `auto`.
+- `chat_image_2` / 2.5: `auto` or `WxH`, each edge ≤3840 and divisible by 16, long/short ratio ≤3, total pixels 655360–8294400. `1536x864` and `1088x1920` work; `1080x1920` fails locally.
+
+3D display aliases `H3.1` / `P1.0` / `P2.0` (plus `P2.0 Preview`, the pre-GA name kept for compatibility) and legacy `H3.0` / `H2.5` map to the same dated IDs and validation as `tripo-v3.1` / `tripo-p1` / `tripo-p2` / `tripo-v3.0` / `tripo-v2.5`; every model alias is case-insensitive. All `face_limit` values must be finite integers. Unknown model names are rejected, not forwarded.
+
 | param | default | endpoint | notes |
 | --- | --- | --- | --- |
 | `prompt` | — | t2i (required), i2i | ≤1024 chars; i2i: required unless `template` is set |