diff --git a/marketplace.json b/marketplace.json index c7f09a06..de292800 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1097,12 +1097,12 @@ "en": "Tripo 3D", "zh-CN": "Tripo 3D" }, - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, - "version": "0.1.4", + "version": "0.1.5", "author": { "name": "VAST", "url": "https://www.tripo3d.ai" @@ -1125,14 +1125,7 @@ "Generate a low-poly treasure chest and export it as FBX for Unity", "Turn this concept image into a textured 3D model and export it as GLB", "Make a 3D-printable knight figurine and export STL" - ], - "examplePrompts_i18n": { - "zh-CN": [ - "生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用", - "把这张概念图变成带贴图的 3D 模型,导出 GLB", - "生成一个可 3D 打印的骑士小雕像,导出 STL 文件" - ] - } + ] }, { "name": "kicad", diff --git a/plugins/tripo-3d/.claude-plugin/plugin.json b/plugins/tripo-3d/.claude-plugin/plugin.json index 16aab3c6..94c37a16 100644 --- a/plugins/tripo-3d/.claude-plugin/plugin.json +++ b/plugins/tripo-3d/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", - "version": "0.1.3", - "description": "Generate textured, rig-ready 3D models from a text prompt or a reference image with Tripo, and export GLB/FBX/OBJ/STL/USDZ/3MF straight into your project. Connect your China-mainland Tripo account once in the browser (OAuth), no API key pasting.", + "version": "0.1.5", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured, rig-ready 3D models from a text prompt or a reference image with Tripo, and export GLB/FBX/OBJ/STL/USDZ/3MF straight into your project. Connect your China-mainland Tripo account once in the browser (OAuth), no API key pasting.", - "zh-CN": "用 Tripo 从一句话或一张图生成带贴图、可绑骨的 3D 模型,支持动画、减面与 GLB/FBX/OBJ/STL/USDZ/3MF 导出,文件直接落到项目里。浏览器里授权一次国内站 Tripo 账号即可使用,无需粘贴 API Key。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/.mcp.json b/plugins/tripo-3d/.mcp.json index edf7df96..58e1b3bc 100644 --- a/plugins/tripo-3d/.mcp.json +++ b/plugins/tripo-3d/.mcp.json @@ -4,7 +4,19 @@ "type": "http", "url": "https://developers.tripo3d.com/mcp", "enabled": true, - "timeoutMs": 90000 + "timeoutMs": 90000, + "headers": { + "X-Tripo-Distribution": "zcode_plugin" + } + }, + "tripo-global": { + "type": "http", + "url": "https://openapi-mcp.tripo3d.ai/mcp", + "enabled": true, + "timeoutMs": 90000, + "headers": { + "X-Tripo-Distribution": "zcode_plugin" + } } } } diff --git a/plugins/tripo-3d/.zcode-plugin/plugin.json b/plugins/tripo-3d/.zcode-plugin/plugin.json index 55f169ee..94c37a16 100644 --- a/plugins/tripo-3d/.zcode-plugin/plugin.json +++ b/plugins/tripo-3d/.zcode-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "tripo-3d", - "version": "0.1.4", - "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", + "version": "0.1.5", + "description": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", "description_i18n": { - "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Requires a mainland China Tripo account.", - "zh-CN": "用文字或图片生成带贴图的 3D 模型,添加骨骼与动画、精简模型面数,导出用于游戏或 3D 打印的素材。需使用 Tripo 国内站账号。" + "en": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts.", + "zh-CN": "Generate textured 3D models from text or images, add rigging and animation, simplify meshes, and export assets for games or 3D printing. Works with mainland China and international Tripo accounts." }, "author": { "name": "VAST", diff --git a/plugins/tripo-3d/README.md b/plugins/tripo-3d/README.md index 6f49a8b4..78b51136 100644 --- a/plugins/tripo-3d/README.md +++ b/plugins/tripo-3d/README.md @@ -1,25 +1,47 @@ # Tripo 3D -[中文](./README_CN.md) +## 0.1.5 + +Works with both China-mainland and international Tripo accounts: the plugin +ships one MCP server per region, `tripo` for the China site and `tripo-global` +for the international site, and you authorize the one your account belongs to. + +A user's explicitly chosen compatible model overrides usage-based defaults. +Game/realtime recipes explicitly prefer **P2** (more credits than H/P1), the +P-series default; **P1** is used only when the user names it or picks it for lower +cost and speed, and v3.1 for film/render/print. Rigs pass the model +explicitly, v3.0 for bipeds and v2.5 for animals (the API's own default, v1.0, +rigs bipeds only), with animation presets selected +from the upstream rig model. Retopology v3.0's +`smart_uv` and standalone `tripo_smart_uv` are distinct billed workflows. +Fast textures require v3.5; `chat_image_1` is retired. + +The plugin runs through the Tripo MCP tools only — there is no CLI path, and +missing authorization is never a reason to switch to one. PBR stays off unless +you explicitly ask for it. A plan is advisory, not a price quote or budget lock. +Show estimated or unestimated costs, cite the source, region and date of any +static list estimate, and obtain explicit consent. Never switch accounts silently. +The hook also enforces the PBR default and explicit model/billing decisions. The official Tripo plugin for ZCode. Generate textured 3D models from a text prompt or a reference image, with rigging, animation, retopology and format conversion (GLB/FBX/OBJ/STL/USDZ/3MF), and land the files directly in your project. Built for games, film, AR and 3D printing. -Connect your **China-mainland** Tripo account once in the browser -(developers.tripo3d.com) — no API key pasting. This build's MCP endpoint is -China-only; overseas-site accounts need the overseas Tripo 3D plugin build, or -the CLI with `--region ov`. +Connect your Tripo account once in the browser — no API key pasting. Both +**China-mainland** (developers.tripo3d.com) and **international** +(developers.tripo3d.ai) accounts work: the plugin ships one MCP server per +region and you authorize only the one your account belongs to. ## Components | Component | What it does | | --- | --- | -| Skill `tripo-3d` | Main workflow: execution-path selection, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules; plus the fallback `tripo-cli` path | +| Skill `tripo-3d` | Main workflow: tool check, authorization guidance, MCP workflow, scenario → tool-chain mapping, input handling, credit rules | | Skill `tripo-game-asset` | Game-asset recipes: budgeted low-poly props, LOD chains, rigged characters with locomotion clips, wiring into Unity/Unreal/Godot/Three.js | -| MCP server `tripo` | Remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1) exposing 26 tools such as `tripo_plan`, `tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_task_wait`, `tripo_mesh_edit`, `tripo_rig`, `tripo_animate`, `tripo_convert` | -| Hook `SessionStart` | Injects five hard rules (async waiting, link expiry, credit confirmation / `tripo_plan`, browser authorization, honest failure reporting) so they hold even when no skill was triggered | +| MCP server `tripo` | China site: remote Streamable HTTP server `https://developers.tripo3d.com/mcp` (OAuth 2.1), including `tripo_plan`, generation, rigging, conversion and `tripo_smart_uv`; available tool schemas are authoritative | +| MCP server `tripo-global` | International site: the same tools on `https://openapi-mcp.tripo3d.ai/mcp` (OAuth 2.1) | +| Hook `SessionStart` | Injects seven rules: async waiting, link expiry, credit confirmation, browser authorization, honest failures, PBR off by default and explicit model/billing decisions, plus a region hint from the system time zone | ## Usage @@ -36,15 +58,18 @@ from the Skills group. ### First-time authorization -The Tripo MCP server needs a one-time authorization: - -1. Open **Settings → MCP**, find the Tripo row under "Plugin MCP servers" - (it shows "Authorization required") and click **Open authorization**. -2. The system browser opens the Tripo authorization page for the **China site** - (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up). There is no - region picker on this page. You can sign up on the spot; new accounts get - free credits. An international-site account will not authorize against this - build — use the overseas plugin or `tripo-cli` with `--region ov`. +Authorize the Tripo MCP server for your account's region once: + +1. Open **Settings → MCP Servers**. Under "Plugin MCP servers" there are two Tripo + rows, both showing "Authorization required": `tripo` for a China-mainland + account and `tripo-global` for an international account. Click + **Open authorization** on the row for your account; the other row can stay + as it is. +2. The system browser opens that site's authorization page: `tripo` uses the + **China site** (developers.tripo3d.com — +86 SMS sign-in, Alipay top-up), + `tripo-global` the **international site** (developers.tripo3d.ai — email + sign-in, Stripe top-up). The page has no region picker. You can sign up on + the spot; new accounts get free credits. 3. The page shows a one-time verification code and opens the Tripo console: sign in, type the code into **Verification code**, click **Authorize**. 4. ZCode reconnects and loads the tools automatically. To revoke access, @@ -53,35 +78,42 @@ The Tripo MCP server needs a one-time authorization: ## Dependencies, network access and side effects -- **Network**: MCP tool calls go to `https://developers.tripo3d.com/mcp`; - authorization redirects to the China Tripo console - (developers.tripo3d.com). Results are downloaded from Tripo's CDN through - short-lived links (about 5 minutes). +- **Network**: ZCode connects to both MCP endpoints, + `https://developers.tripo3d.com/mcp` (China site) and + `https://openapi-mcp.tripo3d.ai/mcp` (international site); tool calls go + only to the one you authorized, and authorization redirects to that site's + Tripo console. Results are downloaded from Tripo's CDN through short-lived + links (about 2 hours). - **Account and billing**: every generation spends credits from your own - Tripo account; each tool reports `credits_consumed`, failed tasks are - refunded automatically. The skill drafts the chain with `tripo_plan`, + Tripo account; use task status and the usage ledger for actual charges. Failed + tasks are refunded automatically. The skill drafts the chain with `tripo_plan`, checks the balance and asks before generating a batch. - **File writes**: only when you ask for the model on disk, the agent - downloads it into your project with `curl`. The hook and the MCP server + downloads it into your project with `curl`. The hook and the MCP servers write nothing. -- **Command execution**: on the MCP path, shell commands run only to upload a - local image/model (the `curl` returned by `tripo_upload_ticket`) or to - download a result. The fallback CLI path downloads and runs - [tripo-cli](https://www.npmjs.com/package/tripo-cli) (MIT, via - `npx tripo-cli@latest`), only for jobs that need it (e.g. bulk generation), - and says so first. +- **Command execution**: shell commands run only to upload a local image/model + (the `curl` returned by `tripo_upload_ticket`) or to download a result. The + plugin never installs or runs a command-line client, including after an MCP + failure, missing authorization, batch work or a request to save files locally. - **Hook**: `hooks/session-start.mjs` needs `node` on PATH. It reads the - event from stdin and prints a fixed text to stdout; no network, no file - access. -- **No data collection**: the plugin contains no telemetry; account - credentials are managed by ZCode's credential store and never pass through - the chat. + event from stdin and prints the rules plus a region hint derived from the + system time zone to stdout; no network, no file access. +- **Telemetry**: the plugin has no independent analytics SDK. When enabled on + the Tripo MCP server you authorized (China or international site; both + record the same fields), analytics can record tool results, task + metadata and the Tripo account ID when resolved. Both MCP servers declare the + non-credential `X-Tripo-Distribution: zcode_plugin` header; if the host + forwards it, the server records the distribution channel separately from + the detected client (such as ZCode, Claude, or unknown). Analytics excludes + prompts, API keys, OAuth tokens, file paths and signed download links. + Account credentials are managed by ZCode's credential store and never pass + through the chat. ## Provenance and license - Plugin: MIT, by [VAST](https://www.tripo3d.ai). - Both skills are ported from Tripo's official Kimi / Codex plugins (also maintained by VAST, MIT). -- The MCP server and `tripo-cli` are official Tripo implementations; +- Both MCP servers run the official Tripo implementation; generated content is subject to the [Tripo API content policy](https://platform.tripo3d.ai/docs). diff --git a/plugins/tripo-3d/README_CN.md b/plugins/tripo-3d/README_CN.md deleted file mode 100644 index 8fedd44c..00000000 --- a/plugins/tripo-3d/README_CN.md +++ /dev/null @@ -1,56 +0,0 @@ -# Tripo 3D - -[English](./README.md) - -Tripo 官方 ZCode 插件。用一句话或一张图生成带贴图的 3D 模型,支持骨骼绑定、动画、 -减面和格式转换(GLB/FBX/OBJ/STL/USDZ/3MF),文件直接落到你的项目里。覆盖游戏、 -影视、AR 和 3D 打印场景。 - -浏览器里授权一次**国内站** Tripo 账号即可使用(developers.tripo3d.com),无需复制 -API Key。本构建的 MCP 只对接国内站;海外站账号请安装海外版插件,或用 CLI -`--region ov`。 - -## 包含的组件 - -| 组件 | 内容 | -| --- | --- | -| Skill `tripo-3d` | 主流程:执行路径选择、授权引导、MCP 工作流、场景 → 工具链映射、输入处理、积分规则;以及备用的 `tripo-cli` 路径 | -| Skill `tripo-game-asset` | 游戏资产配方:面数预算道具、LOD 链、绑骨角色与动画、接入 Unity/Unreal/Godot/Three.js | -| MCP 服务器 `tripo` | 远程 Streamable HTTP server `https://developers.tripo3d.com/mcp`(OAuth 2.1),提供 `tripo_plan`、`tripo_text_to_3d`、`tripo_image_to_3d`、`tripo_task_wait`、`tripo_mesh_edit`、`tripo_rig`、`tripo_animate`、`tripo_convert` 等 26 个工具 | -| Hook `SessionStart` | 会话开始时注入 5 条硬规则(异步等待、链接过期、积分确认 / `tripo_plan`、浏览器授权、如实报错),保证即使 skill 未被触发也遵守 | - -## 怎么用 - -安装并启用插件后,直接描述需求即可,例如: - -- 生成一个低多边形的宝箱 3D 模型,导出 FBX 给 Unity 用 -- Turn this concept image into a textured 3D model and export it as GLB -- 生成一个可 3D 打印的骑士小雕像,导出 STL 文件 -- 生成一个 T-pose 的机器人角色,绑好骨骼并加上走路动画 -- 查一下我的 Tripo 余额 - -也可以在输入框输入 `/` 从「技能」分组手动选用 `tripo-3d` 或 `tripo-game-asset`。 - -### 首次授权 - -首次使用时 Tripo 的 MCP 服务器需要授权: - -1. 打开 **设置 → MCP**,在「Plugin MCP 服务器」分组找到 Tripo 一行(显示「需要授权」),点 **打开授权**。 -2. 系统浏览器打开的授权页对接**国内站**控制台(developers.tripo3d.com,+86 短信登录、支付宝充值),**没有选区步骤**。没有账号可以顺手注册,新账号有免费额度。海外站账号无法在此构建上授权——请改用海外版插件,或 CLI `--region ov`。 -3. 页面显示一次性验证码并跳转 Tripo 控制台:登录后把验证码填入 **Verification code**,点 **Authorize**。 -4. ZCode 自动重连并加载工具。撤销授权:在 Tripo 控制台的 API Keys 页删除授权时选定的 Key。 - -## 依赖、网络访问与副作用 - -- **网络**:MCP 工具调用走 `https://developers.tripo3d.com/mcp`;授权页跳转到国内站 Tripo 控制台(developers.tripo3d.com)。生成结果通过 Tripo 的 CDN 短期链接(约 5 分钟过期)下载。 -- **账号与计费**:所有生成任务消耗你自己 Tripo 账号的积分,每次工具返回 `credits_consumed`;失败任务自动退款。批量生成前 skill 会先用 `tripo_plan` 草稿、查余额并确认。 -- **文件写入**:只在你要求把模型落到本地时,用 `curl` 把结果下载到项目目录;Hook 与 MCP 服务器本身不写任何文件。 -- **命令执行**:MCP 路径下仅在上传本地图片/模型(`tripo_upload_ticket` 返回的 curl)或下载结果时运行 shell 命令。备用 CLI 路径通过 `npx tripo-cli@latest` 从 npm 下载并运行 [tripo-cli](https://www.npmjs.com/package/tripo-cli)(MIT),只在批量生成等需要时使用,且会先说明。 -- **Hook**:`hooks/session-start.mjs` 依赖 PATH 中的 `node`,只从 stdin 读取事件、向 stdout 输出一段固定文本,不访问网络、不读写文件。 -- **不采集任何数据**:插件本体不含遥测;账号凭据由 ZCode 的凭据存储管理,不经过对话。 - -## 来源与许可 - -- 插件本体:MIT,作者 [VAST](https://www.tripo3d.ai)。 -- 两个 skill 由 Tripo 官方的 Kimi / Codex 插件(同为 VAST 维护,MIT)移植而来。 -- MCP 服务器与 `tripo-cli` 均为 Tripo 官方实现;生成内容遵循 [Tripo API 内容策略](https://platform.tripo3d.ai/docs)。 diff --git a/plugins/tripo-3d/hooks/session-start.mjs b/plugins/tripo-3d/hooks/session-start.mjs index e0d840db..24101fdb 100644 --- a/plugins/tripo-3d/hooks/session-start.mjs +++ b/plugins/tripo-3d/hooks/session-start.mjs @@ -1,14 +1,23 @@ #!/usr/bin/env node -// SessionStart hook: inject the Tripo hard rules as additionalContext. +// SessionStart hook: inject the Tripo hard rules and a time-zone region hint as additionalContext. // Reads one JSON event from stdin, writes one JSON object to stdout. // Keep this text in sync with skills/tripo-3d/SKILL.md. const RULES = `Tripo 3D — rules that apply whenever Tripo tools (tripo_*) are used. These hold even when the tripo-3d skill was not loaded; load it for the full workflow. 1. Generation is asynchronous. Every tripo_* generation or processing tool returns a task_id immediately. Call tripo_task_wait with it and keep calling while status is queued/running — each call returns within about 55 seconds, a generation usually takes 1–4 minutes. Never present a result before status is success, and never treat a task_id as a finished model. -2. Show the result, then the link. On success, embed preview_image_url as a markdown image and give model_url as the download link. Both URLs expire in about 5 minutes: never re-print an old one — call tripo_task_status for fresh links. If you saved the file locally, give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes). -3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain. Every billed tool reports credits_consumed. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — show the preview and ask first. -4. Authorization is a browser flow, never a pasted key. This build's MCP is China-mainland only (developers.tripo3d.com/mcp); the auth page has no region picker. If Tripo tools are missing or a call reports an authorization error, tell the user to open ZCode 设置 → MCP, find the Tripo server under「Plugin MCP 服务器」and click「打开授权」, then sign in on the 国内站 console and Authorize. An overseas-site account needs the overseas plugin build or CLI login --region ov. Do not ask for an API key in the chat, and do not run tripo-cli instead just because a local login or TRIPO_API_KEY exists — offer the CLI only as an explicit alternative and use it only if the user picks it. -5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. Stylize has been retired: there is no tripo_stylize and no CLI --then stylize. Use tripo_mesh_edit for P2 regional redo.`; +2. Deliver the file, then one link. On success, download model_url to a local file when a shell is available and give its path as plain text in backticks, never as a clickable link (chat previews cannot render meshes); then also offer model_url as a single markdown download link. Do not paste URLs from output_urls into the reply. Result URLs expire after about 2 hours: never re-print an old one — call tripo_task_status for fresh links. +3. Credits belong to the user. Call tripo_plan and get confirmation before any billed generation or chain; supply structured generation only for tripo_text_to_3d, tripo_image_to_3d and tripo_multiview_to_3d, including the exact text prompt for text-to-3D; never add generation to other steps such as tripo_image_to_splat. For those three use dry_run only when the connected schema exposes it; validate other steps against their schemas and current pricing. Resolve user-requested parameter conflicts before billing. Plan estimates are advisory, not a budget lock; label unknown costs not_estimated, and cite source, region and date for any static list estimate. Use tripo_usage for all task_ids to report actual total and per-task charges; if unavailable say the amount is pending. Check tripo_balance and confirm before generating more than one asset in a batch; on insufficient balance give the returned plans_url instead of retrying. Never silently re-roll a disappointing result — say what is off and ask first. +4. Authorization is a browser flow, never a pasted key. The plugin has one MCP server per Tripo region, and an account exists in only one region: tripo is the China site (developers.tripo3d.com, +86 SMS sign-in), tripo-global is the international site (developers.tripo3d.ai, email sign-in); neither auth page has a region picker. If Tripo tools are missing or a call reports an authorization error, ask which site the user's Tripo account is on unless they already said, then tell them to open ZCode Settings → MCP Servers, find that server under "Plugin MCP servers" and click "Open authorization" (ZCode shows these labels in its UI language), then sign in on that site's console and Authorize. The other server keeps showing "Authorization required", which is expected. If tools from both servers are available, ask which account to spend credits from and keep each task chain on that server: task IDs, file tokens and balances do not carry across regions. Never switch servers silently. Do not ask for an API key in the chat. MCP is the only execution path: never install or run a command-line client instead, even when a local login or API key exists. +5. Failures are reported, not hidden. On failed/banned, relay failure_reason (and error_code) honestly; failed-task credits are refunded automatically. Never invent parameters — the tool schemas are authoritative. If a creation call times out without a task_id, do not automatically retry: check the original account's balance and task history when available and ask before another submission. Stylize has been retired: there is no tripo_stylize tool. tripo_mesh_edit is experimental; use it only if the connected server lists it. +6. PBR is opt-in. Send pbr: false on every tripo_text_to_3d, tripo_image_to_3d, tripo_multiview_to_3d and tripo_texture call unless the user explicitly asks for PBR (e.g. "with PBR" or "PBR materials", in any language); only then send pbr: true, which also forces texture: true. The API turns PBR on when pbr is omitted, so never leave it out. Detailed or high-quality textures do not mean PBR. +7. Choose models explicitly: the user's explicit compatible model wins over usage-based defaults; if requirements conflict, explain and ask before changing model or dropping a requirement. P2 is preferred for game/realtime topology and costs more credits than H/P1; within the P series the default is P2, and P1 is used only when the user names it or picks it for lower cost and speed; v3.1 for film/render/print. Do not infer the model from face_limit. Cost is not estimated by this text or guaranteed by tripo_plan: disclose uncertainty and obtain consent before billing. Pass the rig model explicitly: v3.0 for bipeds, v2.5 for animal body types (the API's own default is v1.0, which rigs bipeds only); use preset:walk, reserving preset:biped:* for explicit v1.0 rigs. Retopology v3.0 with smart_uv and standalone tripo_smart_uv are separate workflows, not interchangeable free export switches. Load the capability reference before running either. chat_image_1 is retired; never fall back to it. chat_image_1.5 remains usable where supported before 2026-12-01; never silently replace a user-selected paid image model. fast textures require texture model v3.5: pass the short name v3.5, or omit the version and the tool picks it. +`; + +const CHINA_TIME_ZONES = new Set(["Asia/Shanghai", "Asia/Urumqi", "Asia/Chongqing", "Asia/Chungking", "Asia/Harbin", "Asia/Kashgar", "PRC"]); +const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone; +const regionHint = timeZone + ? `Region hint: the system time zone is ${timeZone}, which suggests ${CHINA_TIME_ZONES.has(timeZone) ? "the China site (tripo)" : "the international site (tripo-global)"}. Use it only to phrase the question in rule 4; never choose a server for the user on this guess.\n` + : ""; let raw = ""; process.stdin.setEncoding("utf8"); @@ -25,6 +34,6 @@ try { process.stdout.write( JSON.stringify({ - hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES }, + hookSpecificOutput: { hookEventName: eventName, additionalContext: RULES + regionHint }, }), ); diff --git a/plugins/tripo-3d/skills/tripo-3d/SKILL.md b/plugins/tripo-3d/skills/tripo-3d/SKILL.md index 38758ebf..7544fca0 100644 --- a/plugins/tripo-3d/skills/tripo-3d/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-3d/SKILL.md @@ -1,44 +1,38 @@ --- name: tripo-3d -description: 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. +description: 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", and the same requests in any language (text-to-3D, image-to-3D, rigging, character animation, texturing, low-poly or face reduction, 3D-printed figurines, format conversion). Also use to re-run, convert or inspect a previous Tripo generation. --- # 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 - -1. **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. -2. **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. -3. **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. -4. **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 +Generate engine-ready 3D assets with the Tripo MCP tools. +Use a live estimate if available. A dated list-price estimate may be shown with +its source, region and date, but is not a live quote; disclose any unestimated +steps and obtain explicit consent before any billed task. A plan is advisory, +not a budget limit or an authorization ticket. + +## Before you start + +The tool list must contain the 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). The +server id in the prefix tells the region: `tripo` is the China site, +`tripo-global` is the international site. + +If they are missing, the plugin's MCP servers are almost always waiting for +authorization or switched off, not absent. Stop, ask which site the user's +Tripo account is on, and tell them: open **Settings → MCP Servers**, find that +region's server under "Plugin MCP servers", click **Open authorization** if the +row says "Authorization required" (if it says "Plugin disabled", enable the +Tripo 3D plugin first), then start a new session. See Authorization below. +Do not describe generations as if they had run. + +MCP is the only execution path. Never install or run a command-line client +instead — not for a balance check, not because a local login or +`TRIPO_API_KEY` happens to exist (that may be a different account, and the +user installed this plugin to use MCP). Local files and bulk jobs stay on MCP +too: `tripo_upload_ticket` covers both images and mesh files (see Inputs +below), and results are downloaded with `curl` (see Deliver). ## Authorization @@ -47,16 +41,26 @@ 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`. - -1. **设置 → MCP** → group 「Plugin MCP 服务器」 → the Tripo row shows - 「需要授权」 → click **打开授权**. The system browser opens the Tripo +**The plugin ships one MCP server per Tripo region.** An account lives in +exactly one region, and neither authorization page offers a region picker: + +| MCP server | Region | Console | +| --- | --- | --- | +| `tripo` (`https://developers.tripo3d.com/mcp`) | China site — mainland China | developers.tripo3d.com, +86 SMS sign-in, Alipay top-up | +| `tripo-global` (`https://openapi-mcp.tripo3d.ai/mcp`) | International site | developers.tripo3d.ai, email sign-in, Stripe top-up | + +Ask once whether the user's account is on the China site or the international +site, unless they already said. The session context may carry a time-zone region +hint; use it only to phrase the question, never to choose for the user. No +account yet? Users in mainland China pick the China site, everyone else the +international site; they can sign up during authorization and new accounts get +free credits. Only the chosen server needs authorizing; the other row keeps +showing "Authorization required", which is expected. ZCode shows these labels +in its UI language. + +1. **Settings → MCP Servers** → group "Plugin MCP servers" → the chosen + server's row (`tripo` or `tripo-global`) shows "Authorization required" → + click **Open authorization**. The system browser opens that region's authorization page. 2. 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 @@ -69,70 +73,106 @@ 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. +the console's API Keys page — any other client sharing that key loses access +too. + +If tools from both servers are available, ask which account to spend credits +from before the first billed step, and keep the whole task chain on that +server: task IDs, file tokens and balances belong to one region and do not +carry over to the other server. Never switch servers silently. ## Workflow -1. **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`). +1. **Plan** — for any billed generation or chain, call `tripo_plan` first. + For `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d` + steps only, supply a structured `generation` object; include the exact + `prompt` for text-to-3D. Never attach `generation` to other tools, including + `tripo_image_to_splat`. Free-text `params` alone leave the model unresolved. + For these three generation tools, review the exact payload with `dry_run` only + when the connected tool schema exposes it. For other steps review their actual + schemas and current pricing without inventing a `dry_run` argument. Resolve + conflicts with explicit requirements before billing; do not accept silently + stripped requirements. + Show each billed step, selected model, options and estimate or + `not_estimated` to the user, and wait for explicit confirmation. Skip the + plan only for pure reads (`tripo_balance`, `tripo_usage`, `tripo_task_status` + / `tripo_task_list`). Re-plan and reconfirm changed paid steps. 2. **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. + `task_id` immediately. If creation times out without a `task_id`, do not + automatically retry: check the original account's balance and task history + when available, then ask the user before considering another submission. 3. **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. -4. **Judge** — on `success`, look at `preview_image_url` and show it to the - user before building on the result. On `failed`/`banned`, report +4. **Judge** — on `success`, check the result before building on it: you may + look at the rendered image listed in `output_urls`, but never paste + `output_urls` into the reply. 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; + Do not silently re-roll a disappointing result — say what is off and ask; re-rolling means creating a new task with the same prompt. -5. **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. +5. **Post-process** (each asynchronous task requires `tripo_task_wait`; check + billing for each step — `tripo_rig_check` is free. `input` takes a model + task_id, a `file_token` or a public model URL unless noted): + - `tripo_texture` — texture or re-texture a model. Provide guidance for an + imported mesh; it may be omitted for a Tripo-generated model. Re-supply + the original reference image when re-texturing a model made from one. - `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. + Prompt characters as **T-pose** at generation time; `spec: "unity"` for + Unity Humanoid, `"mixamo"` for Mixamo pipelines. Always pass `model` by + body type: `"v3.0"` for `biped`, `"v2.5"` for the animal types the check + reports (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). + The API's own default is still `v1.0-20240301`, which rigs bipeds only. + The `tripo_rig` 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_rig`: explicit legacy v1.0 rigs take `preset:biped:walk`, + `preset:biped:idle`, …; v3.0 and v2.5 rigs take `preset:walk`, + `preset:idle`, … on bipeds and only their body-type clip on creatures + (`preset:quadruped:walk`, …; avian has none); `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". + via `face_limit`/`quad`. Quads cannot export GLTF. Any `face_limit`, or a + non-default `quad`, `flatten_bottom`, `texture_size`, `texture_format`, + `pivot_to_center_bottom` or `scale_factor`, 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. -6. **Deliver** — result URLs (`model_url`, `preview_image_url`) **expire in - about 5 minutes**; never cache or re-print an old one — call + parts and close the cuts. `tripo_mesh_edit` can redo one region of an + existing mesh with P2 (`bbox` required). It is experimental; use it only + when the connected server's actual tool list exposes it. Stylize (lego / + voxel / voronoi / minecraft) has been retired — there is no `tripo_stylize` tool. +6. **Deliver** — result URLs (`model_url` and `output_urls`) **expire after + about 2 hours**; never cache or re-print an old one — call `tripo_task_status` for fresh links. Download the file into the project - (`curl -L -o ""`) and give the local path as plain text in + (`curl -L -o ""`) 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. + meshes — then also offer `model_url` as a single markdown download link; + offer the next real action: reveal it in the file manager + (`open -R ` on macOS, `explorer /select,` on Windows) or wire it + into the project. Only when no shell is available give just the fresh + `model_url` link and say it is short-lived, offering to refresh it on + request. Do not paste other URLs from `output_urls`. After a + `tripo_convert`, the native GLB stays on the earlier task — fetch it with + `tripo_task_status` on that task instead of paying for another conversion. + Call `tripo_usage` with all workflow task IDs and report actual total and + per-task charges; if the ledger is unavailable, say the amount is pending. ## 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. +Pick the chain from what the user is building; each asynchronous task must +finish before a dependent step runs. Check each tool's billing and input rules: +`tripo_rig_check` is free and rig uses the original model, not the check task. +The examples below are suggestions only; an explicitly requested compatible +model overrides the usage-based default. GLB is the native output — a +`tripo_convert` step is only worth its credits when the target needs another format. - **Game prop, mobile / WebGL / many instances** — generate with - `face_limit` ≤ 20000 (auto-selects the low-poly `P1` model) → + explicit `model: "P2"` and a confirmed `face_limit` → `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`, +- **Game hero asset, PC / console** — explicit `model: "P2"`, `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). @@ -143,13 +183,15 @@ step is only worth its credits when the target really needs another format. - **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). + (`model: "v3.0"`, or `"v2.5"` for an animal; `spec: "unity"` for Unity Humanoid) → + `tripo_animate` with the preset + family named in the `tripo_rig` result: v3.0 humanoids + `["preset:walk", "preset:idle"]`; creatures use their body-specific presets + (e.g. `preset:quadruped:walk`); explicit v1.0 humanoids alone use + `preset:biped:*`. +- **LOD chain** — generate once → one `tripo_decimate` per level, each using + the original generation task as input, not the previous LOD (`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. @@ -157,20 +199,38 @@ step is only worth its credits when the target really needs another format. 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. +- **Not a mesh** — `tripo_image_to_splat` outputs a Gaussian-splat `.splat` + scene for viewers, not an editable model; say so before running it. If the + result has no `model_url`, the file is the `model_url` entry of `output_urls`; + deliver that one. ## 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). +- **Choose the generation model explicitly**: the user's explicitly chosen model + wins over usage-based defaults. If it conflicts with required features, explain + the conflict and ask before changing model or dropping a requirement. Otherwise, + P2 is preferred for game/realtime topology (costs more credits than H/P1); + within the P series the default is P2, and P1 is used only when the user names it + or picks it for lower cost and speed. Use v3.1 for film/render/print. This is + plugin policy, not an API requirement. Confirm the model, texture options and + cost; re-confirm any paid model change. +- **PBR is opt-in.** Send `pbr: false` on every `tripo_text_to_3d`, + `tripo_image_to_3d`, `tripo_multiview_to_3d` and `tripo_texture` call unless + the user explicitly asks for PBR materials (for example "with + PBR" or "PBR materials", in any language); only then send `pbr: true`, which also forces + `texture: true`. The API turns PBR on when `pbr` is left out, so never omit + it. Detailed or high-quality textures do not mean PBR. PBR can still be added + later: when the user asks for it after a model is already generated, do not + regenerate. Call `tripo_texture` with that task as `input` and `pbr: true`: it + bills only the texture step, not the generation again, and keeps the geometry, + but the textures are regenerated, so pass the original reference image again if + there was one. Confirm that cost like any other paid step. - 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`. +- `quad: true` (v3.1 or P2) is delivered as FBX directly, so FBX needs no + `tripo_convert`; a convert with `quad: true` always outputs FBX (GLTF is + rejected). P1 does not support `quad`; if the user requests both, stop and + ask which requirement to change before creating a paid task. ## Inputs @@ -183,12 +243,15 @@ step is only worth its credits when the target really needs another format. 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 @ -H "Content-Type: application/octet-stream" ""`) - and read `file_token` from the JSON response — no CLI login involved. + and read `file_token` from the JSON response. - 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. +- Task ids chain: use a successful model task where the processing tool accepts + it. Animation requires a successful rig task, mesh completion a segment task, + and smart segmentation a file token or URL. Rig uses the original model task, + not a rig-check task. A task id only resolves under the API key that created + it; when an older task is not found, upload the local model file instead. ## Other tools @@ -197,174 +260,31 @@ step is only worth its credits when the target really needs another format. 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`). +- `tripo_mesh_edit` — experimental P2 regional regenerate (`bbox` + optional + `ref_image`); use only if the connected server lists it. ## 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. +- `tripo_balance` first when the user asks for several assets; confirm the + whole batch and its cost once before generating more than one, then call the + tools one asset at a time, and report `credits_consumed` after. +- Error `2000` means that category's concurrency pool is full and no task was + created: retry after `Retry-After` or once a running task of the same + category finishes. Error `1007` is the request rate limit: wait a few + seconds and retry the same call. Never resubmit in a loop. - 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 - -```bash -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: - -| region | console | sign-in / top-up | -| --------------------- | ------------------------------ | ------------------------------ | -| `cn` — China mainland | https://developers.tripo3d.com | +86 SMS sign-in, Alipay top-up | -| `ov` — International | https://developers.tripo3d.ai | email sign-in, Stripe top-up | - -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. - -```bash -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: - -1. Open the verification URL in a browser. -2. 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. -3. Type the one-time code into the **"Verification code"** field. -4. 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. -5. 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 - -```bash -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 ` 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 ` 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 ` sets the **parent** directory, not the artifact directory. `make` - always creates `/tripo-out/-/` underneath it, so `-o ./assets` writes - `./assets/tripo-out/-/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 --download -o ` 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 --json` each chain entry. - -## Rules that matter - -1. **`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. -2. **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. -3. **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). -4. **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. -5. **Never invent parameters.** Run `tripo docs --topic commands/make` for the full - flag list, or `tripo docs --topic common-errors` for the error table. -6. **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 --download` instead. - - --- # Capability reference -Model versions, generation/processing parameters, 2D steps, list prices, CLI -result shape and other commands: read [`references/capability.md`](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). +Model versions, generation/processing parameters, 2D steps and list prices: +read [`references/capability.md`](references/capability.md). `tripo_plan` +is advisory and requires confirmation before spend; `tripo_mesh_edit` redoes a +P2 region only when the connected server lists the experimental tool. + +Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` +combines retopology and UVs; check current pricing. Standalone +`tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 +equivalent triangles; confirm the choice and cost. See the capability reference. diff --git a/plugins/tripo-3d/skills/tripo-3d/references/capability.md b/plugins/tripo-3d/skills/tripo-3d/references/capability.md index 39fbad1f..fda1b169 100644 --- a/plugins/tripo-3d/skills/tripo-3d/references/capability.md +++ b/plugins/tripo-3d/skills/tripo-3d/references/capability.md @@ -1,88 +1,107 @@ -# Capability reference (both paths) +# Capability reference Mirrors the official API docs so the agent never has to send the user there. -Parameter names are identical on both paths: pass them as MCP tool arguments, -or as `-p key=value` (generation) / `step:key=value` (`--then`) on the CLI. -Both paths auto-fix the linkage rules below (pbr→texture, model-specific -strips, quad→FBX) and report what they changed (`notes` / warnings). +Pass these parameters as MCP tool arguments. Tools may adjust linkage rules +(pbr→texture, model-specific strips, quad→FBX) and report changes in `notes`. +Preflight explicit user requirements first: if an adjustment would remove or +change one, resolve the conflict with the user before creating a paid task. ## Models -| model | MCP `model` / CLI `--model` | use for | limits | +| model | MCP `model` | use for | limits | | --- | --- | --- | --- | -| **v3.1** (default) | `v3.1` / `tripo-v3.1` | high fidelity: PC/console, film, print | full parameter set | -| **P1** | `P1` / `tripo-p1` | clean low-poly: mobile, UGC, ~2 s mesh | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality`; adds `export_uv` | -| **P2** | `P2` / `tripo-p2` → wire `P2-20260801` | **Preview**: P1 upgrade, low-poly **with quads** or a bigger budget | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; ~5× the P1 price. Never auto-selected on the CLI — needs `--model tripo-p2` | -| v3.0, v2.5 | `v3.0` / `tripo-v3.0`, `v2.5` / `tripo-v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality` | - -Auto-selection: low-poly words in the prompt (low poly, voxel, 低模, 手游, -像素风) or **any `face_limit` ≤ 20000** pick P1; MCP picks P2 instead when -`quad: true` is also set (the CLI never auto-selects P2); everything else is -v3.1. CLI aliases (`tripo-p2`, `tripo-v3.1`…) are sent as dated wire values -(`P2-20260801`, `v3.1-20260211`); the API rejects the alias itself with 1004. +| **v3.1** (default) | `v3.1` | high fidelity: film, render, print | full parameter set | +| **P1** | `P1` | P series alternative, only when the user names it or picks it for lower cost and speed | `face_limit` 50–20000; no `quad`, `smart_low_poly`, `generate_parts`, `geometry_quality` | +| **P2** | `P2` → wire `P2-20260801` | default P-series model, preferred for game/realtime topology, with explicit user confirmation | `face_limit` 48–50000 tri / 48–25000 quad; supports `quad`, still no `smart_low_poly`, `generate_parts`, `geometry_quality`; costs more credits than H/P1, and price depends on texture options; confirm the estimate. Pass the generation model explicitly | +| v3.0, v2.5 | `v3.0`, `v2.5` | legacy, only when the user asks | v2.5 has no `geometry_quality`, `quad`, `smart_low_poly`, `generate_parts`, `auto_size`, `compress` (stripped with a note) | + +Website model names map to these rows: H3.1 → `v3.1`, P1.0 → `P1`, P2.0 → `P2`. + +Selection policy: the explicitly requested model wins over use-based defaults; +resolve incompatible requirements with the user before any paid call. Otherwise, +explicitly choose P2 for game/realtime topology; within the P series the default +is P2, and P1 is used only when the user names it or picks it for lower cost and +speed; v3.1 for film/render/print. +This is plugin guidance, not an API requirement. Do not rely on implicit routing +or infer a generation model from face_limit. Confirm the model, texture options +and estimated cost before a billed call; re-confirm any paid model change. +Short names resolve to dated wire values (P2-20260801, v3.1-20260211). `tripo-turbo` and `tripo-v2.0` appear in older docs but the server rejects them. ## Generation parameters -Apply to `tripo_text_to_3d` / `tripo_image_to_3d` / `tripo_multiview_to_3d` -and to `tripo make` / `tripo generate *-to-model`. +Apply to `tripo_text_to_3d` / `tripo_image_to_3d` / `tripo_multiview_to_3d`. | param | default | notes | | --- | --- | --- | | `prompt`, `negative_prompt` | – | text input only; ≤1024 / ≤255 chars | -| `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 | -| `texture`, `pbr` | `true`, `true` | `pbr=true` forces `texture=true`. `texture=false pbr=false` = bare geometry, no texture credits | -| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`); CLI local validation still rejects it with exit 2 — do not pass it until the CLI accepts it | -| `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5-20260815` (newest), `v3.0-20250812` (default for v3.x and P-series), `v2.5-20250123` (default for v2.5). All generation models incl. P1/P2 | -| `delight` | `true` | v3.5 textures only (`texture_version=v3.5-20260815`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | +| `face_limit` | adaptive | upper bound on triangles. v3.1 any; P1 50–20000; P2 48–50000 (48–25000 with `quad`) | +| `texture`, `pbr` | `true`, see notes | **send `pbr: false` unless the user explicitly asks for PBR** (the API itself defaults it to true); `pbr: true` forces `texture: true`. `texture: false, pbr: false` = bare geometry, no texture credits | +| `texture_quality` | `standard` | `standard` / `detailed` (HD, +10 credits) / `extreme` (8K, +20). API also has `fast` (v3.5 textures only; same price/size as `standard`): it needs `texture_version: "v3.5"` (`v3.5-20260815`), which the tool picks when `texture_version` is omitted; other texture versions are incompatible | +| `texture_version` | derived from `model` | pins the texture model independently of geometry: `v3.5` (`v3.5-20260815`, newest), `v3.0` (`v3.0-20250812`, default for v3.x and P-series), `v2.5` (`v2.5-20250123`, default for v2.5). Pass the short name. All generation models incl. P1/P2 | +| `delight` | `true` | v3.5 textures only (`texture_version: "v3.5"`): remove baked-in lighting from the reference image; `false` keeps original shading. Older texture versions ignore it | | `geometry_quality` | `standard` | `detailed` = Ultra geometry, finer detail up to 2M faces (+20). v3.x only | -| `quad` | `false` | quad mesh (+5); **delivered as FBX** — quads cannot be stored in GLB. v3.x and P2 | +| `quad` | `false` | quad mesh (+5 on v3.1, none on P2); **delivered as FBX** — quads cannot be stored in GLB. v3.x and P2 | | `smart_low_poly` | `false` | hand-modelled-style low-poly topology (+10); requires `face_limit` 500–20000 tri / 500–10000 quad. v3.x only | -| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture=false pbr=false` (both paths flip them and warn — re-texture afterwards with `tripo_texture` / `--then texture`); `quad` is ignored; `smart_low_poly` wins and suppresses parts. v3.x only | +| `generate_parts` | `false` | editable segmented parts (+20). Requires `texture: false, pbr: false` (the tool flips them and notes it — re-texture afterwards with `tripo_texture`); `quad` is ignored; `smart_low_poly: true` with it is rejected (upstream it would win and produce no parts) — choose one. v3.x only | | `auto_size` | `false` | scale the model to real-world metres (AR, engines) | | `compress` | – | `geometry` = meshopt-compressed output. v3.x only | -| `model_seed`, `texture_seed`, `image_seed` | random | reproducibility: same seed → same geometry / textures / text-to-image stage. Keep `model_seed`, vary `texture_seed` to re-texture the same shape. CLI `--seed` sets `model_seed` | +| `model_seed`, `texture_seed`, `image_seed` | random | reproducibility: same seed → same geometry / textures / text-to-image stage. Keep `model_seed`, vary `texture_seed` to re-texture the same shape | | `enable_image_autofix` | `false` | image input: repair a low-quality / blurry / cropped photo first (slower) | | `texture_alignment` | `original_image` | image/multiview: `original_image` matches the picture, `geometry` matches the mesh | | `orientation` | `default` | image/multiview: `align_image` faces the model like the input viewpoint | -| `export_uv` | `true` | P series only: `false` skips UV unwrap (faster, smaller file; UVs are created when texturing) | -| `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 | +| `export_uv` | `true` | `false` skips UV unwrap (faster, smaller file; UVs are created when texturing) | +| `export_orientation` | `+x` | forward axis `+x` `-x` `+y` `-y`. **Only for output that is not processed further**: 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 `tripo_convert` instead | Multiview (2–4 images): `front` is mandatory and at least two views are needed; -`left`/`back`/`right` are optional. MCP takes them as named arguments (or +`left`/`back`/`right` are optional. Pass them as named arguments (or `multiview_task_id` for a finished `tripo_image_to_multiview` / -`tripo_edit_multiview` sheet); the CLI reads `front|back|left|right` from the -filenames, otherwise positional order front, left, back, right. +`tripo_edit_multiview` sheet). + + +## Retopology and UV workflows + +`tripo_decimate` defaults to v2.0. Explicit `model: "v3.0"` supports +`smart_uv: true` in the same task. Check current pricing and confirm any +model/cost change before submitting. With any other model, `smart_uv: true` is rejected and no +task is created. v2.0/v3.0 targets: 500–20000 triangles or 500–10000 quads. +The face budget is a target, not a ceiling. The combined task has no UV preview. + +Standalone `tripo_smart_uv` is separately billed: re-unwrap UVs and remap existing +textures, rigging and animation. Input must be at most 80,000 equivalent triangles +(one quad counts as two); decimate larger meshes first. `bake` defaults true; +false keeps geometry + UVs only. Optional `export_orientation` and `compress` +follow the exposed schema. Its `output_urls.uv_render_url` is a UV-layout preview, +not the model download; show it when requested. Do not substitute this separate +paid task for integrated smart_uv without confirming the extra cost. ## Processing steps -Every step takes a model task_id, a `file_token` or a model URL as `input`, -except: `tripo_animate` / `retarget` (a successful rig task), `tripo_mesh_complete` -/ `complete` (a successful segment task) and `tripo_smart_segment` / -`smartsegment` (file_token or URL only, never a task_id). CLI `--then` maps a -bare value to the primary argument (`convert:fbx`, `decimate:5000`). +Most mesh processing tools accept a model task_id, a `file_token` or a model URL +as `input`. Check each tool's schema; for example: `tripo_animate` (`task_id` of a successful rig task), +`tripo_mesh_complete` (`task_id` of a successful segment task) and +`tripo_smart_segment` (file_token or URL only, never a task_id). -| MCP tool / CLI step | arguments and constraints | +| MCP tool | arguments and constraints | | --- | --- | -| `tripo_texture` / `texture` | `texture_quality` `standard`/`detailed`/`extreme`; `pbr` (true); `texture_seed`; `texture_alignment`; `model` `v3.0` / `v3.0-20250812` (default) / `v3.5-20260815` (newest; unlocks `delight` and `texture_quality=fast` on MCP) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. MCP also takes guidance — exactly one of `prompt` (+ optional `style_image`), `image`, or `images` (4 views front/left/back/right). Re-textures any model, including imported files | -| `tripo_mesh_edit` | P2 Preview regional regenerate: `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | -| `tripo_plan` | Free draft of the tool chain **before** any billed call; show the user and wait for confirmation. Skip only for pure reads (balance / usage / task status) | -| `tripo_convert` / `convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `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`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. Any non-default option bills the complex tier (10 credits instead of 5) | -| `tripo_import_model` / `import` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`). `tripo make ` runs it implicitly | -| `tripo_rig_check` / `rig-check` | free. GLB input. Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | -| `tripo_rig` / `rig` | `rig_type` one of the seven above (default `biped`; take it from rig-check); `spec` `tripo`/`mixamo` (Mixamo = Unity Humanoid-compatible skeleton); `out_format` `glb`/`fbx`; `model` — `v1.0` humanoid rig (biped only, 90+ `preset:biped:*` clips) / `v2.5` creature rig (the other six body types, 16 universal presets). MCP picks it from `rig_type` when unset (`biped` → v1.0, otherwise v2.5) and reports the choice plus the matching preset family in the result; CLI `rig:model=rig-v1.0` / `rig-v2.0` (CLI default is still v2.0 for every body type — pass `rig:model=rig-v1.0` for humanoids) | -| `tripo_animate` / `retarget` | needs a rig task. MCP `animations: [...]` (≤5, billed per clip); CLI one clip per `--then retarget:preset:walk`, several via `tripo anim retarget --animation preset:idle preset:walk`. `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `bake_animation` (true, glb only), `export_with_geometry` (true) | -| `tripo_segment` / `segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). MCP switches to v2.0 automatically when a v2-only argument is set | -| `tripo_mesh_complete` / `complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | -| `tripo_decimate` / `decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad=true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | -| `tripo_smart_segment` / `smartsegment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `segment`, it is an end-to-end pipeline | - -Animation presets depend on the rig model of the upstream rig task — on MCP -read it from the `tripo_rig` result (a `biped` rig is v1.0 unless `model` was -set). v2.5 rig (creature body types): `preset:idle` `preset:walk` `preset:run` `preset:dive` +| `tripo_texture` | `texture_quality` `standard`/`detailed`/`extreme`/`fast` (fast requires v3.5); `pbr` (send `false` unless the user explicitly asks for PBR); `texture_seed`; `texture_alignment`; `model` as the short name: `v3.0` (`v3.0-20250812`, default) / `v3.5` (`v3.5-20260815`, newest; unlocks `delight` and `texture_quality: "fast"`, picked automatically for them when `model` is omitted) / `v2.5`; `bake`; `part_names` (segmented models); `compress`. Guidance — select one of `prompt` (+ optional `style_image`), `image`, `images` (4 views front/left/back/right), or native `texture_prompt`; native `texture_prompt` cannot be combined with the shortcut fields. Provide guidance for imported meshes; it may be omitted for Tripo-generated models. Re-supply the original reference image when re-texturing a model made from one. Re-textures any model, including imported files | +| `tripo_mesh_edit` | Experimental P2 regional regenerate: use only when listed by the connected server. `input` (task_id / file_token / URL) + axis-aligned `bbox` in model space; optional `ref_image`. Rest of mesh kept. Billed separately | +| `tripo_plan` | Free advisory draft **before** any billed call. Pass structured `generation` only for `tripo_text_to_3d`, `tripo_image_to_3d` and `tripo_multiview_to_3d`; text-to-3D requires its exact prompt. Do not add `generation` to other steps such as `tripo_image_to_splat`. Review `dry_run` only for these three when their connected schemas expose it; validate other steps against their own schemas. Free-text `params` alone leave the model unresolved. Show billed steps and estimates or `not_estimated`, then wait for explicit confirmation; not a quote or budget lock. Skip only for pure reads | +| `tripo_convert` | `format` `GLTF` `USDZ` `FBX` `OBJ` `STL` `3MF` (3MF = single-colour print). Mesh: `quad`, `force_symmetry` (quad only), `face_limit` (default: keep), `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`, `auto_size`, `with_animation` (true), `animate_in_place`, `part_names`, `export_orientation`, `fbx_preset` `blender`/`3dsmax`/`mixamo` (FBX only). `quad` with `GLTF` is rejected. A non-default `quad`, `flatten_bottom`/`flatten_bottom_threshold`, `texture_size`, `texture_format`, `pivot_to_center_bottom` or `scale_factor`, or any `face_limit`, bills the complex tier (10 credits instead of 5); the other options do not | +| `tripo_import_model` | GLB/GLTF/FBX/OBJ/STL ≤150 MB via `file_token` or URL (`.gltf` only as a URL — upload `.glb`) | +| `tripo_rig_check` | free. Input: successful model task ID, `file_token`, or public model URL; documented file formats are GLB, FBX, OBJ and STL (up to 150 MB). Result: `riggable` and recommended `rig_type`: `biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`. Gate step — not riggable → stop; riggable → rig the **original model task**, not the check task | +| `tripo_rig` | `model`: always pass it by body type: `v3.0` (`v3.0-20260909`) for `biped` and `others`, `v2.5` (`v2.5-20260210`, the official animal rig) for `quadruped`/`hexapod`/`octopod`/`avian`/`serpentine`/`aquatic`. When it is omitted the MCP sends v3.0 for every body type, and the API's own default is `v1.0-20240301`, which rigs bipeds only. v3.0 is required for `others` and the `actorcore`/`unity`/`unreal`/`vrm` specs. Both take `preset:walk` / `preset:idle` on bipeds and body-type clips on creatures. Explicit `v1.0-20240301` (`v1.0`) is legacy biped-only for 90+ `preset:biped:*` clips. Read the returned model before animation. `rig_type` comes from rig-check; rig the original model, not the check task. `spec` is biped-only; `out_format` is `glb`/`fbx`. | +| `tripo_animate` | needs a rig task. `animations: [...]` (≤5, billed per clip). `out_format` `glb`/`fbx`, `animate_in_place` (no root motion — game code drives movement), `export_with_geometry` (true); `bake_animation` is deprecated — do not pass it (it is ignored) | +| `tripo_segment` | `model` `v1.0-20250506` (geometry-based, default) or `v2.0-20260430` (semantic, beta) with `segmentation_granularity` `simple`/`balanced`/`detailed`, `split_by_connectivity` (true), `ref_image` (overrides the other two). The tool switches to v2.0 automatically when a v2-only argument is set without `model`; an explicit `v1.0-20250506` with any of them is rejected and no task is created | +| `tripo_mesh_complete` | needs a segment task. `completion_mode` `ai_completion` (default) / `quick_cap` (hole fill, cheaper); `part_names` (default all) | +| `tripo_decimate` | `face_limit` target 500–20000 tri / 500–10000 with `quad: true` (docs quote 1000–20000); `bake` (true) bakes textures onto the low-poly; `part_names`. `model: "v1.0"` accepts up to 2 000 000 tri / 150 000 quad but requires `face_limit` and has no `bake`/`part_names`. The budget is a target, not a ceiling | +| `tripo_smart_segment` | file_token/URL only. `seg_type` `model` (existing **GLB only**, 55 credits; default) or `image` (photo → auto-model → parts, 85); `granularity` `coarse`/`medium`/`fine`; `hint` describing the parts to find. Output: part labels, a PNG mask, the segmented GLB and the inner task ids. Unlike `tripo_segment`, it is an end-to-end pipeline | + +Animation presets depend on the rig model of the upstream rig task — read it +from the `tripo_rig` result (this skill passes v3.0 for bipeds and v2.5 for animal body types). v3.0 and v2.5 biped rigs: `preset:idle` `preset:walk` `preset:run` `preset:dive` `preset:climb` `preset:jump` `preset:slash` `preset:shoot` `preset:hurt` -`preset:fall` `preset:turn`, plus `preset:quadruped:walk` `preset:hexapod:walk` -`preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march`. v1.0 rig +`preset:fall` `preset:turn`; creature rigs take only their body type's clip: `preset:quadruped:walk` `preset:hexapod:walk` +`preset:octopod:walk` `preset:serpentine:march` `preset:aquatic:march` (avian and others have none). v1.0 rig (biped only, 90+ clips as `preset:biped:`): `idle` `walk` `run` `jump` `sit` `swim`, `dance_01`…`dance_06`, `greet_01`…`greet_04`, `wave_goodbye_01`, `clap` `bow` `cry` `laugh_01`, `angry_01`…, `box_01`…`box_03`, `front_kick_01`, @@ -90,63 +109,103 @@ set). v2.5 rig (creature body types): `preset:idle` `preset:walk` `preset:run` ` ## 2D steps before 3D -MCP: `tripo_generate_image` (text→image when no `input`; edit/fusion with `input` +`tripo_generate_image` (text→image when no `input`; edit/fusion with `input` or `inputs`), `tripo_image_to_multiview`, `tripo_edit_multiview`, -`tripo_image_to_splat`. CLI: `tripo generate text-to-image|image-to-image| -image-to-multiview|edit-multiview|image-to-splat`. An image task_id is a valid -`input` for `tripo_image_to_3d` — no re-upload. - -- **Templates** (`template`): `t_pose` (the pre-step for rigging), `3d_enhance` - (clean a photo before image-to-3D; image mode only), `character_completion`, - `asset_extraction` (text mode only), `variants`, `figure`. The CLI also - accepts `head_extraction`, `print_clay` and the shortcuts `t_pose=true`, - `sketch_to_render=true` via `-p`. Image editing needs `prompt` and/or - `template`; negative prompts go inside `prompt` after `--no`. +`tripo_image_to_splat`. An image task_id is a valid `input` for +`tripo_image_to_3d` — no re-upload. + +- **Templates** (`template`): choose from the documented endpoint whitelist: + - Text-to-image templates: `asset_extraction`, `character_completion`, `t_pose`, `variants`, `figure`. + - Image-to-image templates: `t_pose`, `character_completion`, `3d_enhance`, `variants`, `figure`. + - `head_extraction` and `print_clay` are not in the documented endpoint whitelists, + and the `template` argument does not accept them; do not recommend them as + supported templates. + - Image editing requires `prompt` and/or `template`; text-to-image requires a + prompt. Negative prompts go inside `prompt` after `--no`. - **Image models** (`model`): `seedream_v4` (text-to-image default; **not accepted by image editing**), `seedream_v5` (editing default), Google Gemini as `banana` (= gemini-2.5-flash, fast), `banana_pro` (= gemini-3-pro, quality), - `banana2` (= gemini-3.1-flash, latest fast) — MCP may take these `banana*` - names; the CLI takes either — and OpenAI `chat_image_2`, + `banana2` (= gemini-3.1-flash, latest fast) — pass these `banana*` names — + and OpenAI `chat_image_2`, `chat_image_2.5_flare` (faster), `chat_image_2.5_sunburst` (edits keep - untouched regions closer to the original). `chat_image_1` retires 2026-10-23 - and `chat_image_1.5` on 2026-12-01: pick `chat_image_2` or a 2.5 model. + untouched regions closer to the original). `chat_image_1` is retired (2026-10-23) + and `chat_image_1.5` retires on 2026-12-01. Before retirement it remains + available where supported; respect a user's explicit selection. After retirement + explain alternatives such as `chat_image_2` or a 2.5 model and confirm any + replacement or changed cost; never silently substitute a paid model. GPT-image options: `quality` `low`/`medium`/`high` (`chat_image_2`; 2.5 also `xhigh`/`max`; omitted = `low`); `background` `auto`/`opaque`/`transparent` - (2.5 only; `transparent` needs `output_format=png`). The CLI still rejects - `texture_quality=fast` locally; MCP accepts `fast` only with texture model v3.5. + (2.5 only; `transparent` needs `output_format: "png"`). - **Several references** (`inputs`): seedream ≤4, gemini ≤10, chat_image ≤16; - refer to them in the prompt as `[image 1]`, `[image 2]`. -- `size` `1K`/`2K`/`4K` or `WxH` (default 2048×2048; billed by tier); - `aspect_ratio` is honoured by the gemini (`banana*`) family only; `watermark` - by seedream only; `output_format` `png`/`jpeg`. -- `image-to-multiview` → a 4-view sheet (front/left/back/right); `edit-multiview` - takes that task plus 1–4 `{view, prompt}` edits; either task feeds - `tripo_multiview_to_3d` (`multiview_task_id`). -- `image-to-splat` returns a Gaussian-splat file (30 credits, ~4 min): no - texture, rig or convert downstream — use image-to-3D when a mesh is needed. - Input PNG/JPEG/WebP ≤20 MB, ≥256×256 px, subject clear and centred. + refer to them in the prompt as `image[1]`, `image[2]`. +### Image size by model -## Prices +Each model accepts its own explicit `size` values: -Approximate list prices, so the cost can be quoted before a run (the -authoritative number is `credits_consumed` on the result; `balance` and -`credits_consumed` are decimals, not integers): +| model | accepted explicit size | +| --- | --- | +| `banana` | Fixed pixel whitelist only: `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672` | +| `banana2` | Tiers only: `0.5K`, `1K`, `2K`, `4K`; no explicit pixels | +| `banana_pro` | `1K`, `2K`, `4K`, or positive-integer `WxH` | +| `seedream_v4` | `2K`, `4K`, or positive-integer `WxH` with width/height in [1/16, 16]; text-to-image only | +| `seedream_v5` | `2K`, `3K`, or positive-integer `WxH` with width/height in [1/16, 16] | +| `chat_image_1.5` | `1024x1024`, `1024x1536`, `1536x1024`, `auto`; observe the retirement date above | +| `chat_image_2` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | +| `chat_image_2.5_flare` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | +| `chat_image_2.5_sunburst` | `auto` or positive-integer `WxH`: each edge ≤3840 and divisible by 16; long edge ≤3 × short edge; total pixels 655360–8294400 inclusive | + +Do not apply one size/default to every model. Official model-specific docs list +Seedream defaults as 2048x2048, banana_pro/banana2 as 2K, chat_image_1.5 as auto, +and chat_image_2/2.5 as 2048x2048. For banana, omission behavior is unverified: +the docs also print 2048x2048 as a default despite the fixed-size whitelist. +Prefer an explicit whitelisted size; do not pass that inconsistent default as an +explicit `size`. +Seedream exact pixel-count limits unverified: official ranges are rounded +(v4 approximately 3.69–16.78 MP; v5 approximately 3.69–10.40 MP). Do not invent +exact server pixel thresholds from those figures. Schema acceptance is not proof +of server acceptance; server validation still applies, including banana_pro +custom pixel sizes. Chat example: 1536x864 is valid, 1080x1920 is not divisible +by 16; use 1088x1920 instead. No 1K/2K/4K tiers for chat_image models. + +`aspect_ratio` is honoured by the banana family only; Seedream/chat use size. +`watermark` control is Seedream-only; `output_format` is `png`/`jpeg`. + +### Other image steps +- `tripo_image_to_multiview` → a 4-view sheet (front/left/back/right); + `tripo_edit_multiview` takes that task plus 1–4 `{view, prompt}` edits; either + task feeds `tripo_multiview_to_3d` (`multiview_task_id`). +- `tripo_image_to_splat` returns a Gaussian-splat file (30 credits, ~4 min): no + texture, rig or convert downstream — use `tripo_image_to_3d` when a mesh is + needed. Input PNG/JPEG/WebP ≤20 MB, ≥256×256 px, subject clear and centred. + +## Prices -| operation | credits | +Official list prices from the Tripo pricing pages (developers.tripo3d.com/zh/pricing +and developers.tripo3d.ai/pricing; the same numbers in both regions), checked on +2026-10-30. Numeric prices and add-ons anywhere in this file (including processing +tables) come from those pages. An estimate must name its source, region and date and +match the exact model/options. If this table cannot price the request (a legacy model +or anything not listed), report **not_estimated** (unestimated), not zero; disclose +that uncertainty and obtain consent before billing. Never infer a fixed P2/P1 ratio. +Afterwards use the usage ledger and task `credits_consumed` for actual spending; +`balance` and `credits_consumed` are decimals, not integers: + +| operation | official list credits | | --- | --- | | text-to-3D, v3.1 | 10 bare / 20 textured | | image- or multiview-to-3D, v3.1 | 20 bare / 30 textured | | text-to-3D, P1 | 30 bare / 40 textured (P2: 100 / 110) | | image- or multiview-to-3D, P1 | 40 bare / 50 textured (P2: 100 / 110) | -| add-ons per generation | `texture_quality=detailed` +10, `extreme` +20, `geometry_quality=detailed` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 | -| texture step | 10 standard / 20 detailed / 30 extreme | -| convert | 5, or 10 with any non-default option | -| decimate | 30 (v2.0) / 10 (v1.0) | -| segment / complete | 40 / 50 (`quick_cap` 30) | -| smartsegment | 85 image / 55 model | -| rig-check / rig / animate | free / 25 / 10 per clip | -| text-to-image, image editing | 5 (seedream, banana 1K, chat_image_1) – 20 (banana_pro 4K) by model and size tier | -| image-to-multiview / edit-multiview / image-to-splat | 10 / 5 per edited view / 30 | +| add-ons per generation | `texture_quality: "detailed"` +10, `"extreme"` +20; v3.1 only: `geometry_quality: "detailed"` +20, `quad` +5, `smart_low_poly` +10, `generate_parts` +20 (P2 `quad` has no surcharge) | +| `tripo_texture` | 10 standard / 20 detailed / 30 extreme | +| `tripo_convert` | 5, or 10 with a complex-tier option (see the convert row) | +| `tripo_decimate` | Check current pricing for the selected model and options; mark not_estimated if unavailable | +| `tripo_smart_uv` | 20 | +| `tripo_segment` / `tripo_mesh_complete` | 40 / 50 (`quick_cap` 30) | +| `tripo_smart_segment` | 85 image / 55 model | +| `tripo_rig_check` / `tripo_rig` / `tripo_animate` | free / 25 / 10 per clip | +| `tripo_generate_image` | 5 (seedream, banana 1K) – 20 (banana_pro 4K) by model and size tier; GPT image `quality` `high` / `xhigh` / `max` 20–50 | +| `tripo_image_to_multiview` / `tripo_edit_multiview` / `tripo_image_to_splat` | 10 / 5 per edited view / 30 | Credits are frozen at submission and released on failure, ban or cancellation — failed tasks are never charged. Task states: `queued` → `running` (with @@ -160,59 +219,8 @@ Every generation costs credits from the user's account, and `credits_consumed` i reported on each result. - Confirm the request before generating more than one asset in a batch. -- Run `tripo balance` first when the user asks for several assets, and report the - cost back after finishing. -- For 3D printing and other untextured output, add `-p texture=false -p pbr=false` +- Call `tripo_balance` first when the user asks for several assets, and report + the cost back after finishing. +- For 3D printing and other untextured output, pass `texture: false, pbr: false` — it skips texture credits entirely. - Do not silently re-roll a disappointing result. Show the user the preview and ask. - -## Result shape - -```json -{ - "task_id": "...", - "type": "convert_model", - "status": "success", - "credits_consumed": 25, - "credits_breakdown": [ - { "task_id": "", "type": "text_to_model", "credits_consumed": 20 }, - { "task_id": "", "type": "convert_model", "credits_consumed": 5 } - ], - "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" }] -} -``` - -`model_file` and `preview` describe the **final** chain step. After a convert -step the native GLB and `preview.png` live on the earlier generation task — -fetch them free with `tripo task get --download` instead of -paying for another conversion. - -## Presenting the finished asset - -Every file is already on the user's disk when `tripo make` exits — never offer -a "download". Do not render the model file as a clickable link either: the chat -UI opens local-file links in a preview pane that cannot display binary meshes, -so the link just looks broken when clicked. Instead: - -- show `preview.png` — images render fine; -- give the model's location as a plain path in backticks; -- offer the next real action: reveal it in the file manager (`open -R ` - on macOS, `explorer /select,` on Windows) or wire it into the project. - -## Other commands - -| command | purpose | -| -------------------------------- | ------------------------------------ | -| `tripo task get --download` | fetch or re-download an earlier task | -| `tripo balance` / `tripo usage` | credits remaining / recent spend | -| `tripo redo [@last]` | same request, new seed | -| `tripo files upload ` | get a `file_token` for an image | -| `tripo batch run manifest.yaml` | bulk jobs, resumable | -| `tripo docs --topic ` | full docs for any command or recipe | - -Download URLs returned by the API expire in about five minutes — never cache one. -Re-run `tripo task get --download` instead. diff --git a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md index 4f070060..803c728c 100644 --- a/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md +++ b/plugins/tripo-3d/skills/tripo-game-asset/SKILL.md @@ -1,122 +1,144 @@ --- name: tripo-game-asset -description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, PBR hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. 中文触发词:游戏资产、游戏素材、游戏模型、低模道具、面数预算、LOD、角色绑骨、走跑跳动画、Unity/Unreal/Godot 模型导入。 +description: Recipes for producing game-ready 3D assets with Tripo and wiring them into a game project - low-poly props on a face budget, detailed hero assets, LOD chains, and rigged characters with locomotion clips for Unity, Unreal, Godot or Three.js. Use when the user is building a game or real-time 3D scene and needs props, characters, placeholder art, LODs, or an animated rig, rather than a single one-off model. Also covers walk/run/jump clips and importing models into Unity, Unreal or Godot, whatever language the request is in. --- # Game asset pipeline -Recipes on top of the `tripo-3d` skill. Read that skill first — it explains how -to pick the execution path (MCP tools vs `tripo-cli`), authorization, blocking -behaviour, exit codes, and credit rules. - -The recipes below are written as CLI commands because game work happens in a -project tree where a shell exists and assets should land next to the code. -The same pipelines map onto the MCP tools when the user prefers them: -`tripo_text_to_3d`/`tripo_image_to_3d` with `face_limit` for budgeted props, -`tripo_rig` (`spec: "mixamo"`) + `tripo_animate` for characters (humanoid rigs -take `preset:biped:*` clips, creature rigs the plain `preset:walk` family — the -`tripo_rig` result says which), `tripo_convert` -for FBX/texture-size export, `tripo_decimate` per LOD level, and -`tripo_upload_ticket` → `tripo_import_model` for a mesh the project already has — -then download the fresh result URL into the project. Only `tripo batch` (bulk, -resumable) genuinely requires the CLI; say so instead of improvising. +Recipes on top of the `tripo-3d` skill. Read that skill first — it covers +authorization, the `tripo_task_wait` loop (call again while +`queued`/`running`), credit rules and the full parameter reference. Every +recipe runs through the Tripo MCP tools only. Wait for every asynchronous task +before its dependent step; billing and inputs vary: `tripo_rig_check` is free, +and rig uses the original model task rather than the check task. Each +`tripo_text_to_3d`, `tripo_image_to_3d`, `tripo_multiview_to_3d` and +`tripo_texture` call sends `pbr: false` unless the user explicitly asks for PBR. The point of these recipes is that assets land in the project's own directory -structure. Always pass `-o` pointing at wherever the project keeps its art — but note -`-o` is the parent: the files end up in `/tripo-out/-/`, so move them -to their final location afterwards if the user named a specific path. +structure: after each final step download the file with +`curl -L -o /. ""` (links expire after about +2 hours — fetch fresh ones with `tripo_task_status` if needed) and report the +local path. ## Pick a budget first -| target | preset | what it does | -| ----------------------------- | ------------------- | ----------------------------------------------------- | -| mobile, WebGL, many instances | `--for game-mobile` | P1 low-poly model, face_limit 15000, 2K textures, FBX | -| PC / console hero asset | `--for game-pc` | v3.1, detailed PBR | -| animated character | `--for anim` | rig-check, then rig, then retarget | - -Two budget-related choices the presets do not make for you: - -- **Quads at low poly** — P1 rejects `quad`; use `--model tripo-p2` (wire - `P2-20260801`, **Preview**; face_limit 48–25000 quads, ~5× the P1 price, - output is FBX) or v3.1 with `-p smart_low_poly=true -p quad=true` - (face_limit 500–10000). On MCP pass `model: "P2"` / `quad: true`. -- **v3.1 quality under a face cap** — any `face_limit` ≤ 20000 auto-selects P1, - so add `--model tripo-v3.1` (MCP `model: "v3.1"`) when the user wants v3.1 - geometry with a budget. - -Override the face budget when the project has a stricter one: - -```bash -tripo make "a health potion bottle" --for game-mobile \ - -p face_limit=3000 --then convert:format=FBX,texture_size=1024 \ - -o ./Assets/Art/Props --json --yes -``` +An explicitly requested model takes priority over these recipes. If it cannot +support a requested feature, explain the conflict and ask before changing the +model or dropping the feature. Otherwise, explicitly choose P2 for game/realtime +topology; within the P series the default is P2, and P1 is used only when the +user names it or picks it for lower cost and speed; v3.1 for film/render/print. +Confirm the selected model, texture options and estimated or unestimated cost; +re-confirm any paid model change. The example calls below use defaults only. + +| target | generation call | export | +| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------- | +| mobile, WebGL, many instances | explicit `model: "P2"`, `face_limit: 15000` | `tripo_convert` `format: "FBX"`, `texture_size: 2048` | +| PC / console hero asset | explicit `model: "P2"`, `texture_quality: "detailed"` | FBX only if the engine needs it; GLB is native | +| animated character | T-pose model → `tripo_rig_check` → `tripo_rig` → `tripo_animate` | `out_format: "fbx"` for Unity/Unreal | + +Two budget-related choices the defaults do not make for you: + +- **Quads at low poly** — P1 does not support `quad`. If the user requested both, + ask which to change before submitting; otherwise use `model: "P2", quad: true` + (face_limit 48–25000 quads, price depends on texture options; + confirm the estimate, output is FBX) or v3.1 with + `smart_low_poly: true, quad: true` (face_limit 500–10000). +- **v3.1 quality under a face cap** — explicitly set `model: "v3.1"` when the + user wants v3.1 geometry with a budget. + +Override the face budget when the project has a stricter one, e.g. +`tripo_text_to_3d` `{ model: "P2", prompt: "a health potion bottle", face_limit: 3000, pbr: false }` → +`tripo_convert` `{ format: "FBX", texture_size: 1024 }`. ## Props -```bash -tripo make "an ornate treasure chest, fantasy style" --for game-pc \ - -o ./assets/models --json --yes -``` +`tripo_text_to_3d` `{ model: "P2", prompt: "an ornate treasure chest, fantasy style", texture_quality: "detailed", pbr: false }` +→ download the GLB (or → `tripo_convert` `{ format: "FBX" }` for Unity/Unreal). -For a set of props, generate them one at a time and check each `preview.png` before -continuing — a bad seed early is cheaper to catch than at the end of a batch. For -genuinely large sets use `tripo batch run manifest.yaml`, which is resumable. +For a set of props, generate them one at a time and check each +result before continuing — a bad seed early is cheaper to catch +than at the end of a batch. Confirm the total cost of the whole set with the +user first (`tripo_plan`, `tripo_balance`), then call the tools one asset at a +time, and use `tripo_task_list` to check the status of many task ids in one +call. ## LOD chain from one source -```bash -tripo make "a stone golem" --for game-pc --then decimate:5000 --json --yes -tripo make @last --then decimate:1500,convert:fbx --json --yes -``` +Generate once, then one `tripo_decimate` per level — each with the **original +generation task** as `input`, not the previous LOD: -`decimate` bakes normals by default, so the low LODs keep the silhouette detail of -the source. Each `@last` continues from the previous task rather than regenerating. +`tripo_text_to_3d` `{ model: "P2", prompt: "a stone golem", pbr: false }` (LOD0) +→ `tripo_decimate` `{ input: , face_limit: 5000 }` (LOD1) +→ `tripo_decimate` `{ input: , face_limit: 1500 }` (LOD2) +→ `tripo_convert` `{ input: , format: "FBX" }` if the engine needs FBX. -**`decimate`'s face budget is a target, not a ceiling** — a 1500-face request can come -back at ~1900 triangles. Read the actual triangle count from the result before handing -an LOD to a project with a hard budget, and reduce it locally if it overshoots. -Generation's own `face_limit` does hold as an upper bound, so this caveat is specific -to `decimate`. +`tripo_decimate` bakes textures by default (`bake: true`), so the low LODs keep +the silhouette detail of the source. -## Characters with animation +**`tripo_decimate`'s face budget is a target, not a ceiling** — a 1500-face +request can come back at ~1900 triangles. Read the actual triangle count from +the result before handing an LOD to a project with a hard budget, and reduce it +locally if it overshoots. Generation's own `face_limit` does hold as an upper +bound, so this caveat is specific to decimation. -```bash -tripo make "a knight in full armor, T-pose, standing straight" --for anim --json --yes -``` +For a budget above 20000 faces use `tripo_decimate` `model: "v1.0"` with an +explicit `face_limit` (up to 2 000 000, no bake). `model: "v3.0"` is the newest +retopology and the only one that takes `smart_uv: true` (see the end of this +skill). -`--for anim` runs `rig-check` first, which gates the chain: if the mesh is not -riggable it stops before spending rigging credits. - -Explicit control over the rig and clips: - -```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 -``` +## Characters with animation -- Prompt for a **T-pose** — rigging quality depends heavily on it. -- `--spec mixamo` produces a Unity Humanoid-compatible skeleton. -- `--animate-in-place` for locomotion clips driven by game code rather than root motion. -- Retarget is billed per animation and accepts at most five. -- To animate a mesh the project already has: - `tripo make hero.glb --then rig-check,rig,retarget:preset:walk --json --yes` +1. **T-pose source.** Prompt for it (`"a knight in full armor, T-pose, standing straight"`) + or turn a character image into one with `tripo_generate_image` + `{ input: , template: "t_pose" }` — rigging quality depends heavily on it. +2. `tripo_text_to_3d` / `tripo_image_to_3d` with explicit `model: "P2"` → the + character model task. +3. `tripo_rig_check` `{ input: }` — free. It gates the chain: not + riggable → stop before spending rigging credits. Read the recommended + `rig_type` (`biped` `quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`). +4. `tripo_rig` `{ input: , model: "v3.0", rig_type: , spec: "mixamo", out_format: "fbx" }` + — rig the **original model task**, not the check task. `spec: "mixamo"` + gives Mixamo bone names (`"unity"` for Unity Humanoid, `"unreal"` for the UE + Mannequin); `spec` applies to `biped` + only, so drop it for the other body types (the tool rejects it). Pass + `model: "v3.0"` for `biped` and `model: "v2.5"` for the animal types + (`quadruped` `hexapod` `octopod` `avian` `serpentine` `aquatic`): the API's + own default, v1.0, rigs bipeds only. The result names the preset family to + use next. +5. `tripo_animate` `{ task_id: , animations: [...], out_format: "fbx", animate_in_place: true }` + — at most five clips, billed per clip. Explicit legacy v1.0 rigs take + `preset:biped:idle` `preset:biped:walk` `preset:biped:run` `preset:biped:jump` + plus emotes, dances and sports clips (`preset:biped:dance_01`, + `preset:biped:wave_goodbye_01`, …); v3.0 and v2.5 biped rigs take `preset:idle` + `preset:walk` `preset:run` `preset:jump` `preset:fall` `preset:turn` + `preset:climb` `preset:dive` `preset:slash` `preset:shoot` `preset:hurt`; + creature rigs take only their body-type clip (`preset:quadruped:walk`, …; + avian has none). `animate_in_place: true` + for locomotion driven by game code rather than root motion. + +To animate a mesh the project already has: `tripo_upload_ticket` +`{ kind: "model", format: "glb" }` → run the returned curl to upload the file → +`tripo_import_model` `{ input: }` → continue from step 3. ## Format notes -- **Three.js / web**: GLB. `--for ar-web` adds the web-oriented defaults. -- **Unity / Unreal**: FBX via `--then convert:fbx`, or `--for game-mobile` which - already converts. -- Quads (`-p quad=true`) force FBX — glTF cannot store them, so `convert:glb` - combined with quads is rejected. +- **Three.js / web**: GLB as generated; `auto_size: true` for real-world scale. +- **Unity / Unreal**: FBX via `tripo_convert` `{ format: "FBX" }` + (`fbx_preset: "mixamo"` for a Unity-Humanoid-oriented export of rigged models). +- Quads (`quad: true`) force FBX — glTF cannot store them, so `tripo_convert` + `format: "GLTF"` combined with quads is rejected. - `texture_size` is set on the convert step, not at generation: - `--then convert:format=FBX,texture_size=2048`. + `tripo_convert` `{ format: "FBX", texture_size: 2048 }`. ## Wiring into the project -After a successful run, `model_file` in the result JSON is the path to import. Do the -integration work the user actually asked for — add the loader call, register the -prefab, update the asset manifest — rather than stopping at "the file is generated". -Check `preview.png` first so a wrong asset does not get wired in. +After a successful chain, download the final `model_url` into the project's +art directory and use that path for the import. Do the integration work the +user actually asked for — add the loader call, register the prefab, update the +asset manifest — rather than stopping at "the file is generated". Check the +preview first so a wrong asset does not get wired in. + +Retopology: `tripo_decimate` with explicit `model: "v3.0", smart_uv: true` +combines retopology and UVs; check current pricing. Standalone +`tripo_smart_uv` is a separate billed UV-layout task for inputs up to 80,000 +equivalent triangles; confirm the choice and cost. See the capability reference.