tripo-cli 0.7.2 → 0.8.0

package/skill/commands/task.md

@@ -2,7 +2,7 @@
 
 ## tripo task get <id|@last|@name>
 
-Fetch one task. `--step` adds pipeline step details. `--download` fetches artifacts (output URLs expire in ~5 minutes, so the CLI always re-queries before downloading).
+Fetch one task. `--step` adds pipeline step details. `--download` fetches artifacts (output URLs expire in ~5 minutes, so the CLI always re-queries before downloading). Import tasks, and processing tasks whose model input was a file / URL, also carry `output.normalize_scale` (final size = original size × normalize_scale); `--download` records it in `task.json`.
 
 ```bash
 tripo task get @last --download --json
@@ -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...]
 
@@ -20,7 +20,7 @@ Batch query. With no ids, shows the most recent local history entries (server-re
 
 ## tripo files upload <path>
 
-Upload an image (≤20MB, PNG/JPEG/WebP/BMP/TIFF) or model (≤150MB, GLB/FBX/OBJ/STL). Prints `{"file_token":"file_..."}` — pass it anywhere an input is accepted. `.gltf` is not uploadable (it references external files) — export as `.glb` or pass a URL instead.
+Upload an image (≤20MB, PNG/JPEG/WebP/BMP/TIFF) or model (≤150MB, GLB/GLTF/FBX/OBJ/STL). Prints `{"file_token":"file_..."}` — pass it anywhere an input is accepted. Files over 60 MB and every `.gltf` go through a presigned URL. A `.gltf` must be self-contained (buffers/textures as `data:` URIs); one that references external files is rejected — export as `.glb` or pass a URL instead.
 
 ## tripo history
 

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,12 +4,13 @@
 | --- | --- | --- | --- |
 | 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` / 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 |
+| 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)? |
+| 2 | 2002 | unsupported request parameter | check field names and values against `tripo docs --topic commands/<cmd>` (some values need a newer model version) |
 | 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) |
+| 2 | 2004 | unsupported file type | images: PNG/JPEG/WebP/BMP/TIFF ≤20MB; models: GLB/GLTF/FBX/OBJ/STL ≤150MB (a `.gltf` must embed its buffers/textures — otherwise use .glb or a URL) |
 | 2 | 2005/2006/2007 | upstream task wrong type / not successful | the chain needs a successful task of the right type (the CLI validates locally first) |
 | 5 | 2008 | content policy violation | change the prompt/image |
 | 2 | 2009 | prompt contains invalid characters | remove unusual characters from the prompt |
@@ -20,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: frozen credits auto-refund; `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)
 
@@ -31,17 +34,18 @@
 | 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 |
+| model processing | texture, convert | 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
-- `complete` only accepts a `segment` task; `retarget` only accepts a `rig` task
-- quad + GLTF export → rejected (quads cannot be stored in glTF); use FBX/OBJ/USDZ
-- P1 + face_limit outside 50–20000 → rejected with a suggestion to use v3.1
+- `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; 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
@@ -30,4 +32,4 @@ tripo generate image-to-model @last --json --yes                          # imag
 tripo make @last --then rig-check,rig,retarget:preset:run --json --yes
 ```
 
-Rules: retarget needs a rig task (≤5 animations, billed per animation); the v2.5 rig (CLI default) covers all 7 body types; Unity Humanoid → `--spec mixamo`; in-game locomotion → `--animate-in-place`.
+Rules: retarget needs a rig task (≤5 animations, billed per animation); the v3.0 rig (CLI default) is best for humanoids and covers every body type (avian / others have no preset animations); Mixamo → `--spec mixamo`, Unity Humanoid → `--spec unity`, Unreal → `--spec unreal`; in-game locomotion → `--animate-in-place`.

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,22 +14,33 @@ 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)
 
 ```bash
 tripo make "a knight in full armor, T-pose, standing straight" --for anim --json --yes
-# chain: rig-check → rig(v2.5 rig) → retarget(idle+walk)
+# chain: rig-check → rig(v3.0 rig) → retarget(idle+walk)
 ```

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