tripo-cli 0.7.3 → 0.8.1

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;
-}