Update to Tripo 3D

{
  "description": "Generate a 3D model from a text prompt, a reference image, or an existing mesh, and write it into the project as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like \"make me a low-poly X\", \"turn this image into 3D\", \"rig this character\", \"convert this model to FBX\", \"split this model into parts\", \"unwrap its UVs\", or \"generate placeholder assets\". Also use to re-run, convert or inspect a previous Tripo generation, and to answer questions about which Tripo model, parameter or step to use and what it costs — model versions (H series tripo-v3.1, P series tripo-p1 / tripo-p2 Preview, CLI alias vs API model value), quad output, texture versions, and per-step credit breakdowns.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 487
    }
  ],
  "name": "tripo-3d",
  "skill_md_contents": "---\nname: tripo-3d\ndescription: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and write it into the project as GLB, FBX, OBJ, STL, USDZ or 3MF. Use when the user asks for a 3D asset, model, mesh, prop, character or texture for a game, renderer, viewer, AR scene or 3D print — including requests like \"make me a low-poly X\", \"turn this image into 3D\", \"rig this character\", \"convert this model to FBX\", \"split this model into parts\", \"unwrap its UVs\", or \"generate placeholder assets\". Also use to re-run, convert or inspect a previous Tripo generation, and to answer questions about which Tripo model, parameter or step to use and what it costs — model versions (H series tripo-v3.1, P series tripo-p1 / tripo-p2 Preview, CLI alias vs API model value), quad output, texture versions, and per-step credit breakdowns.\n---\n\n# Tripo 3D\n\n## Client attribution\n\nUse `tripo-cli` 0.7.0 or later. On every CLI command, set `TRIPO_CLIENT_APP=codex` and\n`TRIPO_DISTRIBUTION_CHANNEL=codex_plugin` for that command: as a variable prefix in\nPOSIX shells, or as `$env:TRIPO_CLIENT_APP` and `$env:TRIPO_DISTRIBUTION_CHANNEL` set\nright before it in PowerShell. The user does not have to set them, and they are never\nwritten to an account profile. The two values only name this plugin and carry no user\ndata: the CLI's usage analytics use them to attribute events to it, and\n`TRIPO_ANALYTICS_ENABLED=0` still turns those analytics off. They do not change the\nregion, the confirmation rules or the stdout output.\n\n\nGenerate engine-ready 3D assets with the `tripo` CLI. One command turns a prompt or\nan image into local files: a model, a `preview.png` render, and a `task.json` record.\n\n## Requires a shell\n\nEvery command below runs through a shell. If this environment cannot execute shell\ncommands, stop here: tell the user this skill works in Codex and that the same\nrequest will succeed there. Do not describe the commands as if they had run.\n\n## Before the first generation\n\nEvery command in this and related skills is the `tripo` command of `tripo-cli`,\nTripo's official CLI on npm. Check it first:\n\n```bash\ntripo --version     # 0.7.0 or later\ntripo doctor        # verifies key, network, region, balance\n```\n\nIf `tripo` is missing or older than 0.7.0, do not fetch or run the CLI any other\nway. Tell the user, and only after they agree install the release this skill was\nchecked against:\n\n```bash\nnpm install -g tripo-cli@0.7.2\n```\n\nIf `npm` itself is missing, Node.js is not installed — have the user install\nNode.js LTS first. In Windows PowerShell, `tripo` can fail with \"running scripts is\ndisabled on this system\": that is the machine's script execution policy. Tell the\nuser and leave the fix to them; do not change the policy or route around it.\n\nAuth resolves from `TRIPO_API_KEY` (a `tsk_...` key) or a previous `tripo login`.\nIf `doctor` reports no key, start device login when permitted by the user's\nrequest and the host's approval rules. Do not bypass host permission prompts,\nnever ask the user to paste a key into the chat, and never read, print or copy a\nkey yourself — the CLI stores it, and `tripo whoami` shows it masked:\n\n```bash\ntripo login --region ov --yes\n```\n\n`--yes` forces the non-interactive device flow. The command prints a\nverification URL and a one-time code right away, then blocks until the user\napproves in a browser — up to 15 minutes. Do not kill it early, and do not\nwait for it to exit before talking to the user: read the URL and code from\nits output while it is still running (run it in the background or stream its\nstderr). **Show the user the full verification URL and the code verbatim**,\nplus the console address https://developers.tripo3d.ai, and walk them through\nevery step — assume they have never seen this page:\n\n1. Open the verification URL in a browser.\n2. If the page asks to sign in, they are not logged in on the web either:\n   sign in to your Tripo account at https://developers.tripo3d.ai, then return\n   to the verification page.\n3. Type the one-time code into the **\"Verification code\"** field.\n4. An account that already has several API keys is asked to pick one — any\n   of them works, the CLI will use the chosen key. With no keys, one is\n   created automatically and there is nothing to choose.\n5. Click the **Authorize** button. The key arrives in the CLI and is stored —\n   nothing to copy by hand.\n\nWhen the command exits 0, re-run `doctor` and continue. Exit code 3 means the\ncode expired or was denied — run the same login command again for a fresh\ncode.\n\nExit code 3 means auth failed; run `tripo doctor`, which diagnoses key-vs-region\nmismatches (`ov` = international, `cn` = China mainland) and prints the exact fix.\n\n## The command\n\n```bash\ntripo make \"a stylized treasure chest\" --for game-mobile --json --yes\ntripo make concept.png --for game-pc --json --yes\ntripo make front.png back.png --json --yes           # 2-4 images -> multiview\ntripo make hero.glb --then texture,rig --json --yes  # import an existing mesh\ntripo make @last --then convert:fbx --json --yes     # continue from the last task\n```\n\nInput type is auto-detected: quoted text, an image path or URL, 2-4 images, a model\nfile, or a task reference (`@last`, `@name`, a task id).\n\nA local image file is uploaded by the CLI itself — always reliable. An image\nURL is passed straight to the API and **fetched by Tripo's servers**, so when\nthe user gives a URL, tell them explicitly: it must be publicly reachable and\nserved through a CDN or globally accelerated host, or the server-side fetch\ncan fail or time out (auth-protected, region-locked and slow-origin links all\nbreak). When in doubt, download the image locally first and pass the file\npath instead.\n\n- `--for <scenario>` picks model, parameters, chain and export format:\n  `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`.\n  The base generation already outputs GLB; some preset chains append a **paid**\n  convert step (`game-mobile`/`game-pc` → FBX, `print` → STL, `ar-web` → USDZ).\n  When the user only wants GLB, that convert buys a format nobody asked for —\n  use a chain-free preset instead (`toy` for low-poly, with `-p face_limit=...`)\n  or tell the user the extra format costs credits before running.\n- `--then <steps>` overrides the chain. Steps: `texture` `convert` `import`\n  `rig-check` `rig` `retarget` `segment` `complete` `decimate` `uv` `smartsegment`.\n  There is no `refine` or `stylize` step — the API endpoints behind them have been\n  retired.\n  Arguments use `step:key=value`; a bare value maps to the step's primary argument\n  (`convert:fbx`, `decimate:5000`).\n- `-o, --out <dir>` sets the **parent** directory, not the artifact directory. `make`\n  always creates `<dir>/tripo-out/<name>-<id8>/` underneath it, so `-o ./assets` writes\n  `./assets/tripo-out/<name>-<id8>/model.glb`. Pass `-o` to keep artifacts inside the\n  project instead of the shell's working directory, but when the user asked for a file\n  at a specific path, **move it there after the run and report the final path** — `-o`\n  alone cannot put it there. (`tripo task get <id> --download -o <dir>` is the\n  exception: its `-o` is the final directory.)\n- `-p key=value` passes an API parameter, repeatable. Useful ones: `face_limit=15000`,\n  `texture=false pbr=false` (bare geometry, skips texture credits), `auto_size=true`,\n  `texture_quality=detailed`, `negative_prompt=...`. The full list, with the\n  constraints the server enforces, is in \"Capability reference\" below.\n- `--model <m>` forces the generation model, `--seed <n>` fixes `model_seed`,\n  `-n <2-4>` generates that many candidates with different seeds (`-n` together with\n  `--then` needs an interactive terminal to pick the winner — chain afterwards with\n  `tripo make @<task> --then ...` instead).\n- `--name <name>` records the task under that name, so later commands can say\n  `@name` instead of a task id. `--timeout <seconds>` (default 1800) is the watch\n  timeout. `--no-wait` submits and exits with `{\"task_id\"}` — only for a run the user\n  explicitly wants to leave in the background; resume it with `tripo task watch <id>\n  --download`. `--dry-run` plans and validates without submitting (see next section).\n\n## Plan first, run after the user confirms\n\nCredits are frozen the moment a task is submitted, so before running any command\nthat generates or processes (`make`, `generate`, `redo`, `batch run`, `model|anim|mesh\n<step>` other than `rig-check`), show the user a plan and wait for a yes:\n\n- **input** — the prompt, image(s), file or task reference (`@last` → which task);\n- **model** — the CLI alias *and* the wire value it sends (`tripo-p1` → `P1-20260311`);\n- **steps** — one numbered line per API call, in run order: endpoint, what it does,\n  arguments. `--for` presets expand to a chain (`game-mobile` = generation → convert\n  FBX 2K; `anim` = generation → rig-check → rig → retarget), so list every step the\n  preset adds, not just the flag;\n- **deliverables** — the files that will land on disk and where (`-o`, then any move);\n- **estimated cost** — per step from the price table under \"Spending the user's\n  credits\", plus the total, and that failed steps are refunded.\n\nGet the facts for the plan from the CLI itself: run the exact `tripo make` command\nwith `--dry-run --json` appended. It plans and validates with **zero network calls,\nno credits and no API key**, and prints the plan on stdout:\n\n```bash\ntripo make concept.png --for game-mobile --then rig,convert:fbx --dry-run --json\n# {\"dry_run\":true,\"valid\":true,\"model\":\"P1-20260311\",\"model_reason\":\"scenario game-mobile\",\n#  \"steps\":[{\"name\":\"image-to-model\",\"endpoint\":\"/v3/generation/image-to-model\",\"task_type\":\"image_to_model\",\n#            \"payload\":{\"input\":\"<upload:concept.png>\",\"model\":\"P1-20260311\",\"texture\":true,\"pbr\":true,\"face_limit\":15000}},\n#           {\"name\":\"rig\",\"endpoint\":\"/v3/animations/rig\",\"payload\":{\"input\":\"<upstream>\",\"model\":\"v2.5-20260210\"}},\n#           {\"name\":\"convert\",\"endpoint\":\"/v3/models/convert\",\"payload\":{\"input\":\"<upstream>\",\"format\":\"FBX\"}}],\n#  \"pending_uploads\":[\"concept.png\"],\"deliverables\":[\"FBX\",\"GLB\"],\n#  \"warnings\":[\"--then overrides the default game-mobile processing chain\"],\"errors\":[],\"cost_notes\":[]}\n```\n\n`steps[].payload` is the exact body each call will POST (scenario defaults merged,\naliases turned into wire values, illegal parameters already stripped). `errors` are\nblocking — the dry run exits 2 on them, exactly like the real run would before\nspending; fix them and dry-run again. `warnings` are auto-adjustments (`P1 does not\nsupport quad (removed)`) — show them to the user, they change the outcome. Only when\n`valid` is true turn the steps into the plan below. On a CLI too old for `--dry-run`\n(it arrived in 0.5.0; 0.4.0 and older reject the flag with a usage error, exit 2)\nbuild the same plan by hand from the tables in this skill.\n\nExample of the shape (a `--for game-mobile` text prompt):\n\n```\n1. text-to-model  POST /v3/generation/text-to-model — generate the mesh\n   model=P1-20260311 face_limit=15000 texture=true pbr=true          ~40 credits\n2. convert        POST /v3/models/convert — export FBX, texture_size=2048   ~10 credits\n→ ./Assets/Art/Props/tripo-out/<name>-<id8>/model.fbx (+ model.glb, preview.png)   ≈ 50 credits\n```\n\nWait for explicit confirmation — silence is not a yes. Then run exactly the command\nyou showed, with `--yes` and without `--dry-run`; if the user changes anything, redo\nthe plan. A batch of several assets needs one confirmation for the whole list, not\none per asset. Free commands (`doctor`, `balance`, `usage`, `whoami`, `task get|list|\nwatch`, `history`, `rig-check`, `docs`, anything with `--dry-run`) need no\nconfirmation. `files upload` is free as well, but it sends a local file to Tripo:\nupload only a file the user chose for this task.\n\nCLI 0.5.0 and later print the same plan card on stderr right before submitting (a TTY\nuser is asked \"Run this plan?\"; with `--yes` or when headless it is printed and the\nrun continues; `--quiet` hides it). Use it to check that what ran matches what you\nshowed, and say so if it differs. Older builds print no card — the plan you show the\nuser does not depend on it.\n\n## Rules that matter\n\n1. **`tripo make` is blocking.** It submits, polls, downloads, then exits. Wait for\n   the process to finish. Do not re-implement polling, do not set a timeout shorter\n   than the CLI's own (default 1800s), and do not treat a `task_id` appearing in the\n   logs as completion.\n2. **stdout is the contract.** With `--json`, stdout carries exactly one final JSON\n   line; progress goes to stderr. Parse the last stdout line, not the logs.\n3. **Branch on exit codes**, don't parse error text:\n   `0` ok · `1` fatal, and what `doctor` returns when a critical check fails ·\n   `2` bad parameters · `3` auth · `4` insufficient credits — explain the\n   shortfall and stop; if useful, link only to the informational plans page at\n   https://developers.tripo3d.ai/en/pricing, never a checkout or top-up page · `5` content\n   policy · `6` task failed (credits auto-refunded, `tripo redo` often succeeds) —\n   unless the error says `timeout`: the task is still running server-side and is\n   billed if it succeeds, so resume it with `tripo task watch <id> --download` and\n   never redo or resubmit · `7` network — since 0.5.2 a failed submit is never\n   resent, and the task may already exist with credits frozen: check `tripo balance`\n   (`frozen`) before re-running, or the user can pay twice · `8` not found — a task\n   id only resolves under the key that created it, so when an older task 404s, fall\n   back to passing the local model file · `9` rate limit (retry with backoff).\n   On failure the stdout line is `{\"error\",\"exit_code\",…,\"suggestion\"}` —\n   `suggestion` names the next step.\n4. **Judge the result before moving on.** The result JSON gives `model_file` and\n   `preview`. Read `preview.png` to check the asset actually matches the request; if\n   it does not, `tripo redo` re-rolls with a new seed.\n5. **Never invent parameters.** Everything the API accepts is listed in \"Capability\n   reference\" below; `tripo docs --topic commands/generate` and `tripo docs --topic\n   commands/process` print the same tables with more detail, and\n   `tripo docs --topic common-errors` the error table. Do not send the user to the\n   website for a parameter name.\n6. **Let the CLI choose the model version.** It selects `tripo-v3.1` (high fidelity)\n   or `tripo-p1` (low-poly) automatically — see \"Models\" below for the rule. Only\n   pass `--model` when the user explicitly asks for one or the rule picks wrong.\n\n## Capability reference\n\nMirrors the official API docs so the agent never has to leave the shell. Everything\nhere is passed with `-p key=value` (generation) or `step:key=value` (`--then`).\n\n### Models & Versions\n\nKeywords: model versions · H series (`tripo-v3.x`) · P series (`tripo-p1`, `tripo-p2`\nPreview) · CLI alias → API `model` value · GA / Preview / Legacy · quad.\n\n| `--model` (CLI alias) | wire value sent as `model` | status | use for | limits |\n| --- | --- | --- | --- | --- |\n| `tripo-v3.1` (default) | `v3.1-20260211` | GA | H series, high fidelity: PC/console, film, print | full parameter set |\n| `tripo-p1` | `P1-20260311` | GA | P series, clean low-poly: mobile, UGC, ~2 s mesh | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality` (the CLI strips them with a warning); adds `export_uv` |\n| `tripo-p2` | `P2-20260801` | **Preview** | P1 upgrade: low-poly **with quads** or a bigger budget | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still not `smart_low_poly`, `generate_parts`, `geometry_quality` (stripped with a warning). Never auto-selected — needs an explicit `--model` |\n| `tripo-v3.0`, `tripo-v2.5` | `v3.0-20250812`, `v2.5-20250123` | Legacy | only when the user asks | |\n\n**Alias vs wire value.** `tripo-*`, `p1`, `p2`, `v3.1`… are CLI-side aliases: the CLI\nalways puts the dated wire value in the request's `model` field (`--model tripo-p2` →\n`\"model\": \"P2-20260801\"`), and `task.json` records the value actually used. The v3\nserver whitelist accepts wire values only — an alias sent straight to the API returns\n`1004 invalid model` with the allowed list. When the user quotes a model from the\nwebsite, map it through this table; the Models & Versions page lists the marketing\nnames, the P Series endpoint pages list the wire values. `tripo-turbo` and\n`tripo-v2.0` appear in older docs but the server rejects them.\n\nAuto-selection: low-poly words in the prompt (\"low poly\", \"voxel\") or **any\n`face_limit` ≤ 20000** pick P1; everything else is v3.1. So `-p face_limit=15000` on\nits own switches to P1 — add `--model tripo-v3.1` when the user wants v3.1 quality\nunder a face cap.\n\n**P series through the same endpoints.** P1/P2 are not separate endpoints; only the\n`model` value changes. `tripo make` picks P1 by the rule above; for an exact call use\n`tripo generate <endpoint> --model tripo-p1|tripo-p2` (see \"2D steps before 3D\"). The\nofficial docs document them as a separate \"P Series\" tab on each generation page:\n\n| endpoint | H series page | P series page |\n| --- | --- | --- |\n| `POST /v3/generation/text-to-model` | `…/docs/generation-text-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-text-to-model/p> |\n| `POST /v3/generation/image-to-model` | `…/docs/generation-image-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-image-to-model/p> |\n| `POST /v3/generation/multiview-to-model` | `…/docs/generation-multiview-to-model/standard` | <https://developers.tripo3d.ai/en/docs/generation-multiview-to-model/p> |\n\nReference pages (status and links only — parameter names come from this skill):\nModels & Versions <https://developers.tripo3d.ai/en/docs/models-and-versions> · P\nSeries model detail <https://developers.tripo3d.ai/en/models/p1>.\n\n### Generation parameters\n\n| param | default | notes |\n| --- | --- | --- |\n| `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 |\n| `texture`, `pbr` | `true`, `true` | `pbr=true` forces `texture=true`. `texture=false pbr=false` = bare geometry, no texture credits |\n| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). The API also has `fast` (v3.5 textures only; same price and texture size as `standard`, less detail), but the CLI's local validation still rejects it with exit 2 — do not pass it until the CLI accepts it |\n| `texture_version` | derived from `model` | pins the texture model independently of the geometry model: `v3.5-20260815` (newest), `v3.0-20250812` (default for v3.x and P-series geometry), `v2.5-20250123` (default for v2.5 geometry). All generation models incl. P1/P2; passes through the CLI unchanged — the only way to get v3.5 textures through the CLI, whose `texture` step rejects v3.5 |\n| `delight` | `true` | v3.5 textures only (`texture_version=v3.5-20260815`): remove baked-in lighting from the reference image before texturing; `false` keeps the original shading. Older texture versions ignore it |\n| `geometry_quality` | `standard` | `detailed` = Ultra geometry (+20). v3.x only |\n| `quad` | `false` | quad mesh (+5); **forces FBX output** — quads cannot be stored in GLB. v3.x and P2 |\n| `smart_low_poly` | `false` | hand-modelled-style low-poly topology (+10); with `face_limit`, the window is 500–20000 tri / 500–10000 quad. v3.x only |\n| `generate_parts` | `false` | editable segmented parts (+20). **Always pass `texture=false pbr=false` with it** — the server defaults `texture` to true and rejects the request (`1004`) if either is on; the CLI only corrects an explicit `true`. Re-texture afterwards with `--then texture`. `quad` is ignored; `smart_low_poly` wins and suppresses parts. v3.x only |\n| `auto_size` | `false` | scale the model to real-world metres |\n| `compress` | – | `geometry` = meshopt-compressed output. v3.x only |\n| `model_seed`, `texture_seed`, `image_seed` | random | reproducibility; `task.json` records the seeds used. `--seed` sets `model_seed` |\n| `negative_prompt` | – | text input only, ≤255 chars (prompt ≤1024) |\n| `enable_image_autofix` | `false` | image input: repair a low-quality photo first |\n| `texture_alignment` | `original_image` | image/multiview: `original_image` matches the picture, `geometry` matches the mesh |\n| `orientation` | `default` | image/multiview: `align_image` faces the model like the input viewpoint |\n| `export_uv` | `true` | P series only: `false` skips UV unwrap (faster, smaller file) |\n| `export_orientation` | `+x` | forward axis `+x` `-x` `+y` `-y`. **Generation only**: downstream steps (texture, rig, convert…) read the default orientation and return a wrongly oriented `success` with no error. When a chain follows, leave it unset and pass `export_orientation` to the final `convert` step instead |\n\nMultiview (2–4 images): a front view is mandatory and at least two views are needed.\nFilenames containing `front`, `back`, `left` or `right` assign the views; otherwise\nthe order is front, left, back, right.\n\n### Processing steps (`--then`)\n\nEvery step accepts `@last`, a task id or a model file as input, except `retarget`\n(needs a `rig` task), `complete` (needs a `segment` task) and `smartsegment` (file or\nURL only, cannot follow a task). A bare value after `:` sets the primary argument.\n\n| step | primary arg | arguments and constraints |\n| --- | --- | --- |\n| `texture` | `texture_quality` | `standard`/`detailed`/`extreme`, `pbr`, `texture_seed`, `texture_alignment`, `part_names` (only these parts of a segmented model), `bake` (true), `compress`; `model` `v3.0-20250812` (default) / `v2.5-20250123`. The API also takes `v3.5-20260815` (unlocks `delight`), but the CLI's local validation rejects it on this step (exit 2, still in 0.6.1) — use `texture_version` at generation for v3.5. Guidance `texture_prompt` is exactly one of `{\"text\":\"…\"}` (optionally with `style_image`), `{\"image\":\"<url or file_token>\"}` or `{\"images\":[front, left, back, right]}`; the docs make it optional only for Tripo-generated models, so pass one for an imported mesh, and re-supply the original reference image when re-texturing a generated task. It is an object, so only the `-p` form carries it: `tripo model texture <input> -p 'texture_prompt={\"text\":\"worn leather\"}'`. Re-textures any model, including imported files |\n| `convert` | `format` | `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit`, `flatten_bottom` + `flatten_bottom_threshold` (0.01). Texture: `texture_size` (4096), `texture_format` `JPEG`/`PNG`/`WEBP`/`BMP`/`TIFF`/`TARGA`/`HDR`/`DPX`/`OPEN_EXR`, `bake` (true), `pack_uv`, `export_vertex_colors` (OBJ/GLTF only). Export: `pivot_to_center_bottom`, `scale_factor`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo`. `quad` with `GLTF` is rejected. A non-default `quad`, `face_limit`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor` bills the complex tier (10 credits instead of 5); the other options do not |\n| `import` | – | GLB/GLTF/FBX/OBJ/STL ≤150 MB; `make <file>` runs it implicitly. A `.gltf` references external files, so it only works as a URL — pass a `.glb` for local files |\n| `rig-check` | – | free. GLB input. Returns `riggable` and `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — the chain continues from the same model |\n| `rig` | `rig_type` | one of the seven types above (default `biped`; take it from rig-check); `spec` `tripo`/`mixamo` (Mixamo = Unity Humanoid-compatible skeleton); `out_format` `glb`/`fbx`; `model` — CLI default `v2.5-20260210` (presets for every body type), legacy `v1.0-20240301` (biped only, 90+ presets); the marketing names `rig-v2.0` / `rig-v1.0` are accepted and normalised to those wire values |\n| `retarget` | `animation` | needs a `rig` task. One clip per `--then retarget:preset:walk`; for several clips use `tripo anim retarget --animation preset:idle preset:walk` (≤5 per task, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion), `bake_animation` (glb only), `export_with_geometry` |\n| `segment` | `model` | `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity`, `ref_image` (overrides the other two) |\n| `complete` | – | needs a `segment` task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` |\n| `decimate` | `face_limit` | `model` `v2.0` (default) / `v3.0` (newest retopology) / `v1.0` (basic). v2.0 and v3.0: `face_limit` optional (adaptive when omitted), 500–20000 tri / 500–10000 with `quad=true`; `bake=true` bakes textures onto the low-poly; `part_names`. `smart_uv=true` unwraps UVs in the same task at no extra cost (no atlas image) and works on **v3.0 only**: with no `model` the CLI selects v3.0 and warns, an explicit `v2.0`/`v1.0`/`default` is rejected before submitting (exit 2; the server would answer `1004`). `model=v1.0` accepts up to 2 000 000 faces but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling |\n| `uv` | – | re-unwraps the UVs and remaps the existing textures, rig and animation onto the new layout. `bake` (true; `false` = geometry + UVs only), `export_orientation` `+x`/`-x`/`+y`/`-y`, `compress=geometry`; `model` is `default` only. **Input ≤ 80 000 equivalent triangles** (a quad counts as two) — a bigger model is accepted, then fails and is refunded, so decimate first: `--then decimate:20000,uv`. Adds `uv_render.webp`, the flat UV atlas, which is not a preview (see \"Result shape\") |\n| `smartsegment` | `granularity` | file/URL only, so in practice `tripo mesh smartsegment <file> --seg-type image\\|model`. `seg_type=image` (photo → model → parts, 85 credits) or `seg_type=model` (GLB only, 55, default); `granularity` `coarse`/`medium`/`fine`; `hint` |\n\nThe `uv` step and decimate `v3.0` / `smart_uv` need CLI 0.6.0 or later, which the\n0.7.0 minimum under \"Before the first generation\" already covers.\n\nRetarget presets for the v2.5 rig (all body types): `preset:idle` `preset:walk`\n`preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot`\n`preset:hurt` `preset:fall` `preset:turn`, plus body-specific `preset:quadruped:walk`\n`preset:hexapod:walk` `preset:octopod:walk` `preset:serpentine:march`\n`preset:aquatic:march`. The v1.0 rig uses `preset:biped:<name>` (`idle`, `walk`,\n`run`, `dance_01`…, `greet_01`…, `box_01`…) and is biped only.\n\n### 2D steps before 3D (`tripo generate`)\n\n```bash\ntripo generate text-to-image \"full-body front view of a ninja\" -p template=t_pose --json --yes\ntripo generate image-to-image sketch.png --prompt \"clean concept art, neutral background\" --json --yes\ntripo generate image-to-model @last --json --yes           # an image task id is a valid input\ntripo generate image-to-multiview photo.png --json --yes   # 1 image -> front/left/back/right sheet\ntripo generate edit-multiview @last -p 'prompts=[{\"view\":\"front\",\"prompt\":\"add a sword\"}]' --json --yes  # 1-4 {view,prompt} edits on that sheet\ntripo generate image-to-splat photo.png --json --yes       # gaussian splat, not a mesh\n# P series, same 3D endpoints, explicit model (the CLI sends the wire value):\ntripo generate text-to-model \"a low poly knight\" --model tripo-p1 -p face_limit=8000 --json --yes   # model=P1-20260311\ntripo generate image-to-model photo.png --model tripo-p2 -p quad=true -p face_limit=12000 --json --yes  # model=P2-20260801 (Preview), FBX out\n```\n\n- Templates (`-p template=...`) are whitelisted per endpoint. text-to-image:\n  `t_pose` (the pre-step for rigging), `character_completion`, `asset_extraction`,\n  `variants`, `figure`. image-to-image: `t_pose`, `character_completion`,\n  `3d_enhance` (clean a photo before image-to-model), `variants`, `figure`. The docs\n  also list `head_extraction` and `print_clay`, but they are not on the server-side\n  whitelist the CLI mirrors — expect a parameter error. Shortcuts: `-p t_pose=true`, `-p sketch_to_render=true`.\n- Image models (`--model`, sent as-is — no alias mapping): `seedream_v4`\n  (text-to-image default; not accepted by image-to-image), `seedream_v5`,\n  `gemini-2.5-flash`, `gemini-3-pro`, `gemini-3.1-flash`, `chat_image_2`,\n  `chat_image_2.5_flare` (faster), `chat_image_2.5_sunburst` (keeps untouched regions\n  of an edited image closer to the original) — the two 2.5 models cost the same.\n  `chat_image_1` retires 2026-10-23 and `chat_image_1.5` on 2026-12-01: pick\n  `chat_image_2` or a 2.5 model instead.\n  GPT-image options: `-p quality=low|medium|high` (`chat_image_2`; the 2.5 models add\n  `xhigh`, `max`; omitted = `low`; `high` and above cost extra and take longer; any\n  other model rejects the field), `-p background=auto|opaque|transparent` (2.5 only;\n  `transparent` needs `-p output_format=png`; other models ignore the field).\n  `image-to-image` takes several references via `-p 'inputs=[\"<url or file_token>\", ...]'`\n  (seedream ≤4, gemini ≤10, GPT image ≤16; get tokens with `tripo files upload`),\n  referenced in the prompt as `image[1]`, `image[2]`…\n- Output options: `-p size=...` — default `2048x2048`; the accepted values depend on\n  the model: seedream a tier (`2K`/`3K` on v5, `2K`/`4K` on v4) or `WxH`;\n  `gemini-3-pro` `1K`/`2K`/`4K` or `WxH`; `gemini-3.1-flash` `0.5K`/`1K`/`2K`/`4K`;\n  `gemini-2.5-flash` fixed sizes only (`1024x1024`, `832x1248`, `1248x832`, …); GPT\n  image 2/2.5 presets up to `3840x2160` / `2160x3840`, or a custom `WxH` with each\n  edge ≤3840 and a multiple of 16, the long edge ≤3× the short, 655 360–8 294 400\n  pixels in total. `-p aspect_ratio=16:9` works on the gemini models only (default\n  `1:1`); `-p output_format=png|jpeg` (png default, the only one with transparency);\n  `-p watermark=true` on seedream only. The size tier (1K/2K/4K) sets the price.\n- `image-to-splat` returns a `.splat` file (30 credits, ~4 min): no texture, rig or\n  convert downstream — use image-to-model when a mesh is needed.\n\n## Spending the user's credits\n\nEvery generation costs credits from the user's account, and `credits_consumed` is\nreported on each result.\n\n- Every paid run goes through \"Plan first, run after the user confirms\" above; a\n  batch of several assets gets one confirmation for the whole list.\n- Run `tripo balance` first when the user asks for several assets.\n- **After the run, report the cost twice: the total and the itemised breakdown** —\n  one line per task in run order: step type, task id, credits actually billed, then\n  the total, and the remaining balance when a batch was involved. CLI 0.5.0 and later\n  put this in the result JSON as `credits_breakdown` (chained runs; `credits_consumed`\n  is then the total) and print `credits consumed (total)` plus one line per task in\n  human mode. When the field is missing — a single task, or an older CLI whose\n  `chain` entries carry only `task_id` and `type` — run `tripo task get <task_id>\n  --json` for each chain entry and the top-level task: every task record has its own\n  `credits_consumed`. Quote billed numbers, not the estimate from the plan.\n- Concurrency is pooled per account and per category (exit code 9 when a pool is\n  full): 10 parallel v3.x generations, 5 P-series, 10 animation, 5 texture/convert,\n  10 mesh ops — and **only 1 image generation** (text-to-image, image-to-image,\n  multiview). Never fan out image jobs; run them one after another.\n- For 3D printing and other untextured output, add `-p texture=false -p pbr=false`\n  — it skips texture credits entirely.\n- Do not silently re-roll a disappointing result. Show the user the preview and ask.\n\nApproximate list prices, so the cost can be quoted before a run (the authoritative\nnumber is `credits_consumed` on the result; `balance` and `credits_consumed` are\ndecimals, not integers):\n\n| operation | credits |\n| --- | --- |\n| text-to-model, v3.1 | 10 bare / 20 textured |\n| image- or multiview-to-model, v3.1 | 20 bare / 30 textured |\n| text-to-model, P1 | 30 bare / 40 textured (P2: 100 / 110) |\n| image- or multiview-to-model, P1 | 40 bare / 50 textured (P2: 100 / 110) |\n| add-ons per generation | `texture_quality=detailed` +10, `extreme` +20, `geometry_quality=detailed` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 |\n| texture step | 10 standard / 20 detailed / 30 extreme |\n| convert | 5, or 10 with a complex-tier option (see the convert row) |\n| decimate | 30 (v2.0) / 35, or 40 with quads (v3.0; `smart_uv` is free) / 10 (v1.0) |\n| uv | 20 |\n| segment / complete | 40 / 50 (`quick_cap` 30) |\n| smartsegment | 85 image / 55 model |\n| rig-check / rig / retarget | free / 25 / 10 per clip |\n| text-to-image, image-to-image | 5–20 by model and size tier; GPT image `quality=high` / `xhigh` / `max` 20–50 |\n| image-to-multiview / edit-multiview / image-to-splat | 10 / 5 per edited view / 30 |\n\nFailed and cancelled tasks are never charged: credits are frozen at submission and\nreleased on failure.\n\n## Result shape\n\n```json\n{\n  \"task_id\": \"...\",\n  \"type\": \"convert_model\",\n  \"status\": \"success\",\n  \"credits_consumed\": 145,\n  \"credits_breakdown\": [\n    { \"task_id\": \"<generation>\", \"type\": \"text_to_model\", \"credits_consumed\": 110 },\n    { \"task_id\": \"<texture>\", \"type\": \"texture_model\", \"credits_consumed\": 30 },\n    { \"task_id\": \"<convert>\", \"type\": \"convert_model\", \"credits_consumed\": 5 }\n  ],\n  \"output_dir\": \"tripo-out/knight-1a2b3c4d\",\n  \"files\": [\"model.fbx\", \"preview.png\", \"task.json\"],\n  \"model_file\": \".../model.fbx\",\n  \"preview\": \".../preview.png\",\n  \"source_task_id\": \"<generation>\",\n  \"chain\": [\n    { \"task_id\": \"<texture>\", \"type\": \"texture_model\", \"credits_consumed\": 30 },\n    { \"task_id\": \"<convert>\", \"type\": \"convert_model\", \"credits_consumed\": 5 }\n  ]\n}\n```\n\nWith `--then`, `credits_consumed` is the **total** for the run and `credits_breakdown`\nlists every task, generation first. A single task has no `credits_breakdown`. CLI\n0.4.0 and earlier omit `credits_breakdown`, `source_task_id` and the per-entry\n`credits_consumed` in `chain` — see \"Spending the user's credits\" for the fallback.\n\n`model_file` and `preview` describe the **final** chain step. After a convert\nstep the native GLB and `preview.png` live on the earlier generation task —\nfetch them free with `tripo task get <chain task_id> --download` instead of\npaying for another conversion. A run that ends in `uv` returns no `preview` at all:\nits only image is `uv_render.webp`, the flat UV layout, which the CLI deliberately\ndoes not copy to `preview.png` — judge the asset from the earlier task's preview the\nsame way.\n\n## Presenting the finished asset\n\nEvery file is already on the user's disk when `tripo make` exits — never offer\na \"download\". Do not render the model file as a clickable link either: the chat\nUI opens local-file links in a preview pane that cannot display binary meshes,\nso the link just looks broken when clicked. Instead:\n\n- show `preview.png` — images render fine;\n- give the model's location as a plain path in backticks;\n- offer the next real action: reveal it in the file manager (`open -R <path>`\n  on macOS, `explorer /select,<path>` on Windows) or wire it into the project.\n\n## Other commands\n\n| command                          | purpose                              |\n| -------------------------------- | ------------------------------------ |\n| `tripo task get <id> --download` | fetch or re-download an earlier task (`@last`/`@name` work; `--step` adds pipeline step details; `-o` here is the final directory) |\n| `tripo task watch <id> --download` | block on a task started with `--no-wait` or from elsewhere; with `--json` progress streams as NDJSON lines and the last line is the task detail; exit 6 = failed, or — when the error says `timeout` — still running: watch it again |\n| `tripo task list [ids...]`       | batch query; no ids = recent local history refreshed from the server. `missed` lists ids the server could not find (wrong key or region) |\n| `tripo history`                  | local task history with the `@name` references: `task_id`, `type`, `name`, `status`, `output_dir` |\n| `tripo balance` / `tripo usage`  | credits remaining (`{\"balance\",\"frozen\"}`; `frozen` = holds for running tasks) / recent per-task spend |\n| `tripo whoami`                   | masked key, active profile, region, balance — the quick \"which account is this\" check |\n| `tripo update [--check]`         | `--check` only reports whether a newer release exists. `tripo update` reinstalls the CLI at the latest release with `npm install -g` — run it only when the user asks to upgrade |\n| `tripo redo [@last] [--seed N]`  | same request, new seed; only for tasks this CLI created (the history holds the payload) |\n| `tripo files upload <path>`      | get a `file_token`: images PNG/JPEG/WebP/BMP/TIFF ≤20 MB, models GLB/FBX/OBJ/STL ≤150 MB; `.gltf` is not uploadable |\n| `tripo batch run manifest.yaml`  | bulk jobs, resumable — manifest below |\n| `tripo generate <endpoint> ...`  | one exact endpoint, no auto-chain: `text-to-model` `image-to-model` `multiview-to-model` `text-to-image` `image-to-image` `image-to-multiview` `edit-multiview` `image-to-splat` |\n| `tripo model\\|anim\\|mesh <step>` | one processing step with explicit flags (`tripo model convert @last --format FBX --fbx-preset mixamo`); input = argument > piped stdin JSON > `@last`; shared flags `--json --yes -o --no-wait --no-download --timeout --name -p` |\n| `tripo config context key=value` | per-directory defaults in `.tripo/context.json`, e.g. `default_scenario=game-mobile output_dir=./assets`; `tripo config list` shows the merged config |\n| `--profile <name>` / `tripo use <name>` | several accounts: one-shot override on any command (`TRIPO_PROFILE` env works too) / switch the active profile. An unknown profile exits 3 with the fix in the message — do not retry blindly |\n| `tripo docs --topic <topic>`     | full docs: `commands/make` `commands/generate` `commands/process` `commands/task` `commands/account` `commands/batch` `commands/view` `examples/<scenario>` `common-errors` |\n\n`tripo view` opens a local browser viewer for humans — read `preview.png` instead.\n`tripo ai` is the interactive wizard/LLM planner for humans in a terminal — use\n`tripo make --for <scenario>`, which is deterministic and needs no LLM. `tripo mcp`\nstarts the CLI's own MCP server; it is not part of this plugin, do not configure it.\n\nBatch manifest (`tripo batch run assets.yaml [--concurrency 2] [--retries 1] [--fresh]`):\n\n```yaml\nconcurrency: 2\ndefaults: { for: game-mobile, then: \"convert:fbx\", out: ./assets }\njobs:\n  - input: \"a bronze sword\"\n  - input: \"a wooden shield\"\n    name: shield                       # becomes @shield and the resume key\n  - input: cat.png\n    for: print\n    then: \"convert:stl,flatten_bottom=true\"\n  - inputs: [hero-front.png, hero-back.png]\n    name: hero\n    params: { texture_quality: detailed }\n```\n\nState is saved next to the manifest (`assets.yaml.state.json`) after every job, so\nre-running the same command skips the jobs that already succeeded; `--fresh` starts\nover. Failed jobs retry `--retries` times and the run exits 6 if any stays failed.\nFinal stdout JSON: `{\"total\",\"success\",\"failed\",\"state_file\",\"jobs\":{...}}` — each job\nentry carries `status`, `attempts` and the final `task_id`; the itemised credit report\nfor a batch comes from `tripo task get <task_id> --json` (and `tripo usage`). Keep `concurrency` within the\npools listed under \"Spending the user's credits\" (image jobs: 1).\n\nDownload URLs returned by the API expire in about five minutes — never cache one.\nRe-run `tripo task get <id> --download` instead. Task status can also be `banned`\n(content policy — change the input) or `expired` (output files gone — regenerate);\nthe CLI treats both as terminal failures.\n"
}