tripo-cli 0.7.2 → 0.8.0

package/skill/SKILL.md

@@ -1,8 +1,29 @@
+---
+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.
 
+When the calling host is known, set `TRIPO_CLIENT_APP` to its actual name
+(`codex`, `workbuddy`, `zcode`, `kimi`, `deepseek`, `claude`, `cursor`, or `chatgpt`) on each
+CLI command, including every command in a pipeline. Do not guess from the model,
+API key, account region, or an earlier call. Set `TRIPO_DISTRIBUTION_CHANNEL` only
+when a packaged plugin provides it; a standalone CLI install is not a plugin.
+These values are per-call metadata, never account-profile settings.
+
 ## Install & auth
 
 ```bash
@@ -22,30 +43,43 @@ login only works on the site it was started for.
 - no account yet: mainland China → `cn`, everywhere else → `ov`
 
 ```bash
-tripo login --region <cn|ov>    # the site the human named
+tripo login --region <cn|ov> --no-wait    # the site the human named
 ```
 
-It prints a verification URL and a one-time code, then blocks until the human
-approves in a browser (up to ~15 minutes — do not kill it early). Relay the URL
-and code to the human and tell them: sign in on that page first if it asks
+It prints a verification URL and a one-time code and exits at once. Relay the
+URL and code to the human and tell them: sign in on that page first if it asks
 (sign-up gives free credits), enter the code, pick an API key if the account has
-several (one is created automatically if there are none), click Authorize. The
+several (one is created automatically if there are none), click Authorize. When
+they say it is done, run the same command again: it finishes the login with that
+same code (`"status":"logged_in"`), or answers `"status":"pending"` if they have
+not authorized yet. Without `--no-wait` the command itself waits for the approval
+(up to ~15 minutes); if it gets cut off, rerunning resumes the same code. The
 key is then saved locally; never ask the human to paste a key into the chat. If
 the code expires (exit 3), just run the same command again; if the human says
-the page is the wrong site, stop it and rerun with the other `--region`.
+the page is the wrong site, rerun with the other `--region`.
 
 Regions (ov = international, cn = China mainland) share one CLI: `tripo login --key tsk_...` auto-detects which region the key belongs to. Already logged into the wrong site? `tripo login --region <other>` replaces the active profile's key and region. On exit code 3 (auth), run `tripo doctor` — it diagnoses key-vs-region mismatches and prints the exact fix (`tripo config set region cn|ov`).
 
 ## 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
 
@@ -57,10 +91,11 @@ 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`
-- `--then` chain steps: `refine texture convert import rig-check rig retarget segment complete decimate uv smartsegment`
+- `--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"],["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)
 
@@ -70,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 |
@@ -79,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

@@ -8,13 +8,18 @@ export TRIPO_API_KEY=tsk_...     # zero interaction when a key is already provis
 tripo login                      # humans in a terminal: interactive browser flow
 tripo login --region ov|cn       # agents/CI without a key: headless device flow — prints a
                                  # verification URL + one-time code on stderr, waits for the
-                                 # human to authorize in a browser (≤15 min), saves the key
+                                 # human to authorize in a browser (≤15 min), saves the key;
+                                 # rerunning after an interruption resumes the same code
+tripo login --region ov|cn --no-wait
+                                 # chat agents: print the URL + code and exit at once; rerun
+                                 # it after the human authorizes → "logged_in" (or "pending")
 tripo login --key tsk_... --region ov|cn
 tripo whoami                     # masked key + active profile + region + balance
 tripo logout                     # removes the local key of the active profile only
 ```
 
 Region decides the API host: ov → `openapi.tripo3d.ai`, cn → `openapi.tripo3d.com`.
+`tripo login` probes both regions with the key and stores the right one; a key from `TRIPO_API_KEY` is **not** probed — a China-region key also needs `TRIPO_REGION=cn`.
 
 ## Multiple accounts (profiles)
 
@@ -35,7 +40,7 @@ tripo topup        # opens the billing page, then polls until credits arrive
 ```
 
 Exit code 4 anywhere = insufficient credits → tell the human to run `tripo topup`.
-Failed tasks refund their frozen credits automatically.
+Failed / cancelled tasks refund their frozen credits automatically.
 
 ## Config
 
@@ -49,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

@@ -9,16 +9,17 @@ Everything below is the full parameter reference from the official API docs —
 tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1|tripo-p2] [-p face_limit=15000] ...
 tripo generate image-to-model photo.png [-p texture_alignment=original_image] [-p orientation=align_image]
 tripo generate multiview-to-model front.png back.png [left.png right.png]
+tripo generate multiview-to-model @last          # reuse the 4 views of an image-to-multiview / edit-multiview task
 ```
 
 ### 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 |
@@ -31,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 48–20000 (CLI enforces ≥50); **no** `quad` `smart_low_poly` `generate_parts` `geometry_quality`; ~2s mesh; extra `export_uv` |
-| `tripo-p2` | `P2-20260801` | **Preview** (2026-08) | P1 upgrade (P series) | adds `quad` (forces FBX); face_limit 48–50000 tri / 48–25000 quad (validated locally); still **no** `smart_low_poly` `generate_parts` `geometry_quality` (stripped with a warning); credits 100 (no texture) / 110 / 120 / 130 for standard / detailed / extreme. Explicit `--model` only — the CLI never auto-selects it |
+| `tripo-v3.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>
@@ -56,10 +65,12 @@ Official docs (ov / cn):
 | `input` | — | image | `file_` token, `http(s)://` URL or `task_` id (e.g. a text-to-image task) — the CLI uploads local files for you |
 | `inputs` | — | multiview | see "multiview inputs" below |
 | `model_seed` / `image_seed` / `texture_seed` | random | all | geometry / text-to-image stage / texture seeds — the key to reproducibility (`task.json` records them) |
-| `face_limit` | adaptive | all | max polycount; P1 48–20000, P2 48–50000 |
+| `face_limit` | adaptive | all | max polycount; P1 50–20000, P2 48–50000 (quad 48–25000) |
 | `texture` | `true` | all | set `false` for bare geometry (print / re-texture later) — saves credits |
 | `pbr` | `true` | all | PBR maps; **forces `texture=true`** |
-| `texture_quality` | `standard` | all | `standard` / `detailed` / `extreme` (price tiers) |
+| `texture_quality` | `standard` | all | `fast` (texture v3.5 only, same price as standard) / `standard` / `detailed` / `extreme` (8K, extra credits) |
+| `texture_version` | derived from `model` | all | texture model, decoupled from geometry: `v3.5-20260815` (latest) / `v3.0-20250812` (v3.x and P default) / `v2.5-20250123`. Required by `fast` and `delight` — the CLI fills in v3.5 when you omit it; `fast` with another version is rejected locally |
+| `delight` | `true` | all | remove lighting baked into the reference before texturing; `false` keeps the original shading. Texture v3.5 only (older versions ignore it) |
 | `geometry_quality` | `standard` | v3.x | `detailed` = Ultra mode (extra HD credit) |
 | `auto_size` | `false` | all | scale to real-world metres |
 | `quad` | `false` | v3.x, P2 | quad mesh; **forces FBX output** (quads cannot live in GLB) |
@@ -67,7 +78,7 @@ Official docs (ov / cn):
 | `generate_parts` | `false` | v3.x | editable segmented parts — see rules below |
 | `compress` | — | v3.x | `geometry` = meshopt compression |
 | `export_orientation` | `+x` | all | forward axis `+x` / `-x` / `+y` / `-y` — see warning below |
-| `export_uv` | `true` | P series only | `false` = faster, smaller file (no UV unwrap) |
+| `export_uv` | `true` | all | `false` = faster, smaller file (UVs are unwrapped at the texture stage instead) |
 | `enable_image_autofix` | `false` | image | auto-repair low-quality inputs |
 | `texture_alignment` | `original_image` | image, multiview | `original_image` (match the picture) / `geometry` (match the mesh) |
 | `orientation` | `default` | image, multiview | `align_image` = align the model to the input viewpoint |
@@ -88,13 +99,14 @@ The API accepts three `inputs` shapes (never mix them):
 - **legacy positional**: exactly 4 strings `[front, left, back, right]`, `""` skips a slot.
 - **task_id**: `[{"task_id":"<image-to-multiview or edit-multiview task>"}]` to reuse a 4-view sheet (source task must be `success`).
 
-The CLI builds view-key payloads from your files: filename hints (`front|back|left|right`, or 正面/背面/左/右) win; otherwise positional order front, left, back, right. A front view is mandatory.
+The CLI builds view-key payloads from your files: filename hints (`front|back|left|right`, or 正面/背面/左/右) win; otherwise positional order front, left, back, right. A front view is mandatory. A single task id / `@ref` argument is sent in the task_id shape instead (a `@ref` of another task type is rejected locally).
 
 ## Images (2D pipeline before 3D)
 
 ```bash
 tripo generate text-to-image "front view of a knight, T-pose" [-p template=t_pose] [--model seedream_v4]
 tripo generate image-to-image sketch.png --prompt "make it look like clay" [--model seedream_v5]
+tripo generate image-to-image hero.png outfit.png --prompt "the character from image[1] wearing the outfit from image[2]"
 tripo generate image-to-multiview photo.png     # 1 image → 4-view sheet
 tripo generate edit-multiview <multiview-task-id> -p 'prompts=[{"view":"front","prompt":"add a sword"}]'
 tripo generate image-to-splat photo.png         # gaussian splat
@@ -106,26 +118,48 @@ 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 |
-| `gemini-2.5-flash` / `gemini-3-pro` / `gemini-3.1-flash` | Google | GA | fast / high quality / latest fast. Backend aliases `banana` / `banana_pro` / `banana2` are also accepted |
-| `chat_image_1` / `chat_image_1.5` | OpenAI | retiring 2026-10-23 / 2026-12-01 | GPT image; 1.5 = higher quality — move to `chat_image_2` |
-| `chat_image_2` | OpenAI | GA | GPT latest |
+| `banana` / `banana_pro` / `banana2` | Google | GA | fast / higher quality / latest fast |
+| `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 |
-| `input` | — | i2i, i2mv, edit-mv, splat | `file_` token / URL (i2i also accepts a `task_` id) |
-| `inputs` | — | i2i | multiple reference images: seedream ≤4, gemini ≤10 (gpt ≤16); reference them in the prompt as `[image 1]`, `[image 2]`… |
-| `template` | — | t2i, i2i | `asset_extraction` `character_completion` `t_pose` `head_extraction` `3d_enhance` `variants` `print_clay` `figure` |
-| `t_pose` | `false` | t2i, i2i | boolean shortcut: convert the subject to a T-pose |
-| `sketch_to_render` | `false` | t2i, i2i | turn a sketch into a rendered image |
+| `input` | — | i2i, i2mv, edit-mv, splat | `file_` token / URL (i2i also accepts a `task_` id); i2i: JPEG/PNG ≤20 MB, ≤36 MP |
+| `inputs` | — | i2i | multiple reference images (the CLI sends this when you pass several images): seedream ≤4, banana ≤10, chat_image ≤16; cite them in the prompt as `image[1]`, `image[2]`… |
+| `template` | — | t2i, i2i | t2i: `asset_extraction` `character_completion` `t_pose` `variants` `figure`; i2i: `t_pose` `character_completion` `3d_enhance` `variants` `figure` |
+| `size` | `2048x2048` | t2i, i2i | keyword (`2K` / `4K`) or exact pixels; accepted values differ per model |
+| `quality` | `low` | t2i, i2i | `chat_image_2`: `low` `medium` `high`; `chat_image_2.5_*`: also `xhigh` `max` (no `auto`). Other models reject it. `high` and above cost more credits |
+| `background` | model decides | t2i, i2i | `chat_image_2.5_*` only (ignored elsewhere): `auto` / `opaque` / `transparent`; `transparent` requires `output_format=png` |
+| `aspect_ratio` | `1:1` | t2i, i2i | banana family only: `1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9` (banana2 adds `1:8 1:4 4:1 8:1`); seedream / chat_image use `size` |
+| `output_format` | `png` | t2i, i2i | `png` (lossless, alpha) / `jpeg` (smaller, no alpha) |
+| `watermark` | `false` | t2i | AI-content watermark, seedream only (banana always embeds an invisible one; chat_image has no control) |
 | `model_seed` | random | splat | same seed + same image = repeatable `.splat` |
 
-- `template=t_pose` (or `t_pose=true`) is the golden pre-step for the animation pipeline; `3d_enhance` cleans a photo before image-to-model; `print_clay` previews a single-colour print look.
-- Sizes are billed in 1K / 2K / 4K tiers; `aspect_ratio` is only honoured by the gemini family.
+- `template=t_pose` is the golden pre-step for the animation pipeline; `3d_enhance` (i2i) cleans a photo before image-to-model.
+- Sizes are billed in 1K / 2K / 4K tiers.
 - `image-to-multiview` output: `front_view_url` `left_view_url` `back_view_url` `right_view_url` — feed them (or the task id, see above) to `multiview-to-model`.
 - `edit-multiview` takes a successful `image-to-multiview` task; `prompts` is 1–4 `{view, prompt}` objects.
 - `image-to-splat` returns a `.splat` file in `output.model_url` (not a mesh — no texture / rig / convert downstream). Fixed **30 credits**, ~4 minutes. Input PNG / JPEG / WebP ≤20 MB, ≥256×256 px, subject clear and centred. Use image-to-model when you need an editable mesh.

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
 ──────────────────────────────────
 ```
 
@@ -34,17 +40,21 @@ In a TTY it then asks `Run this plan?`; answering no exits 0 with `cancelled; no
 | quoted text | text-to-model |
 | one image (.png/.jpg/.jpeg/.webp/.bmp) or image URL | image-to-model |
 | 2–4 images | multiview-to-model (filename hints front/back/left/right win; otherwise positional front,left,back,right; front required) |
-| a model file (.glb/.gltf/.fbx/.obj/.stl) | import (add --then for processing) |
+| a model file or model URL (.glb/.gltf/.fbx/.obj/.stl) | import (add --then for processing) |
 | task id / `@last` / `@name` | continue processing from that task (--then required) |
 
 ## 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 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".
+- `--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 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}},
-   {"name":"rig","endpoint":"/v3/animations/rig","task_type":"animate_rig","payload":{"input":"<upstream>","model":"v2.5-20260210"}},
+    "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.
@@ -103,10 +115,25 @@ 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,35 +1,37 @@
 # 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"]'`).
 
 ## tripo model
 
 ```bash
-tripo model refine [input]                  # only accepts text_to_model tasks
-tripo model texture [input] --texture-quality detailed --texture-alignment geometry [-p pbr=true]
+tripo model texture [input] [--model v3.5-20260815|v3.0-20250812|v2.5-20250123] \
+    --texture-quality fast|standard|detailed|extreme --texture-alignment geometry [-p pbr=true] [-p delight=false]
 tripo model convert [input] --format GLTF|USDZ|FBX|OBJ|STL|3MF \
     [--texture-size 2048] [--texture-format JPEG|PNG|OPEN_EXR|...] [--face-limit N] \
-    [--quad] [--flatten-bottom] [--fbx-preset blender|3dsmax|mixamo] \
-    [--export-orientation +x|-x|+y|-y] [--scale-factor 1.5] [--auto-size] \
+    [--quad] [--flatten-bottom] [--fbx-preset blender|3dsmax|mixamo|bake_scale] \
+    [--export-orientation +x|-x|+y|-y] [--scale-factor 1.5] \
     [--pivot-to-center-bottom] [--export-vertex-colors]
 tripo model import <file-or-url>            # GLB/GLTF/FBX/OBJ/STL ≤150MB
 ```
 
 | 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 |
+| `texture` | task / file / URL (file/URL is imported implicitly) | `model` `v3.0-20250812` (default) / `v3.5-20260815` (latest; required by `fast` and `delight` — the CLI selects it when you use them without `--model`, and rejects `fast` with another version) / `v2.5-20250123`; `texture_quality` fast/standard/detailed/extreme; `delight` (default true, v3.5 only: strip baked lighting from the reference); `pbr` (default true); `texture_seed`; `texture_alignment` original_image/geometry |
 | `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` |
+| `import` | file / URL | GLB / GLTF / FBX / OBJ / STL ≤150 MB. A self-contained `.gltf` (buffers/images embedded as `data:` URIs) uploads fine; one that references external `.bin`/textures is rejected locally — export `.glb` or pass a URL. Output adds `normalize_scale`: final size = original size × normalize_scale (`1` = untouched); divide by it to recover the original size. Texture / convert / rig etc. on a file / URL input return it too (they import first); task-id inputs do not |
+
+Local files over 60 MB (and every `.gltf`) are uploaded through a presigned URL instead of multipart; the limits stay 20 MB per image and 150 MB per model.
 
 ### 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 | `quad` | false | quad remesh; **forces FBX output** (GLTF is rejected locally, other formats are overridden — pass `--format FBX`) |
 | 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 |
@@ -44,35 +46,38 @@ tripo model import <file-or-url>            # GLB/GLTF/FBX/OBJ/STL ≤150MB
 | 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) |
+| export | `fbx_preset` | blender | `blender` / `3dsmax` / `mixamo` / `bake_scale` (bake the scale transform into the geometry) — FBX only |
 
-Billing: any non-default convert option bills as "complex convert" (pricier than a plain format swap).
+Billing: a non-default `quad`, `flatten_bottom`, `flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills as "complex convert" (pricier than a plain format swap).
 
 ## tripo anim
 
 ```bash
-tripo anim check [input]                    # rig-check: {"riggable":true,"rig_type":"biped"}; GLB input only
-tripo anim rig [input] [--rig-type biped|quadruped|hexapod|octopod|avian|serpentine|aquatic] \
-    [--spec tripo|mixamo] [--out-format glb|fbx]      # CLI defaults model=v2.5-20260210 (all body types)
+tripo anim check [input]                    # rig-check: {"riggable":true,"rig_type":"biped"}; GLB/FBX/OBJ/STL input
+tripo anim rig [input] [--model v3.0-20260909|v2.5-20260210|v1.0-20240301] \
+    [--rig-type biped|quadruped|hexapod|octopod|avian|serpentine|aquatic|others] \
+    [--spec tripo|mixamo|actorcore|unity|unreal|vrm] [--out-format glb|fbx]   # CLI defaults model=v3.0-20260909
 tripo anim retarget [input] --animation preset:walk [preset:run ...] \
     [--out-format glb|fbx] [--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) |
+| `check` (rig-check) | task / file / URL — GLB / FBX / OBJ / STL, ≤150 MB | none. Output: `riggable` (bool) + recommended `rig_type` (one of the 7 types below, never `others`). Run it first: not riggable → stop before spending rig credits |
+| `rig` | task / file / URL (GLB / FBX / OBJ / STL ≤150 MB) | `model`: `rig-v3.0` (wire `v3.0-20260909`, **CLI default**: recommended for humanoids — much better and faster biped rigs; other body types behave like v2.5) / `rig-v2.5` (alias `rig-v2.0`, wire `v2.5-20260210`: animals; biped works but v3.0 is better) / `rig-v1.0` (wire `v1.0-20240301`, server default, biped only); `rig_type` biped/quadruped/hexapod/octopod/avian/serpentine/aquatic/others (default biped — use rig-check's value; `others` = none of the above, v3.0 only); `spec` (biped only) tripo/mixamo/actorcore/unity/unreal/vrm (actorcore/unity/unreal/vrm need v3.0); `out_format` glb/fbx |
+| `retarget` | **rig task id only** | `animation` (one) or `animations` (list, ≤5, billed per animation); `out_format` glb/fbx; `export_with_geometry` (default true); `animate_in_place` (default false); `bake_animation` is deprecated and ignored |
 
-- 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).
+- Marketing names `rig-v1.0` / `rig-v2.0` / `rig-v2.5` / `rig-v3.0` are normalized to the wire versions automatically (sending them raw is a 400).
+- Mixamo → `--spec mixamo` (+ `--fbx-preset mixamo` at convert time); Unity Humanoid → `--spec unity`; Unreal Mannequin → `--spec unreal`; ActorCore / VRM 1.0 → `--spec actorcore` / `--spec vrm`.
 - Game code drives movement → `--animate-in-place`.
-- The preset set depends on **which rig model the upstream rig task used**.
+- The preset set depends on **which rig model and rig type the upstream rig task used**.
+- In `make` / `--then` chains, a non-biped rig gets its own preset instead of the biped ones (quadruped / hexapod / octopod → `:walk`, serpentine / aquatic → `:march`); avian / others have no presets, so the chain stops after rig and keeps the rigged model.
 
-### Presets for rig v2.0 / v2.5 (all rig types)
+### Presets for rig v2.5 / v3.0
 
-`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`
+- biped: `preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` `preset:fall` `preset:turn`
+- quadruped: `preset:quadruped:walk`; hexapod: `preset:hexapod:walk`; octopod: `preset:octopod:walk`; serpentine: `preset:serpentine:march`; aquatic: `preset:aquatic:march`
+- avian / others: none
 
 ### Presets for rig v1.0 (biped only, 90+)
 
@@ -101,7 +106,7 @@ tripo mesh smartsegment <file-or-url> [--seg-type image|model] [--granularity co
 | `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 / URL | `model` `v2.0` (default, smart retopology, 30 credits) / `v3.0` (newest retopology, 35 credits tri / 40 quad) / `v1.0` (basic decimation, 10 credits); `face_limit` (v2.0/v3.0: optional, 500–20000 tri / 500–10000 quad, adaptive if omitted); `quad`; `bake` (default true — bake textures onto the low-poly, right for LODs); `part_names`; `smart_uv` (**v3.0 only**, default false — unwrap UVs in the same task, no extra cost, no UV atlas image; `--smart-uv` without `--model` selects v3.0, an explicit v1.0/v2.0 is rejected locally because the server answers `1004`). `--model v1.0`: up to 2,000,000 tri / 150,000 quad but `face_limit` becomes required and `bake`/`part_names` are unsupported |
 | `uv` | task / file / URL | re-unwraps UVs and remaps the existing textures, rig and animation onto the new layout; **20 credits**. `bake` (default true; `--no-bake` returns geometry + UVs only); `export_orientation` `+x`/`-x`/`+y`/`-y`; `compress` `geometry` (meshopt, `-p compress=geometry`); `model` `default` (only value). **Input ≤ 80,000 equivalent triangles** (a quad counts as two): larger inputs are accepted, then the task fails and refunds — decimate first |
-| `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 |
+| `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: `image` for an image file/URL, else `model`; `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`.