tripo-cli 0.1.0

package/dist/util/spinner.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal stderr spinner. Interactive TTY gets an animated line; headless
+ * environments get sparse plain-text progress lines (never control codes).
+ */
+import pc from 'picocolors';
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export function createSpinner(initialText, quiet = false) {
+    const isTTY = Boolean(process.stderr.isTTY);
+    let text = initialText;
+    let frame = 0;
+    let timer;
+    let lastPlainLog = 0;
+    const render = () => {
+        process.stderr.write(`\r\x1b[2K${pc.cyan(FRAMES[frame % FRAMES.length])} ${text}`);
+        frame++;
+    };
+    const clearLine = () => {
+        if (isTTY)
+            process.stderr.write('\r\x1b[2K');
+    };
+    if (!quiet && isTTY) {
+        render();
+        timer = setInterval(render, 100);
+        timer.unref?.();
+    }
+    else if (!quiet) {
+        process.stderr.write(`${initialText}\n`);
+        lastPlainLog = Date.now();
+    }
+    return {
+        update(next) {
+            text = next;
+            if (quiet)
+                return;
+            if (!isTTY) {
+                // Throttle non-TTY progress to one line per 5s to keep logs readable.
+                if (Date.now() - lastPlainLog > 5000) {
+                    process.stderr.write(`${next}\n`);
+                    lastPlainLog = Date.now();
+                }
+            }
+        },
+        succeed(finalText) {
+            if (timer)
+                clearInterval(timer);
+            clearLine();
+            if (!quiet)
+                process.stderr.write(`${pc.green('✓')} ${finalText}\n`);
+        },
+        fail(finalText) {
+            if (timer)
+                clearInterval(timer);
+            clearLine();
+            process.stderr.write(`${pc.red('✗')} ${finalText}\n`);
+        },
+        stop() {
+            if (timer)
+                clearInterval(timer);
+            clearLine();
+        },
+    };
+}

package/dist/util/term-image.js

@@ -0,0 +1,28 @@
+/**
+ * Inline image display for capable terminals (iTerm2 OSC 1337; Kitty graphics
+ * protocol consumers also honor the iTerm sequence via icat shims). Falls back
+ * to returning false so callers can open the system viewer instead.
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+export function terminalSupportsInlineImages() {
+    if (!process.stdout.isTTY)
+        return false;
+    const program = process.env.TERM_PROGRAM ?? '';
+    const term = process.env.TERM ?? '';
+    return program === 'iTerm.app' || program === 'WezTerm' || term.includes('kitty');
+}
+export function printInlineImage(filePath, stream = process.stderr) {
+    if (!terminalSupportsInlineImages())
+        return false;
+    try {
+        const data = readFileSync(filePath);
+        const b64 = data.toString('base64');
+        const name = Buffer.from(basename(filePath)).toString('base64');
+        stream.write(`\x1b]1337;File=name=${name};size=${data.length};inline=1;width=40%:${b64}\x07\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/version.js

@@ -0,0 +1,10 @@
+import { readFileSync } from 'node:fs';
+export function cliVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "tripo-cli",
+  "version": "0.1.0",
+  "description": "Tripo 3D intelligent CLI — turn a prompt or an image into engine-ready 3D assets from your terminal (Tripo V3 API)",
+  "keywords": [
+    "tripo",
+    "3d",
+    "text-to-3d",
+    "image-to-3d",
+    "cli",
+    "ai",
+    "glb",
+    "fbx"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tripo": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vast-enterprise/Tripo-API-CLI.git"
+  },
+  "homepage": "https://github.com/vast-enterprise/Tripo-API-CLI#readme",
+  "bugs": {
+    "url": "https://github.com/vast-enterprise/Tripo-API-CLI/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/postbuild.mjs",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "e2e": "node scripts/e2e-smoke.mjs",
+    "pack:check": "node scripts/pack-check.mjs",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build && npm run pack:check"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^3.2.7",
+    "eslint": "^9.39.5",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^3.2.7"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,70 @@
+# Tripo CLI Skill
+
+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.
+
+## Install & auth
+
+```bash
+npm install -g tripo-cli        # or: npx tripo-cli ...
+export TRIPO_API_KEY=tsk_...    # highest-priority auth; no interaction needed
+tripo doctor                    # verify key, network, balance
+```
+
+If there is no key, ask the human to run `tripo login` or to provide `TRIPO_API_KEY`.
+
+Regions (ov = international, cn = China mainland) share one CLI: `tripo login --key tsk_...` auto-detects which region the key belongs to. 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 submits the task, polls, downloads artifacts, then exits. 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.
+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) · 7 network · 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 (see `commands/`).
+6. **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.
+
+## The one command you usually need
+
+```bash
+tripo make "a medieval knight, T-pose" --for game-mobile --json --yes
+tripo make concept.png --for print --json --yes
+tripo make front.png back.png --json --yes                # 2-4 views → multiview
+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 stylize convert import rig-check rig retarget segment complete decimate smartsegment`
+  - step args: `convert:format=FBX,texture_size=2048` (bare value = primary arg: `convert:fbx`, `stylize:lego`, `decimate:5000`)
+- Output JSON: `{"task_id","type","status","credits_consumed","output_dir","files",["model_file"],["preview"],["chain"]}`
+
+## Pipes (composing steps yourself)
+
+Downstream commands read the upstream task from stdin:
+
+```bash
+tripo make cat.png --json | tripo anim rig --json | tripo anim retarget --param animation=preset:walk --json
+```
+
+## Other commands
+
+| command | purpose |
+| --- | --- |
+| `tripo task get/watch <id> --download` | inspect / block on / download an existing task |
+| `tripo balance` / `tripo usage` | credits: `{"balance","frozen"}` / recent spend |
+| `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 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
+- `examples/` — copy-paste recipes per scenario (game/print/animation/...)
+- `common-errors.md` — error table with fixes
+
+Print any of them: `tripo docs --topic examples/game-asset`.

package/skill/commands/account.md

@@ -0,0 +1,41 @@
+# tripo login / balance / usage / topup / config / doctor
+
+## Auth
+
+```bash
+export TRIPO_API_KEY=tsk_...     # best for agents/CI — zero interaction
+tripo login                      # humans: browser flow (or --paste / --key tsk_...)
+tripo login --key tsk_... --region ov|cn
+tripo whoami                     # masked key + region + balance
+tripo logout                     # removes the local key only
+```
+
+Region decides the API host: ov → `openapi.tripo3d.ai`, cn → `openapi.tripo3d.com`.
+
+## Credits
+
+```bash
+tripo balance      # {"balance":1000,"frozen":50} — frozen = running tasks' holds
+tripo usage        # recent per-task spend
+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.
+
+## Config
+
+```bash
+tripo config list
+tripo config set region cn
+tripo config set llm.base_url https://api.openai.com/v1     # enables `tripo ai` conversation mode
+tripo config set llm.api_key sk-...
+tripo config set llm.model gpt-4o-mini
+tripo config context default_scenario=game-mobile output_dir=./assets   # per-directory .tripo/context.json
+```
+
+Env overrides: `TRIPO_API_KEY` `TRIPO_REGION` `TRIPO_API_BASE_URL` `TRIPO_LLM_BASE_URL` `TRIPO_LLM_API_KEY` `TRIPO_LLM_MODEL`.
+
+## tripo doctor
+
+Checks node version, key, API reachability, balance, config permissions, terminal capabilities. Exit 1 when a critical check fails. Run this first when anything misbehaves.

package/skill/commands/batch.md

@@ -0,0 +1,33 @@
+# tripo batch run
+
+Bulk production from a YAML manifest with concurrency, retries, and resume.
+
+```bash
+tripo batch run assets.yaml [--concurrency 2] [--retries 1] [--fresh]
+```
+
+## Manifest
+
+```yaml
+concurrency: 2
+defaults:
+  for: game-mobile
+  then: "texture,convert:fbx"
+  out: ./assets
+jobs:
+  - input: "a bronze sword"
+  - input: "a wooden shield"
+    name: shield            # names become @references and state keys
+  - input: cat.png
+    for: print
+    then: "convert:stl,flatten_bottom=true"
+  - inputs: [hero-front.png, hero-back.png]
+    name: hero
+    params: { texture_quality: detailed }
+```
+
+## 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":{...}}`.

package/skill/commands/generate.md

@@ -0,0 +1,34 @@
+# tripo generate — deterministic endpoint access
+
+Use `tripo make` unless you need exact endpoint control. All subcommands accept the shared task options (`--json --yes -o --no-wait --no-download --timeout --name -p key=value`).
+
+## 3D
+
+```bash
+tripo generate text-to-model "a ceramic teapot" [--model tripo-v3.1|tripo-p1] [-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]
+```
+
+Key params (hard rules enforced locally):
+- `pbr=true` implies `texture=true`
+- `generate_parts=true` excludes texture/pbr/quad (bare geometry; re-texture afterwards)
+- `quad=true` forces FBX output (quads cannot be stored in GLB)
+- P1: `face_limit` 50–20000; `quad`/`smart_low_poly`/`generate_parts`/`geometry_quality` unsupported
+- model aliases (`tripo-v3.1`/`tripo-p1`/`v3.0`/`v2.5`) are normalized to server wire versions automatically
+- `smart_low_poly=true`: face_limit 500–20000 (500–10000 with quad)
+- seeds: `image_seed` / `model_seed` / `texture_seed` — record them for reproducibility (task.json does this automatically)
+
+## 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-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
+```
+
+- image models: `seedream_v4` (t2i default) `seedream_v5` (i2i default) `banana` `banana_pro` `banana2` `chat_image_1` `chat_image_1.5` `chat_image_2`
+- templates — text-to-image: `asset_extraction character_completion t_pose variants figure`; image-to-image: `t_pose character_completion 3d_enhance variants figure`
+- `template=t_pose` is the golden pre-step for the animation pipeline

package/skill/commands/make.md

@@ -0,0 +1,47 @@
+# tripo make
+
+The magic command: input in, finished local 3D artifacts out. Blocking; exits when files are on disk.
+
+```
+tripo make <input...> [options]
+```
+
+## Inputs (auto-detected)
+
+| you pass | it runs |
+| --- | --- |
+| 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) |
+| 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 stylize convert import rig-check rig retarget segment complete decimate smartsegment`. Args: `step:key=value,...`; bare value maps to the step's primary arg (`convert:fbx` → format, `stylize:lego` → style, `decimate:5000` → face_limit, `retarget:preset:walk` → animation). Overrides the scenario chain.
+- `--model <m>` — force `tripo-v3.1` (high fidelity, default) or `tripo-p1` (low-poly; face_limit 50–20000; quad/parts/geometry_quality unsupported and stripped). The CLI normalizes these aliases to the wire versions (`v3.1-20260211` / `P1-20260311`) the server actually accepts.
+- `-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=...`.
+- `-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.
+- `--name <name>` — history name for `@name` references.
+- `--notify` — desktop notification when done.
+- `--timeout <seconds>` — watch timeout (default 1800).
+
+## Output (stdout, --json)
+
+```json
+{"task_id":"...","type":"convert_model","status":"success","credits_consumed":25,
+ "output_dir":"tripo-out/knight-1a2b3c4d","files":["model.fbx","preview.png","task.json"],
+ "model_file":".../model.fbx","preview":".../preview.png",
+ "chain":[{"task_id":"...","type":"texture_model"}]}
+```
+
+Exit codes: 0 ok · 2 params · 3 auth · 4 credits · 5 content policy · 6 task failed · 7 network · 9 rate limit.
+
+## Cost behavior
+
+Balance is pre-checked before submitting; failed tasks auto-refund frozen credits. `texture=false pbr=false` skips texture credits entirely (right for 3D printing).

package/skill/commands/process.md

@@ -0,0 +1,50 @@
+# tripo model / anim / mesh — processing steps
+
+All subcommands take input as: explicit argument (task id / @last / @name / file / URL) > piped stdin JSON > `@last`.
+Shared options: `--json --yes -o --no-wait --no-download --timeout --name -p key=value`.
+
+## 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 stylize [input] --style lego|voxel|voronoi|minecraft [--block-size 80]
+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] \
+    [--pivot-to-center-bottom] [--export-vertex-colors]
+tripo model import <file-or-url>            # GLB/GLTF/FBX/OBJ/STL ≤150MB
+```
+
+Notes: quad cannot export GLTF; vertex colors only in OBJ/GLTF; any non-default convert option bills as "complex convert".
+
+## 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 retarget [input] --animation preset:walk [preset:run ...] \
+    [--out-format glb|fbx] [--animate-in-place]
+```
+
+- retarget only accepts a rig task id; ≤5 animations, billed per animation
+- rig model wire versions: `v2.5-20260210` (CLI default) / `v1.0-20240301`; marketing names `rig-v1.0`/`rig-v2.0` are normalized automatically
+- v2.5 rig presets (all body types): `preset:idle walk run dive climb jump slash shoot hurt fall turn` (+ body-specific like `preset:quadruped:*`)
+- v1.0 rig presets (biped only): `preset:biped:idle` etc. (90+)
+- Mixamo/Unity Humanoid → `--spec mixamo` (+ `--fbx-preset mixamo` at convert time)
+- game code drives movement → `--animate-in-place`
+
+## tripo mesh
+
+```bash
+tripo mesh segment [input] [--model v1.0-20250506|v2.0-20260430]
+tripo mesh complete [input] [--completion-mode ai_completion|quick_cap]   # needs a segment task
+tripo mesh decimate [input] --face-limit 5000 [--quad] [--no-bake]        # 500–20000 tri / 500–10000 quad
+tripo mesh smartsegment <file-or-url> [--seg-type image|model] [--granularity coarse|medium|fine] [--hint "..."]
+```
+
+- decimate bakes textures onto the low-poly by default (right for LODs); `-p model=v1.0` allows up to 2M faces but requires `face_limit` and does not support bake/part_names
+- `mesh complete` only accepts segmentation tasks
+- smartsegment takes a file/URL only (no task ids); `--seg-type model` needs a GLB and a 4×4 transform — the CLI auto-fills the identity matrix

package/skill/commands/task.md

@@ -0,0 +1,27 @@
+# tripo task / files / history
+
+## 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).
+
+```bash
+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).
+
+Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded).
+
+## tripo task list [ids...]
+
+Batch query. With no ids, shows the most recent local history entries (server-refreshed). JSON output is `{"tasks":[...],"missed":[id,...]}` — `missed` lists ids the server could not find (wrong account/region).
+
+## 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.
+
+## tripo history
+
+Local task history with `@name` references: `{"task_id","type","name","status","output_dir"}`.

package/skill/commands/view.md

@@ -0,0 +1,25 @@
+# tripo view / redo / ai / mcp
+
+## tripo view [task|@last|file.glb]
+
+Starts a local model-viewer page and opens the browser (humans). Headless callers should read `preview.png` from the artifact directory instead — the files are already local; the browser is optional. `--keep` holds the server until Ctrl+C.
+
+## 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`.
+
+## tripo ai [request...]
+
+- Without an LLM configured: interactive wizard (3–4 questions) → plan card → confirm → run. Terminal required.
+- With an LLM (`tripo config set llm.*`): natural-language planning by producer + domain-specialist agents → same plan card → confirm (`--yes` skips) → run.
+- Agents: prefer `tripo make --for <scenario>` — it is deterministic and needs no LLM. `@task-name` references inside the request resolve to task ids.
+
+## tripo mcp
+
+MCP server on stdio for Cursor/Claude Desktop:
+
+```json
+{ "mcpServers": { "tripo": { "command": "tripo", "args": ["mcp"], "env": { "TRIPO_API_KEY": "tsk_..." } } } }
+```
+
+Tools: `tripo_make` (blocking generate+download), `tripo_task_get`, `tripo_task_wait`, `tripo_balance`, `tripo_history`.

package/skill/common-errors.md

@@ -0,0 +1,38 @@
+# Common errors & fixes
+
+| exit | api code | meaning | fix |
+| --- | --- | --- | --- |
+| 3 | 1002 | authentication failed (invalid/missing API key) | set `TRIPO_API_KEY` or run `tripo login`; check the key wasn't revoked |
+| 3 | 1005 | forbidden (no permission for this resource) | check account permissions |
+| 2 | 1003/1004 | malformed request / invalid parameter | check spelling against `tripo docs --topic commands/<cmd>`; the CLI already strips illegal P1 params |
+| 9 | 1007/2000 | rate or concurrency limit (task families share pools) | wait and retry with backoff; lower `--concurrency` in batch |
+| 8 | 2001 | task not found | task ids are account-scoped — same key that created it? right region (ov/cn)? |
+| 2 | 2003 | empty input file / unreachable URL | verify the file isn't empty and the URL is publicly accessible |
+| 2 | 2004 | unsupported file type | images: PNG/JPEG/WebP/BMP/TIFF ≤20MB; models: GLB/FBX/OBJ/STL ≤150MB (.gltf not uploadable — use .glb or a URL) |
+| 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 |
+| 4 | 2010 | insufficient credits | `tripo topup` (human action); `tripo balance` to check |
+| 2 | 2011/2012 | animation chain input invalid | rig-check needs a model-producing task; retarget needs a rig task |
+| 2 | 2015/2016/2017 | version/type deprecated or invalid | drop the explicit `--model`; the CLI default is current |
+| 2 | 2018 | too complex to remesh | lower `face_limit` or simplify the input model |
+| 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 | 1000 auto-retries; if persistent, contact support with the `request_id` |
+| 6 | — | task failed server-side | frozen credits auto-refund; `tripo redo` often succeeds with a new seed |
+| 7 | — | network/5xx | auto-retried 3×; check `tripo doctor`; region mismatch (ov/cn) is a common cause |
+
+## 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
+- 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)
+
+## Weird-but-normal
+
+- `model_url` in task output points to a file that may be named `pbr_model` etc. — normal, just download it (the CLI does).
+- Output URLs expire in ~5 minutes — never cache them; re-run `tripo task get <id> --download`.
+- `frozen` balance = holds for running tasks; it settles or refunds automatically.

package/skill/examples/animation.md

@@ -0,0 +1,33 @@
+# Recipe: character animation
+
+## One shot (generate → rig → animate)
+
+```bash
+tripo make "a cartoon fox character, T-pose" --for anim --json --yes
+# rig-check gates the chain: if not riggable it stops early (no credits wasted)
+```
+
+## Step by step with pipes
+
+```bash
+tripo make "a robot soldier, T-pose" --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
+```
+
+## Animate an existing model file
+
+```bash
+tripo make hero.glb --then rig-check,rig,retarget:preset:walk --json --yes
+```
+
+## T-pose image first (better rigging on tricky subjects)
+
+```bash
+tripo generate text-to-image "full-body front view of a ninja" -p template=t_pose --json --yes
+tripo generate image-to-model @last --json --yes                          # image task id works as input
+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`.

package/skill/examples/ar-web.md

@@ -0,0 +1,23 @@
+# Recipe: AR / Web / e-commerce
+
+iOS QuickLook needs USDZ; the web wants a small GLB. The ar-web scenario delivers both.
+
+```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.
+```
+
+Tighter mobile budget:
+
+```bash
+tripo make product.jpg --for ar-web --then decimate:8000,convert:usdz --json --yes
+```
+
+Web-only (skip USDZ):
+
+```bash
+tripo make product.jpg --then decimate:10000 --json --yes
+```
+
+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/film.md

@@ -0,0 +1,22 @@
+# Recipe: film / offline rendering
+
+Quads for subdivision, maximum quality, DCC handoff.
+
+```bash
+tripo make "an antique brass telescope" --for film --json --yes
+# → v3.1, quad=true (FBX out), geometry+texture detailed, 4K PBR
+```
+
+USD pipeline handoff:
+
+```bash
+tripo make @last --then convert:format=USDZ,texture_format=PNG --json --yes
+```
+
+HDR textures for compositing:
+
+```bash
+tripo make @last --then "convert:format=OBJ,texture_format=OPEN_EXR,texture_size=4096" --json --yes
+```
+
+Notes: quad topology cannot live in GLB — deliverables are FBX/OBJ/USD; `geometry_quality=detailed` bills an extra HD credit; non-default convert options bill as complex convert.

package/skill/examples/game-asset.md

@@ -0,0 +1,35 @@
+# Recipe: game assets
+
+## Mobile / low-poly (P1, clean topology, FBX)
+
+```bash
+tripo make "a stylized barbarian axe" --for game-mobile --json --yes
+# → P1, face_limit 15000, 2K textures, convert to FBX
+```
+
+Tighter budget and Unity delivery:
+
+```bash
+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)
+
+```bash
+tripo make "an ornate treasure chest, fantasy style" --for game-pc --json --yes
+```
+
+## LODs from one high-poly
+
+```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
+```
+
+## 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)
+```