tripo-cli 0.7.2 → 0.7.3

package/skill/commands/process.md

@@ -7,29 +7,30 @@ Any API parameter without a first-class flag can be passed with `-p key=value` (
 ## 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 +45,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 +105,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`.

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
@@ -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/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 already strips illegal P1 params. Classic 1004s: `generate_parts=true` with texture/pbr on, `ref_image` on segment v1, `quad=true` on P1, `smart_uv=true` on decimate v1.0/v2.0, non-GLB input to smartsegment `model`, `texture_quality=fast` on a texture version other than v3.5. `invalid model`: the API only accepts dated wire values (`P2-20260801`, `v3.1-20260211`…) — pass the CLI alias (`--model tripo-p2`) and let the CLI normalize, or the wire value itself; never `tripo-*` straight to the API. Table: `commands/generate` § "Models & Versions" |
+| 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,7 +21,7 @@
 | 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. `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 |
 
 ## Concurrency pools (default per account; error 2000 when full)
@@ -31,16 +32,16 @@
 | 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
+- `complete` only accepts a `segment` task; `retarget` only accepts a `rig` task (a file/URL is refused before upload)
+- quad + GLTF export → rejected (quads cannot be stored in glTF; quad forces FBX output); use `--format FBX`
+- `texture_quality=fast` with an explicit texture version other than `v3.5-20260815` → rejected (omit the version and the CLI selects v3.5)
 - P1 + face_limit outside 50–20000 → rejected with a suggestion to use v3.1
 - 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)

package/skill/examples/animation.md

@@ -30,4 +30,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/game-asset.md

@@ -31,5 +31,5 @@ tripo make @last --then decimate:1500,convert:fbx --json --yes               # n
 
 ```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)
 ```