Tripo 3D
Generate engine-ready 3D assets with Tripo. Two execution paths exist; pick one
before doing anything else, and never pretend to run what this environment
cannot run.
Pick the execution path
- MCP path — the tool list contains Tripo tools (
tripo_text_to_3d,
tripo_task_wait, ...; ZCode prefixes them with the MCP server id, e.g.
mcp__…__tripo_text_to_3d — the rest of this skill uses the bare names).
This is the default path.
- Tripo tools missing — the plugin's MCP server is almost always waiting
for authorization or switched off, not absent. Stop and tell the user first:
open 设置 → MCP, find the Tripo server under 「Plugin MCP 服务器」,
click 打开授权 if the row says 「需要授权」 (or enable it), then start a
new session. See Authorization below. Do not switch to
tripo-cli
instead — not for a balance check, not because a local tripo login
or TRIPO_API_KEY happens to exist (that may be a different account, and
the user installed this plugin to use MCP). Offer the CLI only as an
explicit alternative in the same message, and take it only if the user
picks it.
- CLI path — the user explicitly asked for the CLI, or the Tripo MCP
tools are present but the job needs what only a shell gives: bulk
generation (
tripo batch) or artifacts written straight into the project
tree without a download step. Drive tripo-cli as described in the second
half of this skill.
- Neither — stop here and say so; do not describe generations as if
they had run.
Local files do not require the CLI — MCP's tripo_upload_ticket covers both
images and mesh files (see Inputs below).
MCP path
Authorization
Tool calls fail with an authorization error until the user connects a Tripo
account. ZCode runs the OAuth flow but never opens a browser on its own — the
user has to click once. Your job is to guide them through the pages; never ask
for an API key in the chat.
This plugin build talks to the China-mainland MCP
(https://developers.tripo3d.com/mcp). The authorization page does not
offer a region picker — it always opens the 国内站 console
(developers.tripo3d.com, +86 SMS sign-in, Alipay top-up). An overseas-site
account (developers.tripo3d.ai) will not work here: tell the user to install
the overseas Tripo 3D plugin build, or use the CLI path with
login --region ov.
- 设置 → MCP → group 「Plugin MCP 服务器」 → the Tripo row shows
「需要授权」 → click 打开授权. The system browser opens the Tripo
authorization page.
- The page shows a one-time verification code and opens the Tripo console:
sign in (or sign up — new accounts get free credits), type the code into
the "Verification code" field, click Authorize. Nothing is ever
copied or pasted into the chat.
- ZCode reconnects and loads the tools automatically. If the tools still do
not show up, start a new session.
Generations spend credits from the account the user connected. The connection
is bound to the API key the user picked on the Tripo console during
authorization (an account with no key gets cli-default created automatically;
with exactly one key it is used as is). To revoke access, delete that key on
the console's API Keys page — any other client sharing it (e.g. tripo-cli)
loses access too.
Workflow
- Plan — for any billed generation or chain, call
tripo_plan first,
show the draft to the user, and wait for explicit confirmation. Skip only
for pure reads (tripo_balance, tripo_usage, tripo_task_status /
tripo_task_list).
- Create —
tripo_text_to_3d for prompts (Chinese or English, concrete
nouns + style + materials), tripo_image_to_3d for images. Both return a
task_id immediately.
- Wait — call
tripo_task_wait with the task_id; each call returns
within about 55 s, so call it again while status is still queued/running
(a generation takes 1–4 minutes). Do not invent your own sleep loop and do
not treat the task_id as completion.
- Judge — on
success, look at preview_image_url and show it to the
user before building on the result. On failed/banned, report
failure_reason honestly; failed-task credits are refunded automatically.
Do not silently re-roll a disappointing result — show the preview and ask;
re-rolling means creating a new task with the same prompt.
- Post-process (each step is a new billed task: create →
tripo_task_wait;
input takes a model task_id, a file_token or a public model URL unless
noted):
tripo_texture — texture or re-texture a model.
tripo_rig_check → tripo_rig — check riggability before spending rig
credits, then add a skeleton with the rig_type the check returned.
Prompt characters as T-pose at generation time; spec: "mixamo" for
Unity Humanoid / Mixamo pipelines. Leave model unset: tripo_rig picks
the humanoid v1.0 rig for biped and the creature v2.5 rig for the other
body types, and its result says which preset family the rig takes.
tripo_animate — presets on a successful rig task (≤5 per call,
billed per animation). Preset names follow the rig model reported by
tripo_rig: humanoid (v1.0) rigs take preset:biped:walk,
preset:biped:idle, …; creature (v2.5) rigs take preset:walk,
preset:idle, …; animate_in_place: true when game code drives movement.
tripo_convert — export GLTF/USDZ/FBX/OBJ/STL/3MF, optional retopology
via face_limit/quad. Quads cannot export GLTF. Any non-default option
bills as "complex convert".
tripo_decimate — high-poly → low-poly (face_limit 500–20000, bakes the
original textures); tripo_segment → tripo_mesh_complete — split into
parts and close the cuts; tripo_mesh_edit — redo one region of an
existing mesh with P2 Preview (bbox required). Stylize (lego / voxel /
voronoi / minecraft) has been retired — there is no tripo_stylize tool
and no CLI --then stylize step.
- Deliver — result URLs (
model_url, preview_image_url) expire in
about 5 minutes; never cache or re-print an old one — call
tripo_task_status for fresh links. Download the file into the project
(curl -L -o <path> "<url>") and give the local path as plain text in
backticks — never as a clickable link, the chat preview cannot render
meshes. Only when no shell is available give the fresh link and say it is
short-lived, offering to refresh it on request.
Scenario → tool chain
Pick the chain from what the user is building; every arrow is a billed task
followed by tripo_task_wait. GLB is the native output — a tripo_convert
step is only worth its credits when the target really needs another format.
- Game prop, mobile / WebGL / many instances — generate with
face_limit ≤ 20000 (auto-selects the low-poly P1 model) →
tripo_convert format: "FBX" (texture_size: 2048) for Unity/Unreal;
Three.js/Godot take the GLB as is.
- Game hero asset, PC / console — default
v3.1, pbr: true,
texture_quality: "detailed" → FBX only if the engine needs it.
- Film / render / close-ups —
v3.1 with geometry_quality: "detailed"
and texture_quality: "detailed" (both cost extra credits).
- 3D print / figurine —
texture: false, pbr: false → tripo_convert
format: "STL" (flatten_bottom: true for a stable base); 3MF also works.
- AR / iOS Quick Look —
auto_size: true (real-world meters) →
tripo_convert format: "USDZ"; WebXR uses the GLB directly.
- Animated character — T-pose reference first (
tripo_generate_image
with template: "t_pose" turns a character image into one) →
tripo_image_to_3d/tripo_text_to_3d → tripo_rig_check → tripo_rig
(spec: "mixamo" for Unity Humanoid) → tripo_animate with the preset
family named in the tripo_rig result: humanoids
["preset:biped:walk", "preset:biped:idle"], creatures (quadruped and the
other body types) ["preset:walk", "preset:idle"].
- LOD chain — generate once → one
tripo_decimate per level
(face_limit is a target, not a hard ceiling — say so when the project has
a strict budget).
- Better views of one image —
tripo_image_to_multiview →
tripo_multiview_to_3d with multiview_task_id; when the user already has
2–4 orthographic views, tripo_multiview_to_3d takes them directly.
- User's existing mesh — a public URL goes straight into any processing
tool's
input; a local file goes through tripo_upload_ticket
(kind: "model", format: "glb") → tripo_import_model, which yields a
reusable task_id with a preview (.gltf is rejected — export .glb).
- Not a mesh —
tripo_image_to_splat outputs a Gaussian-splat .ply
scene for viewers, not an editable model; say so before running it.
Parameters that matter
- Generation model version is chosen automatically:
v3.1 high fidelity
by default, P1 when the prompt smells low-poly or face_limit ≤ 20000.
Only pass model to the generation tools when the user explicitly asks
(P2 / P2-20260801 Preview for quads or a bigger low-poly budget). The
rig model is likewise chosen from rig_type by tripo_rig (see above).
- 3D printing / untextured output:
texture: false, pbr: false skips texture
credits entirely; convert to STL (add flatten_bottom: true for stability).
quad: true (v3.1 or P2) needs a tripo_convert to FBX/OBJ/USDZ at the end;
P1 rejects quad.
Inputs
- Image inputs, three routes: a publicly reachable URL goes straight into
tripo_image_to_3d (Tripo's servers fetch it — auth-protected, region-locked
or slow-origin links break). A signed/short-lived or uncertain URL goes
through tripo_upload_image first: the server re-hosts it and returns a
file_token, failing fast instead of wasting a task. A local image file
(a file in the project, or one the user attached to the chat whose path is
known — ask for the path if only the picture is visible) goes through
tripo_upload_ticket: run the how_to curl it returns in the shell
(curl -sS -X POST --data-binary @<file> -H "Content-Type: application/octet-stream" "<upload_url>")
and read file_token from the JSON response — no CLI login involved.
- Model files (GLB/FBX/OBJ/STL, ≤150 MB) use the same ticket with
kind: "model" and format; the file_token then feeds
tripo_import_model or any processing tool directly.
- Task ids chain: a successful generation task is a valid
input for every
processing tool, so never re-upload what Tripo already has.
Other tools
tripo_plan — free draft of the intended tool chain before any billed call.
tripo_task_status — fresh links for any task; steps: true adds the
per-stage breakdown when a chain misbehaves.
tripo_task_list — status of up to 100 task ids in one call (batches).
tripo_usage — recent per-task credit spend (includes per-task breakdown).
tripo_mesh_edit — P2 Preview regional regenerate (bbox + optional
ref_image).
Spending the user's credits
tripo_balance first when the user asks for several assets; confirm before
generating more than one in a batch, and report credits_consumed after.
- Insufficient balance errors: give the
plans_url from tripo_balance
(informational pricing page for this deployment's region) instead of retrying.
CLI path
Everything below runs through the shell. One command turns a prompt or an
image into local files: a model, a preview.png render, and a task.json
record.
Before the first generation
npx tripo-cli@latest doctor # verifies key, network, region, balance
Auth resolves from TRIPO_API_KEY (a tsk_... key) or a previous tripo login.
If doctor reports no key, start the device login yourself — do not ask for
permission first, and never ask the user to paste a key into the chat.
Tripo has two regions with separate accounts and consoles:
Pick the region yourself only when the context already says which site the
user's account is on — they mentioned it, tripo whoami shows a profile, or
TRIPO_REGION is set. Otherwise ask one question before starting the login:
"你的 Tripo 账号在国内站还是海外站?" An account lives in exactly one region,
and starting the device flow on the wrong console sends the user to a site
where their account does not exist. No account yet? China-mainland users
should pick cn (Alipay top-up), everyone else ov — signing up during the
login flow is fine and new accounts get free credits.
npx tripo-cli@latest login --region cn --yes # or: --region ov
--yes forces the non-interactive device flow. The command prints a
verification URL and a one-time code right away, then blocks until the user
approves in a browser — up to 15 minutes. Do not kill it early, and do not
wait for it to exit before talking to the user: read the URL and code from
its output while it is still running (run it in the background or stream its
stderr). Show the user the full verification URL and the code verbatim,
plus the matching console address (cn: https://developers.tripo3d.com,
ov: https://developers.tripo3d.ai), and walk them through every step —
assume they have never seen this page:
- Open the verification URL in a browser.
- If the page asks to sign in, they are not logged in on the web either:
sign in — or sign up at the console address above; new accounts get
free credits — then return to the verification page.
- Type the one-time code into the "Verification code" field.
- An account that already has several API keys is asked to pick one — any
of them works, the CLI will use the chosen key. With no keys, one is
created automatically and there is nothing to choose.
- Click the Authorize button. The key arrives in the CLI and is stored —
nothing to copy by hand.
When the command exits 0, re-run doctor and continue. Exit code 3 means the
code expired or was denied — run the same login command again for a fresh
code. If an older CLI rejects headless login with a usage error, fall back to
asking the user to run npx tripo-cli@latest login in their own terminal.
Installing globally (npm install -g tripo-cli) makes repeated calls faster and
is what makes the bare tripo command exist — ask before doing it. Without a
global install, run every tripo ... command in this and related skills as
npx tripo-cli@latest ...; npx downloads the CLI on first use, so a fresh machine
needs no manual install. If npx itself is missing, Node.js is not installed —
have the user install Node.js LTS first. On China-mainland networks, when the
npx download stalls, switch to the npmmirror registry and retry:
npm config set registry https://registry.npmmirror.com.
Exit code 3 means auth failed; run tripo doctor, which diagnoses key-vs-region
mismatches (ov = international, cn = China mainland) and prints the exact fix.
The command
tripo make "a stylized treasure chest" --for game-mobile --json --yes
tripo make concept.png --for game-pc --json --yes
tripo make front.png back.png --json --yes # 2-4 images -> multiview
tripo make hero.glb --then texture,rig --json --yes # import an existing mesh
tripo make @last --then convert:fbx --json --yes # continue from the last task
Input type is auto-detected: quoted text, an image path or URL, 2-4 images, a model
file, or a task reference (@last, @name, a task id).
A local image file is uploaded by the CLI itself — always reliable. An image
URL is passed straight to the API and fetched by Tripo's servers, so when
the user gives a URL, tell them explicitly: it must be publicly reachable and
served through a CDN or globally accelerated host, or the server-side fetch
can fail or time out (auth-protected, region-locked and slow-origin links all
break). When in doubt, download the image locally first and pass the file
path instead.
--for <scenario> picks model, parameters, chain and export format:
game-mobile game-pc film print ar-web anim toy.
The base generation already outputs GLB; some preset chains append a paid
convert step (game-mobile/game-pc → FBX, print → STL, ar-web → USDZ).
When the user only wants GLB, that convert buys a format nobody asked for —
use a chain-free preset instead (toy for low-poly, with -p face_limit=...)
or tell the user the extra format costs credits before running.
--then <steps> overrides the chain. Steps: texture convert
import rig-check rig retarget segment complete decimate smartsegment.
Arguments use step:key=value; a bare value maps to the step's primary argument
(convert:fbx, decimate:5000).
-o, --out <dir> sets the parent directory, not the artifact directory. make
always creates <dir>/tripo-out/<name>-<id8>/ underneath it, so -o ./assets writes
./assets/tripo-out/<name>-<id8>/model.glb. Pass -o to keep artifacts inside the
project instead of the shell's working directory, but when the user asked for a file
at a specific path, move it there after the run and report the final path — -o
alone cannot put it there. (tripo task get <id> --download -o <dir> is the
exception: its -o is the final directory.)
-p key=value passes an API parameter, repeatable. Useful ones: face_limit=15000,
texture=false pbr=false (bare geometry, skips texture credits), auto_size=true,
texture_quality=detailed, negative_prompt=.... --model forces the generation
model (tripo-v3.1 / tripo-p1 / tripo-p2 → wire v3.1-20260211 /
P1-20260311 / P2-20260801). --dry-run plans and validates with zero network
calls (no credits, no key) and prints the chosen wire-value model,
steps[].payload, warnings and errors; only run for real when valid is true.
After a chained run, report credits_consumed (total) and credits_breakdown
(per task); if the field is missing, tripo task get <id> --json each chain entry.
Rules that matter
tripo make is blocking. It submits, polls, downloads, then exits. Wait for
the process to finish. Do not re-implement polling, do not set a timeout shorter
than the CLI's own (default 1800s), and do not treat a task_id appearing in the
logs as completion.
- stdout is the contract. With
--json, stdout carries exactly one final JSON
line; progress goes to stderr. Parse the last stdout line, not the logs.
- Branch on exit codes, don't parse error text:
0 ok · 1 fatal, and what doctor returns when a critical check fails ·
2 bad parameters · 3 auth · 4 insufficient credits · 5 content
policy · 6 task failed (credits auto-refunded, tripo redo often succeeds) ·
7 network · 8 not found — a task id only resolves under the key that created
it, so when an older task 404s, fall back to passing the local model file ·
9 rate limit (retry with backoff).
- Judge the result before moving on. The result JSON gives
model_file and
preview. Read preview.png to check the asset actually matches the request; if
it does not, tripo redo re-rolls with a new seed.
- Never invent parameters. Run
tripo docs --topic commands/make for the full
flag list, or tripo docs --topic common-errors for the error table.
- Let the CLI choose the model version. It selects
tripo-v3.1 (high fidelity)
or tripo-p1 (low-poly, face budget 50-20000) automatically. Only pass --model
when the user explicitly asks for one (tripo-p2 Preview for quads).
Download URLs returned by the API expire in about five minutes — never cache one.
Re-run tripo task get <id> --download instead.
Capability reference
Model versions, generation/processing parameters, 2D steps, list prices, CLI
result shape and other commands: read references/capability.md
(same parameter names on MCP and CLI). MCP also has tripo_plan (confirm before
spend) and tripo_mesh_edit (P2 regional redo).
1---2name: tripo-3d3description: Generate a 3D model from a text prompt, a reference image, or an existing mesh, and deliver it 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", or "generate placeholder assets". 中文触发词:生成3D模型、建模、3D素材、把图片变成3D、图生3D、文生3D、骨骼绑定、绑骨、角色动画、贴图、纹理、低模、低多边形、减面、3D打印、手办、格式转换(FBX/GLB/OBJ/STL/USDZ/3MF)。Also use to re-run, convert or inspect a previous Tripo generation.4metadata:5 source: https://skillmd.com/skills/zai-org/tripo-3d6---78# Tripo 3D910Generate engine-ready 3D assets with Tripo. Two execution paths exist; pick one11before doing anything else, and never pretend to run what this environment12cannot run.1314## Pick the execution path15161. **MCP path** — the tool list contains Tripo tools (`tripo_text_to_3d`,17 `tripo_task_wait`, ...; ZCode prefixes them with the MCP server id, e.g.18 `mcp__…__tripo_text_to_3d` — the rest of this skill uses the bare names).19 This is the default path.202. **Tripo tools missing** — the plugin's MCP server is almost always waiting21 for authorization or switched off, not absent. Stop and tell the user first:22 open **设置 → MCP**, find the Tripo server under 「Plugin MCP 服务器」,23 click **打开授权** if the row says 「需要授权」 (or enable it), then start a24 new session. See Authorization below. **Do not switch to `tripo-cli`25 instead** — not for a balance check, not because a local `tripo login`26 or `TRIPO_API_KEY` happens to exist (that may be a different account, and27 the user installed this plugin to use MCP). Offer the CLI only as an28 explicit alternative in the same message, and take it only if the user29 picks it.303. **CLI path** — the user explicitly asked for the CLI, or the Tripo MCP31 tools are present but the job needs what only a shell gives: bulk32 generation (`tripo batch`) or artifacts written straight into the project33 tree without a download step. Drive `tripo-cli` as described in the second34 half of this skill.354. **Neither** — stop here and say so; do not describe generations as if36 they had run.3738Local *files* do not require the CLI — MCP's `tripo_upload_ticket` covers both39images and mesh files (see Inputs below).4041---4243# MCP path4445## Authorization4647Tool calls fail with an authorization error until the user connects a Tripo48account. ZCode runs the OAuth flow but never opens a browser on its own — the49user has to click once. Your job is to guide them through the pages; never ask50for an API key in the chat.5152**This plugin build talks to the China-mainland MCP**53(`https://developers.tripo3d.com/mcp`). The authorization page does **not**54offer a region picker — it always opens the **国内站** console55(developers.tripo3d.com, +86 SMS sign-in, Alipay top-up). An overseas-site56account (developers.tripo3d.ai) will not work here: tell the user to install57the overseas Tripo 3D plugin build, or use the CLI path with58`login --region ov`.59601. **设置 → MCP** → group 「Plugin MCP 服务器」 → the Tripo row shows61 「需要授权」 → click **打开授权**. The system browser opens the Tripo62 authorization page.632. The page shows a one-time verification code and opens the Tripo console:64 sign in (or sign up — new accounts get free credits), type the code into65 the **"Verification code"** field, click **Authorize**. Nothing is ever66 copied or pasted into the chat.673. ZCode reconnects and loads the tools automatically. If the tools still do68 not show up, start a new session.6970Generations spend credits from the account the user connected. The connection71is bound to the API key the user picked on the Tripo console during72authorization (an account with no key gets `cli-default` created automatically;73with exactly one key it is used as is). To revoke access, delete that key on74the console's API Keys page — any other client sharing it (e.g. `tripo-cli`)75loses access too.7677## Workflow78791. **Plan** — for any billed generation or chain, call `tripo_plan` first,80 show the draft to the user, and wait for explicit confirmation. Skip only81 for pure reads (`tripo_balance`, `tripo_usage`, `tripo_task_status` /82 `tripo_task_list`).832. **Create** — `tripo_text_to_3d` for prompts (Chinese or English, concrete84 nouns + style + materials), `tripo_image_to_3d` for images. Both return a85 `task_id` immediately.863. **Wait** — call `tripo_task_wait` with the `task_id`; each call returns87 within about 55 s, so call it again while status is still `queued`/`running`88 (a generation takes 1–4 minutes). Do not invent your own sleep loop and do89 not treat the `task_id` as completion.904. **Judge** — on `success`, look at `preview_image_url` and show it to the91 user before building on the result. On `failed`/`banned`, report92 `failure_reason` honestly; failed-task credits are refunded automatically.93 Do not silently re-roll a disappointing result — show the preview and ask;94 re-rolling means creating a new task with the same prompt.955. **Post-process** (each step is a new billed task: create → `tripo_task_wait`;96 `input` takes a model task_id, a `file_token` or a public model URL unless97 noted):98 - `tripo_texture` — texture or re-texture a model.99 - `tripo_rig_check` → `tripo_rig` — check riggability before spending rig100 credits, then add a skeleton with the `rig_type` the check returned.101 Prompt characters as **T-pose** at generation time; `spec: "mixamo"` for102 Unity Humanoid / Mixamo pipelines. Leave `model` unset: `tripo_rig` picks103 the humanoid v1.0 rig for `biped` and the creature v2.5 rig for the other104 body types, and its result says which preset family the rig takes.105 - `tripo_animate` — presets on a **successful rig task** (≤5 per call,106 billed per animation). Preset names follow the rig model reported by107 `tripo_rig`: humanoid (v1.0) rigs take `preset:biped:walk`,108 `preset:biped:idle`, …; creature (v2.5) rigs take `preset:walk`,109 `preset:idle`, …; `animate_in_place: true` when game code drives movement.110 - `tripo_convert` — export GLTF/USDZ/FBX/OBJ/STL/3MF, optional retopology111 via `face_limit`/`quad`. Quads cannot export GLTF. Any non-default option112 bills as "complex convert".113 - `tripo_decimate` — high-poly → low-poly (`face_limit` 500–20000, bakes the114 original textures); `tripo_segment` → `tripo_mesh_complete` — split into115 parts and close the cuts; `tripo_mesh_edit` — redo one region of an116 existing mesh with P2 Preview (`bbox` required). Stylize (lego / voxel /117 voronoi / minecraft) has been retired — there is no `tripo_stylize` tool118 and no CLI `--then stylize` step.1196. **Deliver** — result URLs (`model_url`, `preview_image_url`) **expire in120 about 5 minutes**; never cache or re-print an old one — call121 `tripo_task_status` for fresh links. Download the file into the project122 (`curl -L -o <path> "<url>"`) and give the local path as plain text in123 backticks — never as a clickable link, the chat preview cannot render124 meshes. Only when no shell is available give the fresh link and say it is125 short-lived, offering to refresh it on request.126127## Scenario → tool chain128129Pick the chain from what the user is building; every arrow is a billed task130followed by `tripo_task_wait`. GLB is the native output — a `tripo_convert`131step is only worth its credits when the target really needs another format.132133- **Game prop, mobile / WebGL / many instances** — generate with134 `face_limit` ≤ 20000 (auto-selects the low-poly `P1` model) →135 `tripo_convert` `format: "FBX"` (`texture_size: 2048`) for Unity/Unreal;136 Three.js/Godot take the GLB as is.137- **Game hero asset, PC / console** — default `v3.1`, `pbr: true`,138 `texture_quality: "detailed"` → FBX only if the engine needs it.139- **Film / render / close-ups** — `v3.1` with `geometry_quality: "detailed"`140 and `texture_quality: "detailed"` (both cost extra credits).141- **3D print / figurine** — `texture: false, pbr: false` → `tripo_convert`142 `format: "STL"` (`flatten_bottom: true` for a stable base); `3MF` also works.143- **AR / iOS Quick Look** — `auto_size: true` (real-world meters) →144 `tripo_convert` `format: "USDZ"`; WebXR uses the GLB directly.145- **Animated character** — T-pose reference first (`tripo_generate_image`146 with `template: "t_pose"` turns a character image into one) →147 `tripo_image_to_3d`/`tripo_text_to_3d` → `tripo_rig_check` → `tripo_rig`148 (`spec: "mixamo"` for Unity Humanoid) → `tripo_animate` with the preset149 family named in the `tripo_rig` result: humanoids150 `["preset:biped:walk", "preset:biped:idle"]`, creatures (quadruped and the151 other body types) `["preset:walk", "preset:idle"]`.152- **LOD chain** — generate once → one `tripo_decimate` per level153 (`face_limit` is a target, not a hard ceiling — say so when the project has154 a strict budget).155- **Better views of one image** — `tripo_image_to_multiview` →156 `tripo_multiview_to_3d` with `multiview_task_id`; when the user already has157 2–4 orthographic views, `tripo_multiview_to_3d` takes them directly.158- **User's existing mesh** — a public URL goes straight into any processing159 tool's `input`; a local file goes through `tripo_upload_ticket`160 (`kind: "model"`, `format: "glb"`) → `tripo_import_model`, which yields a161 reusable task_id with a preview (`.gltf` is rejected — export `.glb`).162- **Not a mesh** — `tripo_image_to_splat` outputs a Gaussian-splat `.ply`163 scene for viewers, not an editable model; say so before running it.164165## Parameters that matter166167- **Generation model version is chosen automatically**: `v3.1` high fidelity168 by default, `P1` when the prompt smells low-poly or `face_limit ≤ 20000`.169 Only pass `model` to the generation tools when the user explicitly asks170 (`P2` / `P2-20260801` Preview for quads or a bigger low-poly budget). The171 rig model is likewise chosen from `rig_type` by `tripo_rig` (see above).172- 3D printing / untextured output: `texture: false, pbr: false` skips texture173 credits entirely; convert to `STL` (add `flatten_bottom: true` for stability).174- `quad: true` (v3.1 or P2) needs a `tripo_convert` to FBX/OBJ/USDZ at the end;175 P1 rejects `quad`.176177## Inputs178179- Image inputs, three routes: a **publicly reachable URL** goes straight into180 `tripo_image_to_3d` (Tripo's servers fetch it — auth-protected, region-locked181 or slow-origin links break). A signed/short-lived or uncertain URL goes182 through `tripo_upload_image` first: the server re-hosts it and returns a183 `file_token`, failing fast instead of wasting a task. A **local image file**184 (a file in the project, or one the user attached to the chat whose path is185 known — ask for the path if only the picture is visible) goes through186 `tripo_upload_ticket`: run the `how_to` curl it returns in the shell187 (`curl -sS -X POST --data-binary @<file> -H "Content-Type: application/octet-stream" "<upload_url>"`)188 and read `file_token` from the JSON response — no CLI login involved.189- Model files (GLB/FBX/OBJ/STL, ≤150 MB) use the same ticket with190 `kind: "model"` and `format`; the `file_token` then feeds191 `tripo_import_model` or any processing tool directly.192- Task ids chain: a successful generation task is a valid `input` for every193 processing tool, so never re-upload what Tripo already has.194195## Other tools196197- `tripo_plan` — free draft of the intended tool chain before any billed call.198- `tripo_task_status` — fresh links for any task; `steps: true` adds the199 per-stage breakdown when a chain misbehaves.200- `tripo_task_list` — status of up to 100 task ids in one call (batches).201- `tripo_usage` — recent per-task credit spend (includes per-task breakdown).202- `tripo_mesh_edit` — P2 Preview regional regenerate (`bbox` + optional203 `ref_image`).204205## Spending the user's credits206207- `tripo_balance` first when the user asks for several assets; confirm before208 generating more than one in a batch, and report `credits_consumed` after.209- Insufficient balance errors: give the `plans_url` from `tripo_balance`210 (informational pricing page for this deployment's region) instead of retrying.211212---213214# CLI path215216Everything below runs through the shell. One command turns a prompt or an217image into local files: a model, a `preview.png` render, and a `task.json`218record.219220## Before the first generation221222```bash223npx tripo-cli@latest doctor # verifies key, network, region, balance224```225226Auth resolves from `TRIPO_API_KEY` (a `tsk_...` key) or a previous `tripo login`.227If `doctor` reports no key, start the device login yourself — do not ask for228permission first, and never ask the user to paste a key into the chat.229230Tripo has two regions with separate accounts and consoles:231232| region | console | sign-in / top-up |233| --------------------- | ------------------------------ | ------------------------------ |234| `cn` — China mainland | https://developers.tripo3d.com | +86 SMS sign-in, Alipay top-up |235| `ov` — International | https://developers.tripo3d.ai | email sign-in, Stripe top-up |236237Pick the region yourself only when the context already says which site the238user's account is on — they mentioned it, `tripo whoami` shows a profile, or239`TRIPO_REGION` is set. Otherwise ask one question before starting the login:240"你的 Tripo 账号在国内站还是海外站?" An account lives in exactly one region,241and starting the device flow on the wrong console sends the user to a site242where their account does not exist. No account yet? China-mainland users243should pick `cn` (Alipay top-up), everyone else `ov` — signing up during the244login flow is fine and new accounts get free credits.245246```bash247npx tripo-cli@latest login --region cn --yes # or: --region ov248```249250`--yes` forces the non-interactive device flow. The command prints a251verification URL and a one-time code right away, then blocks until the user252approves in a browser — up to 15 minutes. Do not kill it early, and do not253wait for it to exit before talking to the user: read the URL and code from254its output while it is still running (run it in the background or stream its255stderr). **Show the user the full verification URL and the code verbatim**,256plus the matching console address (`cn`: https://developers.tripo3d.com,257`ov`: https://developers.tripo3d.ai), and walk them through every step —258assume they have never seen this page:2592601. Open the verification URL in a browser.2612. If the page asks to sign in, they are not logged in on the web either:262 sign in — or sign up at the console address above; new accounts get263 free credits — then return to the verification page.2643. Type the one-time code into the **"Verification code"** field.2654. An account that already has several API keys is asked to pick one — any266 of them works, the CLI will use the chosen key. With no keys, one is267 created automatically and there is nothing to choose.2685. Click the **Authorize** button. The key arrives in the CLI and is stored —269 nothing to copy by hand.270271When the command exits 0, re-run `doctor` and continue. Exit code 3 means the272code expired or was denied — run the same login command again for a fresh273code. If an older CLI rejects headless login with a usage error, fall back to274asking the user to run `npx tripo-cli@latest login` in their own terminal.275276Installing globally (`npm install -g tripo-cli`) makes repeated calls faster and277is what makes the bare `tripo` command exist — ask before doing it. Without a278global install, run every `tripo ...` command in this and related skills as279`npx tripo-cli@latest ...`; npx downloads the CLI on first use, so a fresh machine280needs no manual install. If `npx` itself is missing, Node.js is not installed —281have the user install Node.js LTS first. On China-mainland networks, when the282npx download stalls, switch to the npmmirror registry and retry:283`npm config set registry https://registry.npmmirror.com`.284285Exit code 3 means auth failed; run `tripo doctor`, which diagnoses key-vs-region286mismatches (`ov` = international, `cn` = China mainland) and prints the exact fix.287288## The command289290```bash291tripo make "a stylized treasure chest" --for game-mobile --json --yes292tripo make concept.png --for game-pc --json --yes293tripo make front.png back.png --json --yes # 2-4 images -> multiview294tripo make hero.glb --then texture,rig --json --yes # import an existing mesh295tripo make @last --then convert:fbx --json --yes # continue from the last task296```297298Input type is auto-detected: quoted text, an image path or URL, 2-4 images, a model299file, or a task reference (`@last`, `@name`, a task id).300301A local image file is uploaded by the CLI itself — always reliable. An image302URL is passed straight to the API and **fetched by Tripo's servers**, so when303the user gives a URL, tell them explicitly: it must be publicly reachable and304served through a CDN or globally accelerated host, or the server-side fetch305can fail or time out (auth-protected, region-locked and slow-origin links all306break). When in doubt, download the image locally first and pass the file307path instead.308309- `--for <scenario>` picks model, parameters, chain and export format:310 `game-mobile` `game-pc` `film` `print` `ar-web` `anim` `toy`.311 The base generation already outputs GLB; some preset chains append a **paid**312 convert step (`game-mobile`/`game-pc` → FBX, `print` → STL, `ar-web` → USDZ).313 When the user only wants GLB, that convert buys a format nobody asked for —314 use a chain-free preset instead (`toy` for low-poly, with `-p face_limit=...`)315 or tell the user the extra format costs credits before running.316- `--then <steps>` overrides the chain. Steps: `texture` `convert`317 `import` `rig-check` `rig` `retarget` `segment` `complete` `decimate` `smartsegment`.318 Arguments use `step:key=value`; a bare value maps to the step's primary argument319 (`convert:fbx`, `decimate:5000`).320- `-o, --out <dir>` sets the **parent** directory, not the artifact directory. `make`321 always creates `<dir>/tripo-out/<name>-<id8>/` underneath it, so `-o ./assets` writes322 `./assets/tripo-out/<name>-<id8>/model.glb`. Pass `-o` to keep artifacts inside the323 project instead of the shell's working directory, but when the user asked for a file324 at a specific path, **move it there after the run and report the final path** — `-o`325 alone cannot put it there. (`tripo task get <id> --download -o <dir>` is the326 exception: its `-o` is the final directory.)327- `-p key=value` passes an API parameter, repeatable. Useful ones: `face_limit=15000`,328 `texture=false pbr=false` (bare geometry, skips texture credits), `auto_size=true`,329 `texture_quality=detailed`, `negative_prompt=...`. `--model` forces the generation330 model (`tripo-v3.1` / `tripo-p1` / `tripo-p2` → wire `v3.1-20260211` /331 `P1-20260311` / `P2-20260801`). `--dry-run` plans and validates with zero network332 calls (no credits, no key) and prints the chosen wire-value `model`,333 `steps[].payload`, `warnings` and `errors`; only run for real when `valid` is true.334 After a chained run, report `credits_consumed` (total) and `credits_breakdown`335 (per task); if the field is missing, `tripo task get <id> --json` each chain entry.336337## Rules that matter3383391. **`tripo make` is blocking.** It submits, polls, downloads, then exits. Wait for340 the process to finish. Do not re-implement polling, do not set a timeout shorter341 than the CLI's own (default 1800s), and do not treat a `task_id` appearing in the342 logs as completion.3432. **stdout is the contract.** With `--json`, stdout carries exactly one final JSON344 line; progress goes to stderr. Parse the last stdout line, not the logs.3453. **Branch on exit codes**, don't parse error text:346 `0` ok · `1` fatal, and what `doctor` returns when a critical check fails ·347 `2` bad parameters · `3` auth · `4` insufficient credits · `5` content348 policy · `6` task failed (credits auto-refunded, `tripo redo` often succeeds) ·349 `7` network · `8` not found — a task id only resolves under the key that created350 it, so when an older task 404s, fall back to passing the local model file ·351 `9` rate limit (retry with backoff).3524. **Judge the result before moving on.** The result JSON gives `model_file` and353 `preview`. Read `preview.png` to check the asset actually matches the request; if354 it does not, `tripo redo` re-rolls with a new seed.3555. **Never invent parameters.** Run `tripo docs --topic commands/make` for the full356 flag list, or `tripo docs --topic common-errors` for the error table.3576. **Let the CLI choose the model version.** It selects `tripo-v3.1` (high fidelity)358 or `tripo-p1` (low-poly, face budget 50-20000) automatically. Only pass `--model`359 when the user explicitly asks for one (`tripo-p2` Preview for quads).360361Download URLs returned by the API expire in about five minutes — never cache one.362Re-run `tripo task get <id> --download` instead.363364365---366367# Capability reference368369Model versions, generation/processing parameters, 2D steps, list prices, CLI370result shape and other commands: read [`references/capability.md`](references/capability.md)371(same parameter names on MCP and CLI). MCP also has `tripo_plan` (confirm before372spend) and `tripo_mesh_edit` (P2 regional redo).