tripo-cli 0.3.2 → 0.5.0

package/skill/commands/make.md

@@ -6,6 +6,27 @@ The magic command: input in, finished local 3D artifacts out. Blocking; exits wh
 tripo make <input...> [options]
 ```
 
+## Before anything is spent: the plan card
+
+`make` first prints a plan card on stderr — input, scenario, model, then **one numbered line per API call** (endpoint, what it does, its args), deliverables and cost notes:
+
+```
+── Plan ──────────────────────────
+input: a medieval knight
+scenario: game-mobile (Mobile game / low-poly)
+model: P1-20260311 — scenario game-mobile
+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
+     format="FBX" texture_size=2048
+deliverables: FBX, GLB
+──────────────────────────────────
+```
+
+In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no credits spent`. `--yes` (auto-enabled when stdin/stdout are not TTYs, i.e. for agents and pipes) skips the question but still prints the card, so the log shows exactly what ran. `--quiet` hides it.
+
 ## Inputs (auto-detected)
 
 | you pass | it runs |
@@ -20,7 +41,7 @@ tripo make <input...> [options]
 
 - `--for <scenario>` — `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`. Sets model+params+chain+format from the domain knowledge base.
 - `--then <steps>` — processing chain, comma-separated. Steps: `refine texture stylize convert import rig-check rig retarget segment complete decimate smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `stylize:lego` → style, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
-- `--model <m>` — force `tripo-v3.1` (high fidelity, default) or `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311`) the server actually accepts.
+- `--model <m>` — force `tripo-v3.1` (high fidelity, default), `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped) or `tripo-p2` (P-series preview; adds quad, face_limit 48–50000 tri / 48–25000 quad; never auto-selected). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311` / `P2-20260801`) the server actually accepts. Full table with status (GA / Preview / Legacy) and official links: `tripo docs --topic commands/generate` → "Models & Versions".
 - `-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=...`.
@@ -30,18 +51,62 @@ tripo make <input...> [options]
 - `--name <name>` — history name for `@name` references.
 - `--notify` — desktop notification when done.
 - `--timeout <seconds>` — watch timeout (default 1800).
+- `--yes` (global) — skip the plan-card confirmation; implied when headless.
+- `--dry-run` — plan + validate only; nothing is uploaded or submitted, no credits spent. See below.
+
+## 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.
+
+```bash
+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",
+ "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}},
+   {"name":"rig","endpoint":"/v3/animations/rig","task_type":"animate_rig","payload":{"input":"<upstream>","model":"v2.5-20260210"}},
+   {"name":"convert","endpoint":"/v3/models/convert","task_type":"convert_model","payload":{"input":"<upstream>","format":"FBX"}}],
+ "pending_uploads":["concept.png"],
+ "deliverables":["FBX","GLB"],
+ "candidates":1,
+ "warnings":["--then overrides the default game-mobile processing chain"],
+ "errors":[],
+ "cost_notes":[]}
+```
+
+- `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.
+- `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.
+
+Typical agent loop: dry-run → fix `errors` / adjust params → dry-run again until `valid` → drop `--dry-run` and run for real.
 
 ## Output (stdout, --json)
 
 ```json
-{"task_id":"...","type":"convert_model","status":"success","credits_consumed":25,
+{"task_id":"...","type":"convert_model","status":"success",
+ "credits_consumed":145,
+ "credits_breakdown":[
+   {"task_id":"<generation>","type":"text_to_model","credits_consumed":110},
+   {"task_id":"<texture>","type":"texture_model","credits_consumed":30},
+   {"task_id":"<convert>","type":"convert_model","credits_consumed":5}],
  "output_dir":"tripo-out/knight-1a2b3c4d","files":["model.fbx","preview.png","task.json"],
  "model_file":".../model.fbx","preview":".../preview.png",
- "chain":[{"task_id":"...","type":"texture_model"}]}
+ "source_task_id":"<generation>",
+ "chain":[{"task_id":"<texture>","type":"texture_model","credits_consumed":30},{"task_id":"<convert>","type":"convert_model","credits_consumed":5}]}
 ```
 
+- Single task (no `--then`): `credits_consumed` is that task's spend; no `credits_breakdown`.
+- 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.
+
 Exit codes: 0 ok · 2 params · 3 auth · 4 credits · 5 content policy · 6 task failed · 7 network · 9 rate limit.
 
 ## Cost behavior
 
-Balance is pre-checked before submitting; failed tasks auto-refund frozen credits. `texture=false pbr=false` skips texture credits entirely (right for 3D printing).
+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

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

package/skill/common-errors.md

@@ -4,8 +4,9 @@
 | --- | --- | --- | --- |
 | 3 | 1002 | authentication failed (invalid/missing API key) | set `TRIPO_API_KEY` or run `tripo login`; check the key wasn't revoked |
 | 3 | 1005 | forbidden (no permission for this resource) | check account permissions |
-| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params |
-| 9 | 1007/2000 | rate or concurrency limit (task families share pools) | wait and retry with backoff; lower `--concurrency` in batch |
+| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, non-GLB input to smartsegment `model` / rig-check. `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 | wait and retry with backoff; honour `Retry-After` / `X-RateLimit-Reset` headers |
+| 9 | 2000 | per-account concurrency pool full (see table below) | wait for a task in that category to finish, or lower `--concurrency` in batch; other categories are unaffected |
 | 8 | 2001 | task not found | task ids are account-scoped — same key that created it? right region (ov/cn)? |
 | 2 | 2003 | empty input file / unreachable URL | verify the file isn't empty and the URL is publicly accessible |
 | 2 | 2004 | unsupported file type | images: PNG/JPEG/WebP/BMP/TIFF ≤20MB; models: GLB/FBX/OBJ/STL ≤150MB (.gltf not uploadable — use .glb or a URL) |
@@ -22,6 +23,19 @@
 | 6 | — | task failed server-side | frozen credits auto-refund; `tripo redo` often succeeds with a new seed |
 | 7 | — | network/5xx | auto-retried 3×; check `tripo doctor`; region mismatch (ov/cn) is a common cause |
 
+## Concurrency pools (default per account; error 2000 when full)
+
+| category | task types | default concurrency |
+| --- | --- | --- |
+| 3D generation — H series | text/image/multiview-to-model on `tripo-v3.x` / `v2.5` | 10 |
+| 3D generation — P series | text/image/multiview-to-model on `tripo-p1` / P2 | 5 |
+| image generation | text-to-image, image-to-image, image-to-multiview, edit-multiview | **1** |
+| animation | rig-check, rig, retarget | 10 |
+| model processing | texture, convert, refine | 5 |
+| mesh operations | segment, complete, decimate | 10 |
+
+Pools are independent: a full H-series pool does not block P-series or image tasks. Image generation is serial by default — do not fan out text-to-image jobs. Higher limits are granted on request via support.
+
 ## Frequent local validations (caught before spending credits)
 
 - `refine` only accepts a successful `text_to_model` task
@@ -31,8 +45,15 @@
 - 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)
 
+All of these surface in `tripo make ... --dry-run --json` as `errors` (blocking) or `warnings` (auto-adjusted) before anything is uploaded or submitted.
+
 ## Weird-but-normal
 
 - `model_url` in task output points to a file that may be named `pbr_model` etc. — normal, just download it (the CLI does).
 - Output URLs expire in ~5 minutes — never cache them; re-run `tripo task get <id> --download`.
 - `frozen` balance = holds for running tasks; it settles or refunds automatically.
+- `credits_consumed` / `balance` / `frozen` are decimals (e.g. `48.00`) — parse as float, never as int.
+- Task status can also be `banned` (content policy — change the input) or `expired` (output files gone — regenerate); the CLI treats both as terminal failures.
+- A downstream step after a generation that used `export_orientation` succeeds but comes out **wrongly oriented** — no error is raised. Set the orientation on the final `convert` step instead.
+- `generate_parts` with `smart_low_poly=true` silently produces no parts (smart_low_poly wins); with `quad=true` the parts are triangles.
+- `image-to-splat` yields a `.splat`, not a mesh — texture / rig / convert steps cannot follow it.