tripo-cli 0.7.3 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.7.3",
+  "version": "0.8.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",
@@ -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.0.**
+
+- 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,6 +105,8 @@ 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 |
@@ -90,14 +116,14 @@ tripo make cat.png --json | tripo anim rig --json | tripo anim retarget --param
 | `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 |

package/skill/commands/make.md

@@ -14,14 +14,20 @@ tripo make <input...> [options]
 ── Plan ──────────────────────────
 input: a medieval knight
 scenario: game-mobile (Mobile game / low-poly)
-model: P1-20260311 — scenario game-mobile
+model: P2-20260801 — scenario preference
 steps:
   1. text-to-model  POST /v3/generation/text-to-model — generate a 3D model from text
-     model="P1-20260311" texture=true pbr=true texture_quality="standard" face_limit=15000
-  2. texture  POST /v3/models/texture — regenerate textures / PBR materials
-  3. convert  POST /v3/models/convert — convert format / texture size / orientation
+     model="P2-20260801" texture=true pbr=true texture_quality="standard" face_limit=15000
+  2. convert  POST /v3/models/convert — convert format / texture size / orientation
      format="FBX" texture_size=2048
-deliverables: FBX, GLB
+deliverables: FBX
+cost impact:
+  · estimated generation cost: 110 credits (official list price; chain steps not estimated)
+  · non-default convert options bill as complex convert
+  P2 editable low-poly topology
+  2K textures for mobile budgets
+  P2 costs more credits than H/P1; check credits before running
+  append --then rig if you need a skeleton
 ──────────────────────────────────
 ```
 
@@ -41,10 +47,14 @@ In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no
 
 - `--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: `texture convert import rig-check rig retarget segment complete decimate uv smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
-- `--model <m>` — force `tripo-v3.1` (high fidelity, default), `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped) or `tripo-p2` (P-series preview; adds quad, face_limit 48–50000 tri / 48–25000 quad; never auto-selected). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311` / `P2-20260801`) the server actually accepts. Full table with status (GA / Preview / Legacy) and official links: `tripo docs --topic commands/generate` → "Models & Versions".
+- `--model <m>` — force a model. The CLI normalizes these aliases (case-insensitive) to the wire versions the server actually accepts. Full table with status (GA / Legacy) and official links: `tripo docs --topic commands/generate` → "Models & Versions".
+  - `tripo-v3.1` (`v3.1-20260211`) — official default flagship; dense geometry / H-only features. Plan card estimate at official list price: 10–50 credits before add-ons.
+  - `tripo-p1` (`P1-20260311`) — explicit lower-cost low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped. Not estimated.
+  - `tripo-p2` (`P2-20260801`) — P-series; automatic for real-time/editable topology; quad; face_limit 48–50000 tri / 48–25000 quad. Plan card estimate: 100–130 credits.
+  - Without an explicit model, hard geometry requirements win, then the scenario preference, then prompt/topology routing; everything else uses H3.1, the official default. Legacy models are not estimated.
 - `-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=...`.
+- `-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=...`. For 3D generation, `-p model=<string>` is also an explicit model choice, normalized and validated like `--model`; `--model` takes precedence when both are supplied.
 - `-o, --out <dir>` — artifact base dir (default `./tripo-out/<name>-<id8>/`).
 - `--no-wait` — submit only, print `{"task_id"}` and exit (poll later with `tripo task watch`).
 - `--no-download` — wait but skip downloads.
@@ -56,7 +66,7 @@ In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no
 
 ## Dry run (agents: validate before spending)
 
-`tripo make ... --dry-run --json` runs the whole planning stage with **zero network calls** and prints the plan as the result on stdout: the model the dual-model rule picked, the completed request body for every call (scenario defaults merged, aliases normalized to wire values, illegal params stripped, step defaults filled in), and the outcome of every local validation. Works without an API key.
+`tripo make ... --dry-run --json` runs the whole planning stage with **zero network calls** and prints the plan as the result on stdout: the model routing selected, the completed request body for every call (scenario defaults merged, aliases normalized to wire values, illegal params stripped, step defaults filled in), and the outcome of every local validation. Works without an API key.
 
 ```bash
 tripo make concept.png --for game-mobile --then rig,convert:fbx --dry-run --json
@@ -65,22 +75,24 @@ tripo make concept.png --for game-mobile --then rig,convert:fbx --dry-run --json
 ```json
 {"dry_run":true,"valid":true,
  "input":"concept.png","scenario":"game-mobile",
- "model":"P1-20260311","model_reason":"explicit --model",
+ "model":"P2-20260801","model_reason":"scenario preference",
  "steps":[
    {"name":"image-to-model","endpoint":"/v3/generation/image-to-model","task_type":"image_to_model",
-    "payload":{"input":"<upload:concept.png>","model":"P1-20260311","texture":true,"pbr":true,"texture_quality":"standard","face_limit":15000}},
+    "payload":{"input":"<upload:concept.png>","model":"P2-20260801","texture":true,"pbr":true,"texture_quality":"standard","face_limit":15000}},
    {"name":"rig","endpoint":"/v3/animations/rig","task_type":"animate_rig","payload":{"input":"<upstream>","model":"v3.0-20260909"}},
    {"name":"convert","endpoint":"/v3/models/convert","task_type":"convert_model","payload":{"input":"<upstream>","format":"FBX"}}],
  "pending_uploads":["concept.png"],
- "deliverables":["FBX","GLB"],
+ "deliverables":["FBX"],
  "candidates":1,
  "warnings":["--then overrides the default game-mobile processing chain"],
  "errors":[],
- "cost_notes":[]}
+ "generation_credits_estimate":110,
+ "cost_notes":["estimated generation cost: 110 credits (official list price; chain steps not estimated)"]}
 ```
 
 - `valid` / `errors` — `errors` are blocking (illegal chain order, out-of-range `face_limit`, quad + GLTF, missing `animation` for retarget, ...). The real run would exit 2 on them before spending anything; the dry run exits 2 too, so branch on the exit code or on `valid`.
-- `warnings` — adjustments the CLI applies automatically (e.g. `P1 does not support quad (removed)`); safe to proceed, but check they match your intent.
+- `warnings` — adjustments the CLI applies automatically (e.g. `P1 does not support quad (removed)`). A removed requirement is not fulfilled: resolve it with the user before paid execution, even when the normalized request is `valid=true`.
+- `generation_credits_estimate` — official list price of the generation step × candidates; `null` for P1, legacy models, imports and task references (not estimated, never zero). Chain steps are not included, so a chained run costs more.
 - `steps[].payload` — the exact body that would be POSTed. Local files show as `<upload:path>` (also listed in `pending_uploads`); chain steps use `<upstream>` for the task id that does not exist yet.
 - A bare task id with no local history entry cannot have its type checked offline: chain legality is reported as unverified in `warnings` and checked by the real run.
 - Without `--json` the same plan card as the real run is printed on stdout, followed by the warnings/errors and a verdict line.
@@ -105,9 +117,23 @@ Typical agent loop: dry-run → fix `errors` / adjust params → dry-run again u
 - Single task (no `--then`): `credits_consumed` is that task's spend; no `credits_breakdown`.
 - Model file / URL input: the result adds `normalize_scale`, the factor the import rescaled the model by (final size = original size × normalize_scale; `1` = untouched). The platform never scales it back; divide by it to recover the original size. With `--then`, the steps after the import do not return it, so the result carries the import's value.
 - Chained run: `credits_consumed` is the **total** across generation + every step, and `credits_breakdown` lists each task in run order (generation first). Human mode prints the same as `credits consumed (total): 145` followed by one indented line per task.
+- `--for ar-web` with its own chain (no `--then`): the generated GLB is downloaded too, so the result adds `source_output_dir` / `source_model_file` (GLB) beside `output_dir` / `model_file` (USDZ). A chain that stops early (not riggable) reports the source model it downloaded instead in the same two fields.
 
 Exit codes: 0 ok · 2 params · 3 auth · 4 credits · 5 content policy · 6 task failed · 7 network · 9 rate limit.
 
 ## Cost behavior
 
+- Since 0.8.0, `make` preflights every deterministic chain request before resolving local uploads, in both normal and dry-run modes.
+- Missing convert formats, incompatible rig/texture options, known rig/preset-family conflicts and disabled steps cannot produce a successful validated request.
+- Headless `-n 2` with an explicit or scenario-default chain is rejected before upload, including dry-run.
+- `valid=true` means the normalized local plan passed known rules, not that unknown passthrough fields or runtime source-dependent checks have been verified.
+- Removed P-series fields remain warnings and are absent from the payload.
+- Plan notes, normalized step parameters and final deliverables reflect the actual request rather than overridden scenario defaults.
+- Only the generation step is estimated, at official list price; P1, legacy models and chain steps are not.
+
+- The built-in anim chain leaves spec unspecified so rig-check can recommend a non-biped body.
+- Explicit non-biped spec is rejected by this CLI to avoid claiming an ineffective requirement was met; the upstream documentation describes spec as biped-only, not as a universally forbidden field.
+- A known v1.0 rig uses `preset:biped:*`; v2.5/v3.0 use generic/body-type presets. Unknown standalone sources are not assigned an invented rig version.
+- Dense-geometry negation has lexical Chinese/English safeguards, not full semantic understanding; choose an explicit model for ambiguous prompts.
+
 The plan card shows every call before anything is submitted; balance is pre-checked before submitting; failed tasks auto-refund frozen credits. After the run, `credits_consumed` / `credits_breakdown` report what was actually billed per task. `texture=false pbr=false` skips texture credits entirely (right for 3D printing).

package/skill/commands/process.md

@@ -1,6 +1,7 @@
 # tripo model / anim / mesh — processing steps
 
-All subcommands take input as: explicit argument (task id / @last / @name / file / URL) > piped stdin JSON > `@last`.
+All subcommands take input as: explicit argument (task id / @last / @name / file / URL) > piped stdin JSON > `@last` (only in an interactive terminal with nothing piped).
+Headless, a missing input never falls back to `@last`: empty stdin or no `task_id` exits 2, an upstream error JSON exits with the upstream's code, and nothing is submitted.
 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"]'`).
 

package/skill/commands/task.md

@@ -10,9 +10,9 @@ tripo task get @last --download --json
 
 ## tripo task watch <id>
 
-Block until the task finishes. In `--json` mode, progress streams as NDJSON events on stdout (`{"event":"progress",...}` lines) and the final task detail is the last line. `--download` grabs artifacts on success. `--timeout <seconds>` (default 1800).
+Block until the task finishes. Progress goes to stderr (plain lines in `--json` mode, one per progress change); stdout carries only the final task detail as one JSON line. `--download` grabs artifacts on success. `--timeout <seconds>` (default 1800).
 
-Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded) — or, if the error says `timeout`, that it is still running (watch it again; do not resubmit).
+Rules for agents: treat `watch` as synchronous; wait for the process to exit and read its one stdout JSON line; exit code 6 means the task failed (credits refunded) — or, if the error says `timeout`, that it is still running (watch it again; do not resubmit).
 
 ## tripo task list [ids...]
 

package/skill/commands/view.md

@@ -6,7 +6,7 @@ Starts a local model-viewer page and opens the browser (humans). Headless caller
 
 ## tripo redo [task|@last] [--seed N]
 
-Re-submits the recorded request with a fresh `model_seed` (identical otherwise). Only works for tasks created by this CLI (history holds the payload). Result is a new task, downloaded like `make`.
+Re-submits the recorded request with a fresh `model_seed` (identical otherwise). Only works for tasks created by this CLI (history holds the payload). Result is a new task, downloaded like `make`. It is a new paid task submitted at once, with no plan card and no confirmation: agents must ask the human before running it.
 
 ## tripo ai [request...]
 

package/skill/common-errors.md

@@ -4,7 +4,7 @@
 | --- | --- | --- | --- |
 | 3 | 1002 | authentication failed (invalid/missing API key) | set `TRIPO_API_KEY` or run `tripo login`; check the key wasn't revoked |
 | 3 | 1005 | forbidden (no permission for this resource) | check account permissions |
-| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, `smart_uv=true` on decimate v1.0/v2.0, non-GLB input to smartsegment `model`, `texture_quality=fast` on a texture version other than v3.5. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
+| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI strips unsupported P-series parameters with warnings (`quad` on P1; `smart_low_poly`, `generate_parts`, or `geometry_quality` on P1/P2). Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `smart_uv=true` on decimate v1.0/v2.0, non-GLB input to smartsegment `model`, `texture_quality=fast` on a texture version other than v3.5. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
 | 9 | 1007 | per-API-key rate limit | the CLI already waits out `X-RateLimit-Reset` / `Retry-After` (up to 60 s per wait, 3 retries); if it still exits 9, wait longer before re-running |
 | 9 | 2000 | per-account concurrency pool full (see table below) | the CLI waits out `Retry-After` (up to 60 s, 3 retries) first; then 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)? |
@@ -21,8 +21,10 @@
 | 8 | 2019 | file not found (token expired?) | re-upload; file tokens are short-lived |
 | 2 | 2020/2021/2022 | bad image URL / file too large / image too large | fix the URL or shrink the file |
 | 7 | 1000/1001 | server-side error | queries auto-retry on 1000, task creation does not (the task may already exist and be billed — check `tripo balance` frozen credits before re-running); if persistent, contact support with the `request_id` |
-| 6 | — | task failed server-side, or the watch timed out | failed / cancelled: frozen credits auto-refund (the error shows the task's `error_code` / `error_message`); `tripo redo` often succeeds with a new seed. `timeout`: the task is still running and is billed if it succeeds — `tripo task watch <id> --download`, never redo |
+| 6 | — | task failed server-side, or the watch timed out | failed / cancelled: frozen credits auto-refund (the error shows the task's `error_code` / `error_message`); `tripo redo` often succeeds with a new seed, but it is a new paid task with no plan card or confirmation, so ask the human first. `timeout`: the task is still running and is billed if it succeeds — `tripo task watch <id> --download`, never redo |
 | 7 | — | network/5xx | queries auto-retried 3×, task creation is not (follow the `suggestion`: check `tripo balance` before re-running); check `tripo doctor`; region mismatch (ov/cn) is a common cause |
+| 7 | — | task succeeded but downloading its artifacts failed | the task is finished and billed; the error JSON carries `task_id` — run `tripo task get <task_id> --download`, never re-make (batch marks the job `needs_attention`; `make -n` keeps the candidate with `download_error`) |
+| 2 | — | no task on stdin (headless process command with nothing piped, or an upstream that printed no task) | nothing was submitted; pass the input explicitly (`tripo model texture <task_id>` or `@last`). A failed upstream's error JSON is passed through with its own exit code |
 
 ## Concurrency pools (default per account; error 2000 when full)
 
@@ -42,7 +44,8 @@ Pools are independent: a full H-series pool does not block P-series or image tas
 - `complete` only accepts a `segment` task; `retarget` only accepts a `rig` task (a file/URL is refused before upload)
 - quad + GLTF export → rejected (quads cannot be stored in glTF; quad forces FBX output); use `--format FBX`
 - `texture_quality=fast` with an explicit texture version other than `v3.5-20260815` → rejected (omit the version and the CLI selects v3.5)
-- P1 + face_limit outside 50–20000 → rejected with a suggestion to use v3.1
+- P1 + face_limit outside 50–20000 → rejected; use P2 for 48–50000 triangles / 48–25000 quads, or H3.1 beyond P2
+- P2 + face_limit outside 48–50000 triangles (or 48–25000 with `quad=true`) → rejected; use H3.1 for a higher budget
 - decimate `smart_uv` on an explicit v1.0/v2.0 → rejected (v3.0 only); with no model given the CLI selects v3.0
 - multiview without a front view → rejected (name a file "front" or pass it first)
 - `-n` with `--then` needs an interactive terminal (pick the winner first, then chain)

package/skill/examples/animation.md

@@ -9,8 +9,10 @@ tripo make "a cartoon fox character, T-pose" --for anim --json --yes
 
 ## Step by step with pipes
 
+`--model tripo-p2` keeps the `anim` preset's model (P2, 100–130 credits per generation); without it, a plain T-pose prompt like this one routes to H3.1 (10–50 credits).
+
 ```bash
-tripo make "a robot soldier, T-pose" --json --yes \
+tripo make "a robot soldier, T-pose" --model tripo-p2 --json --yes \
   | tripo anim check --json \
   | tripo anim rig --spec mixamo --out-format fbx --json \
   | tripo anim retarget --animation preset:idle preset:walk preset:run --json

package/skill/examples/ar-web.md

@@ -4,20 +4,22 @@ iOS QuickLook needs USDZ; the web wants a small GLB. The ar-web scenario deliver
 
 ```bash
 tripo make product.jpg --for ar-web --json --yes
-# → v3.1 generate → decimate ≤20k faces (textures baked) → convert USDZ
-# GLB comes from the decimate step; USDZ from convert. Both under output_dir.
+# → P2 generate (face_limit 20000) → convert USDZ
+# GLB: source_model_file (in source_output_dir); USDZ: model_file (in output_dir).
 ```
 
 Tighter mobile budget:
 
 ```bash
-tripo make product.jpg --for ar-web --then decimate:8000,convert:usdz --json --yes
+tripo make product.jpg --for ar-web -p face_limit=8000 --json --yes
 ```
 
 Web-only (skip USDZ):
 
 ```bash
-tripo make product.jpg --then decimate:10000 --json --yes
+tripo make product.jpg --model tripo-p2 -p face_limit=10000 --json --yes
 ```
 
+`--then` replaces the preset's whole chain, so `--for ar-web --then ...` downloads only its final step. The GLB + USDZ dual download applies only to the preset's own chain.
+
 Faithful textures from the photo: image inputs default to `texture_alignment=original_image` server-side; add `-p texture_alignment=geometry` only for stylized re-texturing.

package/skill/examples/game-asset.md

@@ -1,10 +1,10 @@
 # Recipe: game assets
 
-## Mobile / low-poly (P1, clean topology, FBX)
+## Mobile / low-poly (P2, clean topology, FBX)
 
 ```bash
 tripo make "a stylized barbarian axe" --for game-mobile --json --yes
-# → P1, face_limit 15000, 2K textures, convert to FBX
+# → P2, face_limit 15000, 2K textures, convert to FBX
 ```
 
 Tighter budget and Unity delivery:
@@ -14,17 +14,28 @@ tripo make "a health potion bottle" --for game-mobile \
   -p face_limit=3000 --then convert:format=FBX,texture_size=1024 --json --yes
 ```
 
-## PC / console (v3.1, detailed PBR)
+## PC / console (P2, detailed PBR)
 
 ```bash
 tripo make "an ornate treasure chest, fantasy style" --for game-pc --json --yes
 ```
 
-## LODs from one high-poly
+P2 gives editable topology; with detailed textures the generation step costs 120 credits. For a hero asset where geometric fidelity matters more, add `--model tripo-v3.1` (detailed textures: 30 credits from text, 40 from an image).
+
+## LODs baked from one dense source (explicit H3.1)
+
+```bash
+tripo make "a dense high-poly stone golem source mesh" --model tripo-v3.1 --name dense-golem --json --yes
+tripo make @dense-golem --then decimate:5000,convert:fbx --json --yes        # bakes normals by default
+tripo make @dense-golem --then decimate:1500,convert:fbx --json --yes        # another LOD from the same source
+```
+
+## Separate editable parts (explicit H3.1)
 
 ```bash
-tripo make "a stone golem" --for game-pc --then decimate:5000 --json --yes   # bakes normals by default
-tripo make @last --then decimate:1500,convert:fbx --json --yes               # next LOD from the same source
+tripo make "a modular sci-fi crate with a separate lid and handles" \
+  --model tripo-v3.1 -p generate_parts=true --json --yes
+# → H3.1; parts disable texture/pbr, so re-texture later with `tripo model texture`
 ```
 
 ## Character with animations (see also examples/animation.md)

package/skill/examples/pipes.md

@@ -1,8 +1,8 @@
 # Recipe: shell pipelines & batch
 
-## NDJSON pipes
+## JSON pipes
 
-stdout of every task command is a single JSON line when piped; downstream commands read it from stdin:
+stdout of every task command is a single JSON line when piped; downstream commands read it from stdin. If an upstream command fails or prints no task, the downstream submits nothing and exits with the upstream's exit code (or 2):
 
 ```bash
 tripo make cat.png --json | tripo model texture --texture-quality detailed --json | tripo model convert --format FBX --json

package/skill/examples/print.md

@@ -17,13 +17,17 @@ tripo make "a phone stand" --for print \
 # or -p auto_size=true at generation for real-world meters
 ```
 
-## Color print (3MF with vertex colors)
+## Color print (OBJ with vertex colors)
 
 ```bash
-tripo make figurine.png --for print \
-  --then "convert:format=3MF,export_vertex_colors=true" --json --yes
+tripo make figurine.png --for print -p texture=true \
+  --then "convert:format=OBJ,export_vertex_colors=true" --json --yes
 ```
 
+- The print preset skips textures (`texture=false`); a color print needs them back with `-p texture=true` (texture credits apply).
+- The API's 3MF output is single color, and vertex colors are only exported to OBJ/GLTF.
+- Build the multi-color 3MF in your slicer from the OBJ.
+
 ## Fix holes / make watertight first
 
 ```bash

package/dist/i18n.js

@@ -1,19 +0,0 @@
-/** Minimal bilingual UX strings. Locale: config override > env (LANG/LC_ALL). */
-let currentLocale;
-export function setLocale(locale) {
-    currentLocale = locale;
-}
-export function getLocale() {
-    if (currentLocale)
-        return currentLocale;
-    const env = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
-    return /^zh/i.test(env) ? 'zh' : 'en';
-}
-/** Pick the localized variant of a bilingual pair. */
-export function t(pair) {
-    return getLocale() === 'zh' ? pair.zh : pair.en;
-}
-/** Pick the localized variant of a bilingual string list. */
-export function tList(pair) {
-    return getLocale() === 'zh' ? pair.zh : pair.en;
-}