# Table of Contents - [Introduction — Tripo Developers](#introduction-tripo-developers) - [Quick Start — Tripo Developers](#quick-start-tripo-developers) - [Authentication — Tripo Developers](#authentication-tripo-developers) - [Changelog — Tripo Developers](#changelog-tripo-developers) - [Plugins — Tripo Developers](#plugins-tripo-developers) - [SDK Integration — Tripo Developers](#sdk-integration-tripo-developers) - [ComfyUI Nodes — Tripo Developers](#comfyui-nodes-tripo-developers) - [Tripo CLI — Tripo Developers](#tripo-cli-tripo-developers) - [Codex Plugin — Tripo Developers](#codex-plugin-tripo-developers) - [Task Lifecycle — Tripo Developers](#task-lifecycle-tripo-developers) - [Billing — Tripo Developers](#billing-tripo-developers) - [Text to 3D Model — P Series — Tripo Developers](#text-to-3d-model-p-series-tripo-developers) - [Text to 3D Model — H Series — Tripo Developers](#text-to-3d-model-h-series-tripo-developers) - [Models & Versions — Tripo Developers](#models-versions-tripo-developers) - [Image to 3D Model — H Series — Tripo Developers](#image-to-3d-model-h-series-tripo-developers) - [Image to 3D Model — P Series — Tripo Developers](#image-to-3d-model-p-series-tripo-developers) - [Multiview to 3D Model — H Series — Tripo Developers](#multiview-to-3d-model-h-series-tripo-developers) - [Multiview to 3D Model — P Series — Tripo Developers](#multiview-to-3d-model-p-series-tripo-developers) - [Text to Image — Tripo Developers](#text-to-image-tripo-developers) - [Image to Image — Tripo Developers](#image-to-image-tripo-developers) - [Image to Multiview — Tripo Developers](#image-to-multiview-tripo-developers) - [Edit Multiview — Tripo Developers](#edit-multiview-tripo-developers) - [Texture — Tripo Developers](#texture-tripo-developers) - [Segmentation — Tripo Developers](#segmentation-tripo-developers) - [Mesh Complete — Tripo Developers](#mesh-complete-tripo-developers) - [Retopology — Tripo Developers](#retopology-tripo-developers) - [Convert Format — Tripo Developers](#convert-format-tripo-developers) - [Rig Check — Tripo Developers](#rig-check-tripo-developers) - [Animation Retarget — Tripo Developers](#animation-retarget-tripo-developers) - [Auto Rig — Tripo Developers](#auto-rig-tripo-developers) - [Batch Task Query — Tripo Developers](#batch-task-query-tripo-developers) - [Rate Limits — Tripo Developers](#rate-limits-tripo-developers) - [Error Handling — Tripo Developers](#error-handling-tripo-developers) - [Webhooks — Tripo Developers](#webhooks-tripo-developers) - [Account — Tripo Developers](#account-tripo-developers) - [Task Query — Tripo Developers](#task-query-tripo-developers) - [File Upload — Tripo Developers](#file-upload-tripo-developers) - [Import Model — Tripo Developers](#import-model-tripo-developers) - [v2 to v3 Migration — Tripo Developers](#v2-to-v3-migration-tripo-developers) - [File Upload (Large Files) — Tripo Developers](#file-upload-large-files-tripo-developers) - [Tripo Developers — AI 3D Generation API](#tripo-developers-ai-3d-generation-api) - [Documentation — Tripo Developers](#documentation-tripo-developers) - [Text to 3D Model — Tripo Developers](#text-to-3d-model-tripo-developers) - [Multiview to 3D Model — Tripo Developers](#multiview-to-3d-model-tripo-developers) - [Image to 3D Model — Tripo Developers](#image-to-3d-model-tripo-developers) --- # Introduction — Tripo Developers Introduction to the Tripo API ============================= CopyDownload PDF \# Introduction to the Tripo API Tripo3D is an AI-powered 3D generation platform that provides text-to-3D, image-to-3D, rigging, mesh editing, and other capabilities. With the Tripo API, developers can integrate high-quality 3D content generation into their own products. > If you are accessing from China, please visit the China site: \[developers.tripo3d.com\](https://developers.tripo3d.com) ## Base URL \`\`\`baseurl https://openapi.tripo3d.ai/v3 \`\`\` ## Authentication All API requests must include an API Key in the request header: \`\`\`apikey Authorization: Bearer {api\_key} \`\`\` You can create and manage API Keys in the \[Tripo Console\](/en/keys). ## Unified Response Format ### Success Response \`\`\`json { "code": 0, "data": { ... } } \`\`\` ### Error Response \`\`\`json { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account" } \`\`\` ### Common Fields | Parameter | Type | Description | | :-: | :-: | :-: | | code | integer | Status code. \`0\` indicates success, and any non-\`0\` value indicates an error | | data | object | Business data, returned only on success | | message | string | Error description, returned only on failure | | suggestion | string | Suggested fix, returned only on failure | ## Asynchronous Task Pattern Most generation APIs use an asynchronous task pattern: 1. \*\*Create a task\*\* - Send a POST request to create a task and receive a \`task\_id\` 2. \*\*Poll for results\*\* - Use \`GET /v3/tasks/{task\_id}\` to query the task status and result \`\`\` POST /v3/generation/text-to-model -> {"code": 0, "data": {"task\_id": "task\_abc123"}} | v GET /v3/tasks/task\_abc123 -> {"code": 0, "data": {"status": "running", "progress": 50}} | v GET /v3/tasks/task\_abc123 -> {"code": 0, "data": {"status": "success", "output": {...}}} \`\`\` ### Task Statuses | Status | Description | | :-: | :-: | | \`queued\` | Queued | | \`running\` | Running | | \`success\` | Succeeded | | \`failed\` | Failed | | \`cancelled\` | Cancelled | ## API Version Current version: \*\*v3\*\* ## Endpoint Overview ### 3D Model Generation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/generation/text-to-model\`\](/en/docs/generation-text-to-model) | Generate a 3D model from text | | \[\`POST /v3/generation/image-to-model\`\](/en/docs/generation-image-to-model) | Generate a 3D model from an image | | \[\`POST /v3/generation/multiview-to-model\`\](/en/docs/generation-multiview-to-model) | Generate a 3D model from multiview images | ### Image Generation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/generation/text-to-image\`\](/en/docs/generation-text-to-image) | Generate an image from text | | \[\`POST /v3/generation/image-to-image\`\](/en/docs/generation-image-to-image) | Transform an image style | | \[\`POST /v3/generation/image-to-multiview\`\](/en/docs/generation-image-to-multiview) | Generate multiview images | | \[\`POST /v3/generation/edit-multiview\`\](/en/docs/generation-edit-multiview) | Edit multiview images | ### Model Processing | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/models/texture\`\](/en/docs/models-texture) | Texture a model | | \[\`POST /v3/models/convert\`\](/en/docs/models-convert) | Convert model format | | \[\`POST /v3/mesh/segment\`\](/en/docs/mesh-segment) | Semantic segmentation | | \[\`POST /v3/mesh/complete\`\](/en/docs/mesh-complete) | Mesh completion | | \[\`POST /v3/mesh/decimate\`\](/en/docs/mesh-decimate) | Retopology | ### Animation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/animations/rig-check\`\](/en/docs/animations-rig-check) | Check rigging compatibility | | \[\`POST /v3/animations/rig\`\](/en/docs/animations-rig) | Rig a model | | \[\`POST /v3/animations/retarget\`\](/en/docs/animations-retarget) | Retarget an animation | ### Task Management | Endpoint | Description | | :-: | :-: | | \[\`GET /v3/tasks/{task\_id}\`\](/en/docs/task-query) | Query a task | | \[\`POST /v3/tasks/list\`\](/en/docs/task-batch-query) | Query tasks in batch | ### File Management | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/files\`\](/en/docs/files) | Upload a file | ### Account | Endpoint | Description | | :-: | :-: | | \[\`GET /v3/account/balance\`\](/en/docs/account) | Query account balance | Introduction to the Tripo API ============================= Tripo3D is an AI-powered 3D generation platform that provides text-to-3D, image-to-3D, rigging, mesh editing, and other capabilities. With the Tripo API, developers can integrate high-quality 3D content generation into their own products. > If you are accessing from China, please visit the China site: [developers.tripo3d.com](https://developers.tripo3d.com/) Base URL -------- `https://openapi.tripo3d.ai/v3` Authentication -------------- All API requests must include an API Key in the request header: `Authorization: Bearer {api_key}` You can create and manage API Keys in the [Tripo Console](https://developers.tripo3d.ai/en/keys) . Unified Response Format ----------------------- ### Success Response JSONCopy { "code": 0, "data": { ... } } ### Error Response JSONCopy { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account" } ### Common Fields | Parameter | Type | Description | | --- | --- | --- | | code | integer | Status code. `0` indicates success, and any non-`0` value indicates an error | | data | object | Business data, returned only on success | | message | string | Error description, returned only on failure | | suggestion | string | Suggested fix, returned only on failure | Asynchronous Task Pattern ------------------------- Most generation APIs use an asynchronous task pattern: 1. **Create a task** - Send a POST request to create a task and receive a `task_id` 2. **Poll for results** - Use `GET /v3/tasks/{task_id}` to query the task status and result Copy POST /v3/generation/text-to-model -> {"code": 0, "data": {"task_id": "task_abc123"}} | v GET /v3/tasks/task_abc123 -> {"code": 0, "data": {"status": "running", "progress": 50}} | v GET /v3/tasks/task_abc123 -> {"code": 0, "data": {"status": "success", "output": {...}}} ### Task Statuses | Status | Description | | --- | --- | | `queued` | Queued | | `running` | Running | | `success` | Succeeded | | `failed` | Failed | | `cancelled` | Cancelled | API Version ----------- Current version: **v3** Endpoint Overview ----------------- ### 3D Model Generation | Endpoint | Description | | --- | --- | | [`POST /v3/generation/text-to-model`](https://developers.tripo3d.ai/en/docs/generation-text-to-model) | Generate a 3D model from text | | [`POST /v3/generation/image-to-model`](https://developers.tripo3d.ai/en/docs/generation-image-to-model) | Generate a 3D model from an image | | [`POST /v3/generation/multiview-to-model`](https://developers.tripo3d.ai/en/docs/generation-multiview-to-model) | Generate a 3D model from multiview images | ### Image Generation | Endpoint | Description | | --- | --- | | [`POST /v3/generation/text-to-image`](https://developers.tripo3d.ai/en/docs/generation-text-to-image) | Generate an image from text | | [`POST /v3/generation/image-to-image`](https://developers.tripo3d.ai/en/docs/generation-image-to-image) | Transform an image style | | [`POST /v3/generation/image-to-multiview`](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) | Generate multiview images | | [`POST /v3/generation/edit-multiview`](https://developers.tripo3d.ai/en/docs/generation-edit-multiview) | Edit multiview images | ### Model Processing | Endpoint | Description | | --- | --- | | [`POST /v3/models/texture`](https://developers.tripo3d.ai/en/docs/models-texture) | Texture a model | | [`POST /v3/models/convert`](https://developers.tripo3d.ai/en/docs/models-convert) | Convert model format | | [`POST /v3/mesh/segment`](https://developers.tripo3d.ai/en/docs/mesh-segment) | Semantic segmentation | | [`POST /v3/mesh/complete`](https://developers.tripo3d.ai/en/docs/mesh-complete) | Mesh completion | | [`POST /v3/mesh/decimate`](https://developers.tripo3d.ai/en/docs/mesh-decimate) | Retopology | ### Animation | Endpoint | Description | | --- | --- | | [`POST /v3/animations/rig-check`](https://developers.tripo3d.ai/en/docs/animations-rig-check) | Check rigging compatibility | | [`POST /v3/animations/rig`](https://developers.tripo3d.ai/en/docs/animations-rig) | Rig a model | | [`POST /v3/animations/retarget`](https://developers.tripo3d.ai/en/docs/animations-retarget) | Retarget an animation | ### Task Management | Endpoint | Description | | --- | --- | | [`GET /v3/tasks/{task_id}`](https://developers.tripo3d.ai/en/docs/task-query) | Query a task | | [`POST /v3/tasks/list`](https://developers.tripo3d.ai/en/docs/task-batch-query) | Query tasks in batch | ### File Management | Endpoint | Description | | --- | --- | | [`POST /v3/files`](https://developers.tripo3d.ai/en/docs/files) | Upload a file | ### Account | Endpoint | Description | | --- | --- | | [`GET /v3/account/balance`](https://developers.tripo3d.ai/en/docs/account) | Query account balance | NextQuick Start On this page --- # Quick Start — Tripo Developers Quick Start =========== CopyDownload PDF \# Quick Start Get started with the Tripo API in 15 minutes and generate your first 3D model from scratch. ## 1. Get an API Key Go to the \[Tripo Console\](https://platform.tripo3d.ai), create an account, and open the "API Keys" page to create an API Key. ## 2. Send Your First Request Generate a 3D model from a text description: ### curl \`\`\`bash curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer {api\_key}" \\ -d '{ "prompt": "a cute cat", "model": "tripo-v3.1" }' \`\`\` Success response: \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ## 3. Query the Task Result 3D generation runs as an asynchronous task. Use the returned \`task\_id\` to poll the task status: \`\`\`bash curl -X GET https://openapi.tripo3d.ai/v3/tasks/task\_abc123 \\ -H "Authorization: Bearer {api\_key}" \`\`\` When \`status\` is \`success\`, the task is complete: \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://...", "rendered\_image\_url": "https://..." } } } \`\`\` ## 4. Download the Model Download the GLB 3D model file from \`output.model\_url\` in the response. You can use it directly in tools such as Blender, Unity, and Three.js. ## Complete Example ### Python \`\`\`python import time import requests API\_KEY = "your\_api\_key\_here" BASE\_URL = "https://openapi.tripo3d.ai/v3" headers = { "Content-Type": "application/json", "Authorization": f"Bearer {API\_KEY}" } # 1. Create a text-to-3D task response = requests.post( f"{BASE\_URL}/generation/text-to-model", headers=headers, json={ "prompt": "a cute cat", "model": "tripo-v3.1" } ) task\_id = response.json()\["data"\]\["task\_id"\] print(f"Task created: {task\_id}") # 2. Poll until the task is complete while True: response = requests.get( f"{BASE\_URL}/tasks/{task\_id}", headers={"Authorization": f"Bearer {API\_KEY}"} ) task = response.json()\["data"\] status = task\["status"\] progress = task.get("progress", 0) print(f"Status: {status}, progress: {progress}%") if status == "success": model\_url = task\["output"\]\["model\_url"\] print(f"Model download URL: {model\_url}") break elif status in ("failed", "cancelled", "banned"): print(f"Task failed: {status}") break time.sleep(2) # 3. Download the model file if status == "success": model\_data = requests.get(model\_url) with open("model.glb", "wb") as f: f.write(model\_data.content) print("Model saved as model.glb") \`\`\` ### JavaScript \`\`\`javascript const API\_KEY = "your\_api\_key\_here"; const BASE\_URL = "https://openapi.tripo3d.ai/v3"; async function generateModel() { // 1. Create a text-to-3D task const createResponse = await fetch(\`${BASE\_URL}/generation/text-to-model\`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": \`Bearer ${API\_KEY}\` }, body: JSON.stringify({ prompt: "a cute cat", model: "tripo-v3.1" }) }); const { data: { task\_id } } = await createResponse.json(); console.log(\`Task created: ${task\_id}\`); // 2. Poll until the task is complete while (true) { const pollResponse = await fetch(\`${BASE\_URL}/tasks/${task\_id}\`, { headers: { "Authorization": \`Bearer ${API\_KEY}\` } }); const { data: task } = await pollResponse.json(); const { status, progress = 0 } = task; console.log(\`Status: ${status}, progress: ${progress}%\`); if (status === "success") { console.log(\`Model download URL: ${task.output.model\_url}\`); return task.output; } if (\["failed", "cancelled", "banned"\].includes(status)) { throw new Error(\`Task failed: ${status}\`); } await new Promise(resolve => setTimeout(resolve, 2000)); } } generateModel().catch(console.error); \`\`\` Get started with the Tripo API in 15 minutes and generate your first 3D model. 1 Get an API Key -------------- Go to the [API Keys](https://developers.tripo3d.ai/en/keys) page, create a new key, and copy it. Store it securely — it is shown only once. Security tip: Store your API key in an environment variable (export TRIPO\_API\_KEY="sk-..."). Never hard-code it in source code or commit it to repositories. 2 Send Your First Request ----------------------- Generate a 3D model from a text description. All generation APIs are asynchronous — the response returns a task\_id immediately. cURLPythonJavaScript Copy curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "prompt": "a cute cat", "model": "v3.1-20260211" }' 200Response — 200 OK { "code": 0, "data": { "task_id": "task_abc123" } } 3 Query the Task Result --------------------- Use task\_id to poll until status: "success". Poll every 2 seconds. Typical generation takes 10–120 seconds. cURLPythonJavaScript Copy curl -X GET https://openapi.tripo3d.ai/v3/tasks/{task_id} \ -H "Authorization: Bearer " 200Response — Task Complete { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://...", "rendered_image_url": "https://..." } } } 4 Download the Model ------------------ Download the GLB 3D model file from output.model\_url in the response. You can use it directly in: BlenderUnityUnreal EngineThree.jsBabylon.jsmodel-viewer Note: Model URLs expire after 5 minutes. Download immediately after the task succeeds. Use output.model\_url for the 3D model file. Advanced Workflows ------------------ Explore complete API pipelines for specific use cases and features. By ScenarioBy Feature #### Game-Ready Character Generate a low-poly character with skeleton and animations, ready for Unity/Unreal. #### High-Fidelity Asset Generate the highest quality PBR model for product visualization or cinematic rendering. #### 3D Printing Generate a pure geometry mesh without textures, export as STL for slicing and printing. #### Animated Scene Create characters with different animations for game levels or short films. #### E-commerce Product Turn a product photo into an interactive 3D model for web AR try-on or product pages. #### Multiview Pipeline Use multiple reference views for the most accurate 3D reconstruction. Game-Ready Character -------------------- Generate a low-poly character with skeleton and animations, ready for Unity/Unreal. ### Call Sequence Your App Tripo API 1POSTimage-to-model task\_id POLLGET tasks/{task\_id} → until success 2POSTrig-check riggable: true, rig\_type: "biped" 3POSTrig New task\_id for rigged model POLLGET tasks/{task\_id} → until success 4POSTretarget task\_id with animated model URLs POLLGET tasks/{task\_id} → until success ### API Data Flow POST image-to-model POST rig-check POST rig POST retarget 1 #### POST /v3/generation/image-to-model Input Image URL or file\_token Output task\_id Poll GET /v3/tasks/{task\_id} until status=success 2 #### POST /v3/animations/rig-check Input { input: "task\_abc123" } Output riggable: true, rig\_type: "biped" If riggable=true, pass task\_id + rig\_type to rig 3 #### POST /v3/animations/rig Input { input: "task\_abc123", rig\_type: "biped" } Output New task\_id for rigged model Poll until success, pass rigged task\_id to retarget 4 #### POST /v3/animations/retarget Input { input: "task\_rig456", animations: \[...\] } Output task\_id with animated model URLs Download output.model\_urls ### Key Parameters | Parameter | Value | Why | | --- | --- | --- | | `model` | `P1-20260311` | Best low-poly topology for game assets | | `face_limit` | `5000` | Mobile/game-friendly polygon count | | `texture` | `true` | Visual fidelity for characters | | `rig_type` | `biped` | Humanoid skeleton for character | | `spec` | `mixamo` | Compatible with Unity/Unreal import | | `animations` | `preset:walk``preset:idle``preset:run` | Essential locomotion set | Estimated Time ~105s Cost (Credits) ~85 cURLPythonJavaScript Copy import requests, time HEADERS = {"Authorization": "Bearer ", "Content-Type": "application/json"} def poll(task_id): while True: r = requests.get(f"https://openapi.tripo3d.ai/v3/tasks/{task_id}", headers=HEADERS).json() if r["data"]["status"] == "success": return r["data"] if r["data"]["status"] in ("failed","cancelled"): raise Exception(r["data"]) time.sleep(2) # Step 1 — Generate model task_id = requests.post("https://openapi.tripo3d.ai/v3/generation/image-to-model", headers=HEADERS, json={"file_token":"","model":"P1-20260311","face_limit":5000} ).json()["data"]["task_id"] poll(task_id) # Step 2 — Rig check rig_type = requests.post("https://openapi.tripo3d.ai/v3/animations/rig-check", headers=HEADERS, json={"input": task_id}).json()["data"]["rig_type"] # Step 3 — Rig rig_id = requests.post("https://openapi.tripo3d.ai/v3/animations/rig", headers=HEADERS, json={"input":task_id,"rig_type":rig_type,"spec":"mixamo"} ).json()["data"]["task_id"] poll(rig_id) # Step 4 — Retarget animations anim_id = requests.post("https://openapi.tripo3d.ai/v3/animations/retarget", headers=HEADERS, json={"input":rig_id,"animations":["preset:walk","preset:idle","preset:run"]} ).json()["data"]["task_id"] result = poll(anim_id) print("Animated GLBs:", result["output"]["model_urls"]) ### Developer Tips * •Always call rig-check before rig — it returns the recommended rig\_type and prevents failures * •Poll tasks every 2 seconds; do not exceed 1 request/second to avoid rate limits * •Use spec: "mixamo" for Unity/Unreal; use spec: "tripo" for custom pipelines ### Common Pitfalls * •If rig-check returns riggable=false, try regenerating with a cleaner prompt (avoid complex poses) * •Retarget only accepts rigged model task\_ids — passing a raw generation task\_id will fail PreviousIntroductionNextAuthentication --- # Authentication — Tripo Developers Authentication ============== CopyDownload PDF \# Authentication All Tripo API requests must include an API Key in the HTTP request header for authentication. ## Authentication Method Add the \`Authorization\` field to the request header, with the value \`Bearer {api\_key}\`: \`\`\` Authorization: Bearer {api\_key} \`\`\` ## Get an API Key 1. Log in to the \[Tripo Console\](https://platform.tripo3d.ai) 2. Open the "API Keys" page 3. Click "Create Key" to generate a new API Key 4. Copy and store it securely. It is shown only once after creation ## Request Examples ### curl \`\`\`bash curl -X GET https://openapi.tripo3d.ai/v3/account/balance \\ -H "Authorization: Bearer YOUR\_API\_KEY" \`\`\` ### Python \`\`\`python import requests headers = { "Authorization": "Bearer YOUR\_API\_KEY" } response = requests.get( "https://openapi.tripo3d.ai/v3/account/balance", headers=headers ) print(response.json()) \`\`\` ### JavaScript \`\`\`javascript const response = await fetch("https://openapi.tripo3d.ai/v3/account/balance", { headers: { "Authorization": "Bearer YOUR\_API\_KEY" } }); const data = await response.json(); console.log(data); \`\`\` ## Security Recommendations - \*\*Store API Keys in environment variables\*\*. Do not hard-code them in source code - \*\*Do not commit API Keys to code repositories\*\*. Add \`.env\` files to \`.gitignore\` - \*\*Do not use API Keys directly in frontend applications\*\*. Proxy requests through your backend service - \*\*Rotate keys regularly\*\*. If you suspect a leak, delete the key in the console immediately and create a new one \`\`\`bash # Recommended: read the API Key from an environment variable export TRIPO\_API\_KEY="your\_api\_key\_here" \`\`\` \`\`\`python import os api\_key = os.environ\["TRIPO\_API\_KEY"\] \`\`\` \`\`\`javascript const apiKey = process.env.TRIPO\_API\_KEY; \`\`\` Authentication ============== All Tripo API requests must include an API Key in the HTTP request header for authentication. Authentication Method --------------------- Add the `Authorization` field to the request header, with the value `Bearer {api_key}`: Copy Authorization: Bearer {api_key} Get an API Key -------------- 1. Log in to the [Tripo Console](https://platform.tripo3d.ai/) 2. Open the “API Keys” page 3. Click “Create Key” to generate a new API Key 4. Copy and store it securely. It is shown only once after creation Request Examples ---------------- cURLPythonJavaScript Copy curl -X GET https://openapi.tripo3d.ai/v3/account/balance \ -H "Authorization: Bearer YOUR_API_KEY" import requests headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get( "https://openapi.tripo3d.ai/v3/account/balance", headers=headers ) print(response.json()) const response = await fetch("https://openapi.tripo3d.ai/v3/account/balance", { headers: { "Authorization": "Bearer YOUR_API_KEY" } }); const data = await response.json(); console.log(data); Security Recommendations ------------------------ * **Store API Keys in environment variables**. Do not hard-code them in source code * **Do not commit API Keys to code repositories**. Add `.env` files to `.gitignore` * **Do not use API Keys directly in frontend applications**. Proxy requests through your backend service * **Rotate keys regularly**. If you suspect a leak, delete the key in the console immediately and create a new one BashCopy # Recommended: read the API Key from an environment variable export TRIPO_API_KEY="your_api_key_here" PythonCopy import os api_key = os.environ["TRIPO_API_KEY"] JavaScriptCopy const apiKey = process.env.TRIPO_API_KEY; PreviousQuick StartNextChangelog On this page --- # Changelog — Tripo Developers Changelog ========= CopyDownload PDF \# Changelog ## Texture model v3.5-20260815 (2026-09) A new texture model, reachable from two entry points: - \*\*\`POST /v3/models/texture\`\*\*: \`model\` now accepts \`v3.5-20260815\`. The default is still \`v3.0-20250812\`, so requests that omit the field are unchanged. - \*\*Generation endpoints\*\* (\`text-to-model\`, \`image-to-model\`, \`multiview-to-model\`, including P1 / P2): new \`texture\_version\` pins the texture model independently of the geometry \`model\`. Supported values are \`v3.5-20260815\`, \`v3.0-20250812\`, and \`v2.5-20250123\`; if omitted it is derived from the geometry version (v2.5 geometry → \`v2.5-20250123\`, otherwise \`v3.0-20250812\`). Two new parameters ship with it, \*\*both effective only on v3.5 textures\*\*: - \*\*\`texture\_quality=fast\`\*\*: a new quality tier — the fastest generation, trading texture detail for speed. \*\*Output texture size and credit cost are both identical to \`standard\`\*\*; only the level of detail is lower. Requesting it on any other texture version returns \`1004\` instead of silently downgrading to \`standard\`. - \*\*\`delight\`\*\* (boolean, default \`true\`): removes baked-in lighting from the reference image before texturing; set \`false\` to keep the original shading. Older texture versions ignore it. ## GPT Image 2.5, quality tiers and transparent backgrounds (2026-09) \`POST /v3/generation/text-to-image\` and \`POST /v3/generation/image-to-image\` now accept two new models, the GPT Image 2/2.5 family gains a \`quality\` parameter, and the two 2.5 models gain a \`background\` parameter. - \*\*New models\*\*: \`chat\_image\_2.5\_flare\` and \`chat\_image\_2.5\_sunburst\`. They cost the same and differ in trade-off — flare is noticeably faster, sunburst preserves the untouched parts of an edited image more closely. - \*\*\`quality\`\*\*: accepted only by \`chat\_image\_2\` (\`low\`, \`medium\`, \`high\`) and the two 2.5 models (additionally \`xhigh\`, \`max\`). Omitting it is equivalent to \`low\` — note this differs from OpenAI's own default of \`auto\`, which is not supported here. \`high\`/\`xhigh\`/\`max\` cost extra credits; see the Pricing page. - \*\*\`background\`\*\*: \`auto\`, \`opaque\` or \`transparent\`, supported by the two 2.5 models only. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so existing requests keep working unchanged. - \*\*\`transparent\` requires \`output\_format=png\`\*\*: JPEG carries no alpha channel, so that combination returns an error instead of silently flattening the transparency. - \*\*Custom sizes\*\*: \`chat\_image\_2\` and the 2.5 models accept any \`WIDTHxHEIGHT\` where each edge is at most 3840 and a multiple of 16, the long edge is at most 3x the short edge, and total pixels fall between 655,360 and 8,294,400. The previous presets continue to work. - \*\*Retirement\*\*: \`chat\_image\_1\` will be retired on \*\*2026-10-23\*\* and \`chat\_image\_1.5\` on \*\*2026-12-01\*\*. Migrate to \`chat\_image\_2\` or the 2.5 models before those dates. ## P2 series model (2026-08) \`POST /v3/generation/text-to-model\`, \`image-to-model\`, and \`multiview-to-model\` now accept \`model=P2-20260801\` (an upgrade of P1). - \*\*P2-only parameters\*\*: \`quad\` (quad mesh). Sending \`quad=true\` with P1 returns \`400\`; switch to P2 or remove the field. - \*\*\`face\_limit\`\*\*: triangle 48–50,000; with \`quad=true\`, 48–25,000. Omitted = adaptive. - \*\*Credits\*\*: 100 without texture; \`standard\` / \`detailed\` / \`extreme\` = 110 / 120 / 130 (same texture add-ons as P1). - \*\*P1\*\* (\`P1-20260311\`) remains available; P1 does not support \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, or \`geometry\_quality\`. ## Documentation correction (2026-08) \`credits\_consumed\`, \`balance\`, and \`frozen\` are JSON \*\*numbers\*\* with up to two decimal places (e.g. \`48.00\`, \`41465.00\`). Parse them as floating-point or decimal values — \*\*do not\*\* use integer parsing (\`int\`, \`parseInt\`, etc.), which will fail or truncate fractional credits (e.g. VIP discounts). ## v3.0 (2026-04) ### New API Architecture - \*\*Dedicated endpoints replace the universal POST endpoint\*\*: Capability-specific endpoints, such as \`POST /v3/generation/text-to-model\`, replace the previous universal \`POST /v2/openapi/task\` endpoint with a \`type\` field - \*\*Unified \`{input}-to-{output}\` naming convention\*\*: All generation endpoints use intuitive names such as \`text-to-model\`, \`image-to-multiview\`, and \`multiview-to-model\` - \*\*Unified \`input\` field\*\*: Supports automatic input source inference from \`task\_id\`, \`file\_token\`, or URL, without requiring you to manually specify the input type - \*\*Removed the redundant \`/openapi\` path\*\*: The Base URL is simplified from \`/v2/openapi/\` to \`/v3/\` - \*\*Text-to-image and image-to-image are separated into dedicated endpoints\*\*: \`text-to-image\` and \`image-to-image\` are no longer combined in a single API ### Endpoint Changes | v2 Endpoint | v3 Endpoint | | :-: | :-: | | \`POST /v2/openapi/task\` type=text\_to\_model | \`POST /v3/generation/text-to-model\` | | \`POST /v2/openapi/task\` type=image\_to\_model | \`POST /v3/generation/image-to-model\` | | \`POST /v2/openapi/task\` type=multiview\_to\_model | \`POST /v3/generation/multiview-to-model\` | | \`POST /v2/openapi/task\` type=text\_to\_image | \`POST /v3/generation/text-to-image\` | | \`POST /v2/openapi/task\` type=generate\_image | \`POST /v3/generation/image-to-image\` | | \`POST /v2/openapi/task\` type=generate\_multiview\_image | \`POST /v3/generation/image-to-multiview\` | | \`POST /v2/openapi/task\` type=edit\_multiview\_image | \`POST /v3/generation/edit-multiview\` | | \`POST /v2/openapi/task\` type=refine\_model | \`POST /v3/models/refine\` | | \`POST /v2/openapi/task\` type=convert\_model | \`POST /v3/models/convert\` | | \`POST /v2/openapi/task\` type=import\_model | \`POST /v3/models/import\` | | \`POST /v2/openapi/task\` type=stylize\_model | \`POST /v3/models/stylize\` | | \`POST /v2/openapi/task\` type=texture\_model | \`POST /v3/models/texture\` | | \`POST /v2/openapi/task\` type=animate\_prerigcheck | \`POST /v3/animations/rig-check\` | | \`POST /v2/openapi/task\` type=animate\_rig | \`POST /v3/animations/rig\` | | \`POST /v2/openapi/task\` type=animate\_retarget | \`POST /v3/animations/retarget\` | | \`POST /v2/openapi/task\` type=mesh\_segmentation | \`POST /v3/mesh/segment\` | | \`POST /v2/openapi/task\` type=mesh\_completion | \`POST /v3/mesh/complete\` | | \`POST /v2/openapi/task\` type=highpoly\_to\_lowpoly | \`POST /v3/mesh/decimate\` | | \`GET /v2/openapi/task/{task\_id}\` | \`GET /v3/tasks/{task\_id}\` | ### Field Changes | v2 Field | v3 Field | | :-: | :-: | | \`create\_time\` | \`created\_at\` | | \`consumed\_credit\` | \`credits\_consumed\` | | \`file\` / \`file\_token\` / \`url\` / \`object\` | Unified as \`input\` | ### New Capabilities - \`POST /v3/tasks/list\` - Query tasks in batch - \`POST /v3/files/upload-credentials\` - Get direct file upload credentials - \`GET /v3/account/usage\` - Query usage details Changelog ========= Texture model v3.5-20260815 (2026-09) ------------------------------------- A new texture model, reachable from two entry points: * **`POST /v3/models/texture`**: `model` now accepts `v3.5-20260815`. The default is still `v3.0-20250812`, so requests that omit the field are unchanged. * **Generation endpoints** (`text-to-model`, `image-to-model`, `multiview-to-model`, including P1 / P2): new `texture_version` pins the texture model independently of the geometry `model`. Supported values are `v3.5-20260815`, `v3.0-20250812`, and `v2.5-20250123`; if omitted it is derived from the geometry version (v2.5 geometry → `v2.5-20250123`, otherwise `v3.0-20250812`). Two new parameters ship with it, **both effective only on v3.5 textures**: * **`texture_quality=fast`**: a new quality tier — the fastest generation, trading texture detail for speed. **Output texture size and credit cost are both identical to `standard`**; only the level of detail is lower. Requesting it on any other texture version returns `1004` instead of silently downgrading to `standard`. * **`delight`** (boolean, default `true`): removes baked-in lighting from the reference image before texturing; set `false` to keep the original shading. Older texture versions ignore it. GPT Image 2.5, quality tiers and transparent backgrounds (2026-09) ------------------------------------------------------------------ `POST /v3/generation/text-to-image` and `POST /v3/generation/image-to-image` now accept two new models, the GPT Image 2/2.5 family gains a `quality` parameter, and the two 2.5 models gain a `background` parameter. * **New models**: `chat_image_2.5_flare` and `chat_image_2.5_sunburst`. They cost the same and differ in trade-off — flare is noticeably faster, sunburst preserves the untouched parts of an edited image more closely. * **`quality`**: accepted only by `chat_image_2` (`low`, `medium`, `high`) and the two 2.5 models (additionally `xhigh`, `max`). Omitting it is equivalent to `low` — note this differs from OpenAI’s own default of `auto`, which is not supported here. `high`/`xhigh`/`max` cost extra credits; see the Pricing page. * **`background`**: `auto`, `opaque` or `transparent`, supported by the two 2.5 models only. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so existing requests keep working unchanged. * **`transparent` requires `output_format=png`**: JPEG carries no alpha channel, so that combination returns an error instead of silently flattening the transparency. * **Custom sizes**: `chat_image_2` and the 2.5 models accept any `WIDTHxHEIGHT` where each edge is at most 3840 and a multiple of 16, the long edge is at most 3x the short edge, and total pixels fall between 655,360 and 8,294,400. The previous presets continue to work. * **Retirement**: `chat_image_1` will be retired on **2026-10-23** and `chat_image_1.5` on **2026-12-01**. Migrate to `chat_image_2` or the 2.5 models before those dates. P2 series model (2026-08) ------------------------- `POST /v3/generation/text-to-model`, `image-to-model`, and `multiview-to-model` now accept `model=P2-20260801` (an upgrade of P1). * **P2-only parameters**: `quad` (quad mesh). Sending `quad=true` with P1 returns `400`; switch to P2 or remove the field. * **`face_limit`**: triangle 48–50,000; with `quad=true`, 48–25,000. Omitted = adaptive. * **Credits**: 100 without texture; `standard` / `detailed` / `extreme` = 110 / 120 / 130 (same texture add-ons as P1). * **P1** (`P1-20260311`) remains available; P1 does not support `quad`, `smart_low_poly`, `generate_parts`, or `geometry_quality`. Documentation correction (2026-08) ---------------------------------- `credits_consumed`, `balance`, and `frozen` are JSON **numbers** with up to two decimal places (e.g. `48.00`, `41465.00`). Parse them as floating-point or decimal values — **do not** use integer parsing (`int`, `parseInt`, etc.), which will fail or truncate fractional credits (e.g. VIP discounts). v3.0 (2026-04) -------------- ### New API Architecture * **Dedicated endpoints replace the universal POST endpoint**: Capability-specific endpoints, such as `POST /v3/generation/text-to-model`, replace the previous universal `POST /v2/openapi/task` endpoint with a `type` field * **Unified `{input}-to-{output}` naming convention**: All generation endpoints use intuitive names such as `text-to-model`, `image-to-multiview`, and `multiview-to-model` * **Unified `input` field**: Supports automatic input source inference from `task_id`, `file_token`, or URL, without requiring you to manually specify the input type * **Removed the redundant `/openapi` path**: The Base URL is simplified from `/v2/openapi/` to `/v3/` * **Text-to-image and image-to-image are separated into dedicated endpoints**: `text-to-image` and `image-to-image` are no longer combined in a single API ### Endpoint Changes | v2 Endpoint | v3 Endpoint | | --- | --- | | `POST /v2/openapi/task` type=text\_to\_model | `POST /v3/generation/text-to-model` | | `POST /v2/openapi/task` type=image\_to\_model | `POST /v3/generation/image-to-model` | | `POST /v2/openapi/task` type=multiview\_to\_model | `POST /v3/generation/multiview-to-model` | | `POST /v2/openapi/task` type=text\_to\_image | `POST /v3/generation/text-to-image` | | `POST /v2/openapi/task` type=generate\_image | `POST /v3/generation/image-to-image` | | `POST /v2/openapi/task` type=generate\_multiview\_image | `POST /v3/generation/image-to-multiview` | | `POST /v2/openapi/task` type=edit\_multiview\_image | `POST /v3/generation/edit-multiview` | | `POST /v2/openapi/task` type=refine\_model | `POST /v3/models/refine` | | `POST /v2/openapi/task` type=convert\_model | `POST /v3/models/convert` | | `POST /v2/openapi/task` type=import\_model | `POST /v3/models/import` | | `POST /v2/openapi/task` type=stylize\_model | `POST /v3/models/stylize` | | `POST /v2/openapi/task` type=texture\_model | `POST /v3/models/texture` | | `POST /v2/openapi/task` type=animate\_prerigcheck | `POST /v3/animations/rig-check` | | `POST /v2/openapi/task` type=animate\_rig | `POST /v3/animations/rig` | | `POST /v2/openapi/task` type=animate\_retarget | `POST /v3/animations/retarget` | | `POST /v2/openapi/task` type=mesh\_segmentation | `POST /v3/mesh/segment` | | `POST /v2/openapi/task` type=mesh\_completion | `POST /v3/mesh/complete` | | `POST /v2/openapi/task` type=highpoly\_to\_lowpoly | `POST /v3/mesh/decimate` | | `GET /v2/openapi/task/{task_id}` | `GET /v3/tasks/{task_id}` | ### Field Changes | v2 Field | v3 Field | | --- | --- | | `create_time` | `created_at` | | `consumed_credit` | `credits_consumed` | | `file` / `file_token` / `url` / `object` | Unified as `input` | ### New Capabilities * `POST /v3/tasks/list` - Query tasks in batch * `POST /v3/files/upload-credentials` - Get direct file upload credentials * `GET /v3/account/usage` - Query usage details PreviousAuthenticationNextSDK Integration On this page --- # Plugins — Tripo Developers Tripo Plugins ============= CopyDownload PDF \# Tripo Plugins Use Tripo directly inside the tools where you already create 3D content. Choose the plugin for your workflow, download it, connect a Tripo API key, and generate models without leaving your editor. ## Supported plugins | Plugin | Tripo version | Compatible version | Best for | Download | | ------------- | ------------- | ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Unity | \`1.0.1\` | \`Unity 2022+\` | Generating and importing game assets | Download | | Unreal Engine | \`1.0\` | \`5.6.0\` | Editor and Blueprint workflows | Download | | Blender | \`0.7.3\` | \`3.0+\` | Generating a base model for further editing | Download | | Godot | \`0.02\` | \`4.4+\` | Editor and \`Node3D\` workflows | Download | | Cocos Creator | \`1.0.0\` | \`3.8.6+\` | Creating assets inside a Cocos project | Download | | ComfyUI | \`1.1.21\` | \`0.3.14\` | Node-based 3D generation workflows | Download | Each plugin exposes a different subset of Tripo features. The examples below describe only behavior present in the corresponding package. ## Plugin use cases ### Unity — Generate a game prop \*\*Use case.\*\* Create a placeholder or production starting point while prototyping a scene. \*\*Steps.\*\* 1. Open \`Tools > Tripo API Unity\` and configure your API key. 2. Select \*\*Image to Model\*\*, upload an image, and start generation. 3. Wait for the task to finish and let the plugin import the downloaded model into the project. For an optional local \*\*Text to Model\*\* runtime workflow, the package also exposes \`TripoRuntimeCore\`: \`\`\`csharp GetComponent() .SetAPIKey("") .SetTextPrompt("a stylized wooden treasure chest") .TextToModel(); \`\`\` \*\*Result.\*\* The generated asset is available in Unity for material setup, scene placement, or further editing. Download ### Unreal Engine — Generate through Blueprint \*\*Use case.\*\* Add model generation to an Unreal editor tool or Blueprint-driven prototype. \*\*Steps.\*\* 1. Create a text, image, or multiview generation task with the plugin's Blueprint nodes. 2. Use the callback and task-status nodes to wait for completion. 3. Pass the returned model URL to the download node. Runtime display requires the separate glTFRuntime plugin documented by the package. !\[Unreal Engine Blueprint nodes for creating, querying, and downloading Tripo models\](/assets/images/docs/plugins/unreal-blueprint.jpg) \*\*Result.\*\* The generated model can be downloaded for editor import or passed to a runtime display workflow. Download ### Blender — Generate from a reference image \*\*Use case.\*\* Produce a base mesh from an image, then continue modeling and material work in Blender. \*\*Steps.\*\* 1. Open \`View3D > Sidebar > Tripo 3D\` and connect your API key. 2. Choose image-to-model, provide the reference image, and adjust options such as face limit, texture, PBR, or quad mesh. 3. Start generation and wait for the plugin to download and import the result. \*\*Result.\*\* The GLB or FBX is imported into Blender and can be edited with the standard modeling tools. Download ### Godot — Add a generated model as Node3D \*\*Use case.\*\* Generate a 3D object in a Godot editor or local runtime workflow and add it to the scene tree. \*\*Steps.\*\* Configure the API key in the plugin, create an input and task node, then wait for the task to finish: The example below uses a text task. For an image task, upload the source with \`TripoUploadImage\` and create the model with \`TripoImageToModel\`. \`\`\`gdscript var input = TripoTextToModelInput.new() input.prompt = "a stylized wooden treasure chest" var task = TripoTextToModel.new() task.input = input add\_child(task) if await task.launch() == TripoTask.TaskError.eSuccess: add\_child(task.save\_to\_node()) \`\`\` \*\*Result.\*\* The generated model can be previewed, saved, or added to the current scene as \`Node3D\`. Download ### Cocos Creator — Save a generated project asset \*\*Use case.\*\* Create a model from text or an image without leaving Cocos Creator. \*\*Steps.\*\* 1. Open the \*\*Tripo Model Generator\*\* panel and connect your API key. 2. Select text or image input, configure generation options, and start the task. 3. Wait for the extension to download the finished model into the project. \*\*Result.\*\* The GLB or FBX is written under \`assets/resources\` and can be used by the current project. Download ### ComfyUI — Build a text-to-3D workflow \*\*Use case.\*\* Connect Tripo generation to an existing node-based image or asset pipeline. \*\*Steps.\*\* 1. Connect a text input to the Tripo model-generation node. 2. Set the API key, generation mode, model version, and output options. 3. Connect the result to the 3D preview node and run the queue. !\[ComfyUI text-to-3D workflow with a generated model preview\](/assets/images/docs/plugins/comfyui-text-to-model.jpg) \*\*Result.\*\* The model is previewed in the workflow and saved automatically under \`ComfyUI/output\`. Download ## Install and get started ### Unity 1. Download and extract the ZIP. 2. Move the extracted plugin directory containing \`package.json\` into your project's \`Packages\` directory. 3. Reopen the project and select \`Tools > Tripo API Unity\`. ### Unreal Engine 1. Download and extract the ZIP into \`Plugins/Tripo3D\` in your Unreal project. 2. Enable the plugin in the project settings. 3. Restart Unreal Editor. ### Blender 1. Open \`Edit > Preferences > Add-ons\`. 2. Choose \*\*Install from Disk\*\*, select the downloaded ZIP, and enable \*\*Tripo 3D\*\*. 3. Open the plugin from \`View3D > Sidebar > Tripo 3D\`. ### Godot 1. Extract the ZIP and copy \`addons/tripo-godot\` into the project's \`addons\` directory. 2. Open \`Project Settings > Plugins\` and enable the Tripo plugin. 3. Open the Tripo editor panel or use the provided nodes in a scene. ### Cocos Creator 1. Open \`Extension > Extension Manager\`. 2. Select \*\*Project\*\* or \*\*Global\*\*, click \`+\`, and import the downloaded ZIP. 3. Enable the extension, then open the \*\*Tripo Model Generator\*\* panel. See the \[Cocos Creator 3.8 extension installation guide\](https://docs.cocos.com/creator/3.8/manual/en/editor/extension/install.html) for the standard ZIP-import workflow. ### ComfyUI 1. Extract the ZIP into \`ComfyUI/custom\_nodes/ComfyUI-Tripo\`. 2. Install its dependencies from the ComfyUI Python environment: \`\`\`bash python -m pip install -r ComfyUI/custom\_nodes/ComfyUI-Tripo/requirements.txt \`\`\` 3. Restart ComfyUI and load or create a Tripo workflow. ## Configure an API key Create a key on the \[Tripo API Keys page\](https://platform.tripo3d.ai/api-keys), then enter it in the selected plugin before starting a task. An API key is a secret credential. Do not commit it to source control, include it in screenshots, print it in logs, or ship it inside a public client build. See \[Authentication\](/en/docs/authentication) for the general API rules. ## Related resources - \[Codex plugin\](/en/docs/codex-plugin) - \[Authentication\](/en/docs/authentication) - \[SDK integration\](/en/docs/sdk) - \[Tripo API Keys\](https://platform.tripo3d.ai/api-keys) Tripo Plugins ============= Use Tripo directly inside the tools where you already create 3D content. Choose the plugin for your workflow, download it, connect a Tripo API key, and generate models without leaving your editor. Supported plugins ----------------- | Plugin | Tripo version | Compatible version | Best for | Download | | --- | --- | --- | --- | --- | | Unity | `1.0.1` | `Unity 2022+` | Generating and importing game assets | [Download](https://assets-pub.tripo3d.ai/archive/760058ab-1128-45b7-9b11-3a0aff142fec/Tripo_API_Unity-latest.zip) | | Unreal Engine | `1.0` | `5.6.0` | Editor and Blueprint workflows | [Download](https://assets-pub.tripo3d.ai/archive/74c76766-33aa-4bb6-89cb-688f00b3c350/Tripo_API_Unreal-latest.zip) | | Blender | `0.7.3` | `3.0+` | Generating a base model for further editing | [Download](https://cdn-web.tripo3d.ai/plugin/tripo-blender.zip) | | Godot | `0.02` | `4.4+` | Editor and `Node3D` workflows | [Download](https://cdn-web.tripo3d.ai/plugin/tripo-godot.zip) | | Cocos Creator | `1.0.0` | `3.8.6+` | Creating assets inside a Cocos project | [Download](https://cdn-web.tripo3d.ai/plugin/tripo-cocos.zip) | | ComfyUI | `1.1.21` | `0.3.14` | Node-based 3D generation workflows | [Download](https://cdn-web.tripo3d.ai/plugin/tripo-comfyUI.zip) | Each plugin exposes a different subset of Tripo features. The examples below describe only behavior present in the corresponding package. Plugin use cases ---------------- ### Unity — Generate a game prop **Use case.** Create a placeholder or production starting point while prototyping a scene. **Steps.** 1. Open `Tools > Tripo API Unity` and configure your API key. 2. Select **Image to Model**, upload an image, and start generation. 3. Wait for the task to finish and let the plugin import the downloaded model into the project. For an optional local **Text to Model** runtime workflow, the package also exposes `TripoRuntimeCore`: Copy GetComponent() .SetAPIKey("") .SetTextPrompt("a stylized wooden treasure chest") .TextToModel(); **Result.** The generated asset is available in Unity for material setup, scene placement, or further editing. [Download](https://assets-pub.tripo3d.ai/archive/760058ab-1128-45b7-9b11-3a0aff142fec/Tripo_API_Unity-latest.zip) ### Unreal Engine — Generate through Blueprint **Use case.** Add model generation to an Unreal editor tool or Blueprint-driven prototype. **Steps.** 1. Create a text, image, or multiview generation task with the plugin’s Blueprint nodes. 2. Use the callback and task-status nodes to wait for completion. 3. Pass the returned model URL to the download node. Runtime display requires the separate glTFRuntime plugin documented by the package. ![Unreal Engine Blueprint nodes for creating, querying, and downloading Tripo models](https://developers.tripo3d.ai/assets/images/docs/plugins/unreal-blueprint.jpg) **Result.** The generated model can be downloaded for editor import or passed to a runtime display workflow. [Download](https://assets-pub.tripo3d.ai/archive/74c76766-33aa-4bb6-89cb-688f00b3c350/Tripo_API_Unreal-latest.zip) ### Blender — Generate from a reference image **Use case.** Produce a base mesh from an image, then continue modeling and material work in Blender. **Steps.** 1. Open `View3D > Sidebar > Tripo 3D` and connect your API key. 2. Choose image-to-model, provide the reference image, and adjust options such as face limit, texture, PBR, or quad mesh. 3. Start generation and wait for the plugin to download and import the result. **Result.** The GLB or FBX is imported into Blender and can be edited with the standard modeling tools. [Download](https://cdn-web.tripo3d.ai/plugin/tripo-blender.zip) ### Godot — Add a generated model as Node3D **Use case.** Generate a 3D object in a Godot editor or local runtime workflow and add it to the scene tree. **Steps.** Configure the API key in the plugin, create an input and task node, then wait for the task to finish: The example below uses a text task. For an image task, upload the source with `TripoUploadImage` and create the model with `TripoImageToModel`. Copy var input = TripoTextToModelInput.new() input.prompt = "a stylized wooden treasure chest" var task = TripoTextToModel.new() task.input = input add_child(task) if await task.launch() == TripoTask.TaskError.eSuccess: add_child(task.save_to_node()) **Result.** The generated model can be previewed, saved, or added to the current scene as `Node3D`. [Download](https://cdn-web.tripo3d.ai/plugin/tripo-godot.zip) ### Cocos Creator — Save a generated project asset **Use case.** Create a model from text or an image without leaving Cocos Creator. **Steps.** 1. Open the **Tripo Model Generator** panel and connect your API key. 2. Select text or image input, configure generation options, and start the task. 3. Wait for the extension to download the finished model into the project. **Result.** The GLB or FBX is written under `assets/resources` and can be used by the current project. [Download](https://cdn-web.tripo3d.ai/plugin/tripo-cocos.zip) ### ComfyUI — Build a text-to-3D workflow **Use case.** Connect Tripo generation to an existing node-based image or asset pipeline. **Steps.** 1. Connect a text input to the Tripo model-generation node. 2. Set the API key, generation mode, model version, and output options. 3. Connect the result to the 3D preview node and run the queue. ![ComfyUI text-to-3D workflow with a generated model preview](https://developers.tripo3d.ai/assets/images/docs/plugins/comfyui-text-to-model.jpg) **Result.** The model is previewed in the workflow and saved automatically under `ComfyUI/output`. [Download](https://cdn-web.tripo3d.ai/plugin/tripo-comfyUI.zip) Install and get started ----------------------- ### Unity 1. Download and extract the ZIP. 2. Move the extracted plugin directory containing `package.json` into your project’s `Packages` directory. 3. Reopen the project and select `Tools > Tripo API Unity`. ### Unreal Engine 1. Download and extract the ZIP into `Plugins/Tripo3D` in your Unreal project. 2. Enable the plugin in the project settings. 3. Restart Unreal Editor. ### Blender 1. Open `Edit > Preferences > Add-ons`. 2. Choose **Install from Disk**, select the downloaded ZIP, and enable **Tripo 3D**. 3. Open the plugin from `View3D > Sidebar > Tripo 3D`. ### Godot 1. Extract the ZIP and copy `addons/tripo-godot` into the project’s `addons` directory. 2. Open `Project Settings > Plugins` and enable the Tripo plugin. 3. Open the Tripo editor panel or use the provided nodes in a scene. ### Cocos Creator 1. Open `Extension > Extension Manager`. 2. Select **Project** or **Global**, click `+`, and import the downloaded ZIP. 3. Enable the extension, then open the **Tripo Model Generator** panel. See the [Cocos Creator 3.8 extension installation guide](https://docs.cocos.com/creator/3.8/manual/en/editor/extension/install.html) for the standard ZIP-import workflow. ### ComfyUI 1. Extract the ZIP into `ComfyUI/custom_nodes/ComfyUI-Tripo`. 2. Install its dependencies from the ComfyUI Python environment: BashCopy python -m pip install -r ComfyUI/custom_nodes/ComfyUI-Tripo/requirements.txt 3. Restart ComfyUI and load or create a Tripo workflow. Configure an API key -------------------- Create a key on the [Tripo API Keys page](https://platform.tripo3d.ai/api-keys) , then enter it in the selected plugin before starting a task. An API key is a secret credential. Do not commit it to source control, include it in screenshots, print it in logs, or ship it inside a public client build. See [Authentication](https://developers.tripo3d.ai/en/docs/authentication) for the general API rules. Related resources ----------------- * [Codex plugin](https://developers.tripo3d.ai/en/docs/codex-plugin) * [Authentication](https://developers.tripo3d.ai/en/docs/authentication) * [SDK integration](https://developers.tripo3d.ai/en/docs/sdk) * [Tripo API Keys](https://platform.tripo3d.ai/api-keys) PreviousSDK IntegrationNextComfyUI Nodes On this page --- # SDK Integration — Tripo Developers SDK Integration =============== CopyDownload PDF \# SDK Integration Use the official Tripo SDKs to submit a text-to-model task, wait for completion, verify the terminal status, and download the generated model. The installation sources below are locked to the versions used to verify this page. ## Supported SDKs | Language | API | Locked version | Installation source | | --- | --- | --- | --- | | JavaScript / TypeScript | V3 | \[\`e351348\`\](https://github.com/VAST-AI-Research/tripo-js-sdk/tree/e35134801b339caac0b84f36fe02d08e73e217b2) | Official Git commit | | Python | V2 + limited V3 | \[\`v0.4.2\`\](https://github.com/VAST-AI-Research/tripo-python-sdk/tree/v0.4.2) | PyPI \`tripo3d==0.4.2\` | | Go | V3 | \[\`2c8c8d4\`\](https://github.com/VAST-AI-Research/tripo-go-sdk/tree/2c8c8d4e6a9e1fc9e49699fc055140eca689ee79) | Go pseudo-version \`v0.0.0-20260713072120-2c8c8d4e6a9e\` | | Rust | V3 | \[\`f992f6a\`\](https://github.com/VAST-AI-Research/tripo-rust-sdk/tree/f992f6a7cf7a28c10781f9fa28e4630c7802291c) | Cargo Git dependency | | Java | V3 | \[\`7b6a68d\`\](https://github.com/VAST-AI-Research/tripo-java-sdk/tree/7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9) | Source build; local Maven \`0.1.0-SNAPSHOT\` | ## 1. Configure an API key and region Create a key in the \[Tripo Console\](https://platform.tripo3d.ai/) and expose it only to your server-side process. Do not put an API key in browser code or commit it to source control. \`\`\`bash export TRIPO\_API\_KEY="tsk\_..." \`\`\` JavaScript, Go, and Rust use \`https://openapi.tripo3d.ai/v3\`. Java selects \`TripoRegion.GLOBAL\`; the SDK starts from \`https://openapi.tripo3d.ai\` and appends \`/v3\`. Python 0.4.2 uses \`https://api.tripo3d.ai/v2/openapi\` for its main V2 client, plus \`https://openapi.tripo3d.ai\` for its limited V3 segmentation flow. ## 2. Install the SDK Install each SDK from its locked production source. ### JavaScript \`\`\`bash npm install github:VAST-AI-Research/tripo-js-sdk#e35134801b339caac0b84f36fe02d08e73e217b2 \`\`\` ### Python \`\`\`bash python -m pip install tripo3d==0.4.2 \`\`\` ### Go \`\`\`bash go get github.com/VAST-AI-Research/tripo-go-sdk@v0.0.0-20260713072120-2c8c8d4e6a9e \`\`\` ### Rust \`\`\`toml \[dependencies\] tripo3d-sdk = { git = "https://github.com/VAST-AI-Research/tripo-rust-sdk.git", rev = "f992f6a7cf7a28c10781f9fa28e4630c7802291c" } tokio = { version = "1", features = \["full"\] } anyhow = "1" \`\`\` ### Java \`\`\`bash git clone https://github.com/VAST-AI-Research/tripo-java-sdk.git cd tripo-java-sdk git checkout 7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9 ./mvnw install \`\`\` The Java build installs \`ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT\` in the local Maven repository. Add that coordinate to your application after the source build completes. ## 3. Submit, wait, and download Each server-side example reads \`TRIPO\_API\_KEY\`, submits a text-to-model task, waits for a terminal result, checks for success, and saves the primary model immediately. Generated model URLs are temporary. ### JavaScript \`\`\`javascript import { writeFile } from 'node:fs/promises'; import { TripoClient, ModelVersion, TaskStatus } from 'tripo3d-sdk-js'; const apiKey = process.env.TRIPO\_API\_KEY; if (!apiKey) throw new Error('TRIPO\_API\_KEY is required'); const client = new TripoClient({ apiKey, baseUrl: 'https://openapi.tripo3d.ai/v3', }); const taskId = await client.textToModel({ prompt: 'a cute red panda holding bamboo', model: ModelVersion.H3\_1, texture: true, pbr: true, texture\_quality: 'detailed', }); const task = await client.waitForTask(taskId, { pollingIntervalMs: 2000, onProgress: (value) => console.log(\`${value.status} — ${value.progress ?? 0}%\`), }); if (task.status !== TaskStatus.SUCCESS) { throw new Error(\`Task did not succeed: ${task.status}\`); } const modelUrl = task.output.model\_url ?? task.output.model; if (!modelUrl) throw new Error('Task returned no model URL'); const response = await fetch(modelUrl); if (!response.ok) throw new Error(\`Download failed: HTTP ${response.status}\`); await writeFile(\`tripo-${taskId}.glb\`, Buffer.from(await response.arrayBuffer())); \`\`\` ### Python \`\`\`python import asyncio import os import shutil from urllib.request import urlopen from tripo3d import TripoClient from tripo3d.models import TaskStatus def download\_file(url, path): with urlopen(url) as response, open(path, "wb") as output: shutil.copyfileobj(response, output) async def main(): api\_key = os.environ\["TRIPO\_API\_KEY"\] os.makedirs("./output", exist\_ok=True) async with TripoClient(api\_key=api\_key) as client: task\_id = await client.text\_to\_model( prompt="a cute red panda holding bamboo", model\_version="v2.5-20250123", ) task = await client.wait\_for\_task(task\_id, verbose=True) if task.status != TaskStatus.SUCCESS: raise RuntimeError(f"Task did not succeed: {task.status}") model\_url = task.output.model if not model\_url: raise RuntimeError("Task returned no model URL") output\_path = "./output/model.glb" await asyncio.to\_thread(download\_file, model\_url, output\_path) print(f"Downloaded model: {output\_path}") asyncio.run(main()) \`\`\` ### Go \`\`\`go package main import ( "context" "fmt" "log" "os" "time" tripo3d "github.com/VAST-AI-Research/tripo-go-sdk" ) func main() { apiKey := os.Getenv("TRIPO\_API\_KEY") if apiKey == "" { log.Fatal("TRIPO\_API\_KEY is required") } client, err := tripo3d.NewClient(tripo3d.ClientOptions{ APIKey: apiKey, BaseURL: "https://openapi.tripo3d.ai/v3", }) if err != nil { log.Fatal(err) } ctx := context.Background() taskID, err := client.TextToModel(ctx, tripo3d.TextToModelParams{ Prompt: "a cute red panda holding bamboo", Model: tripo3d.String(tripo3d.ModelVersionH31), Texture: tripo3d.Bool(true), PBR: tripo3d.Bool(true), TextureQuality: tripo3d.String("detailed"), }) if err != nil { log.Fatal(err) } task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{ PollInterval: 2 \* time.Second, }) if err != nil { log.Fatal(err) } if task.Status != tripo3d.TaskStatusSuccess { log.Fatalf("Task did not succeed: %s", task.Status) } downloaded, err := client.DownloadModel(ctx, task) if err != nil { log.Fatal(err) } if downloaded == nil { log.Fatal("Task returned no model URL") } filename := fmt.Sprintf("tripo-%s.glb", taskID) if err := os.WriteFile(filename, downloaded.Data, 0o644); err != nil { log.Fatal(err) } } \`\`\` ### Rust \`\`\`rust use tokio::fs; use tripo3d\_sdk::{ constants::model\_version, params::TextToModelParams, ClientOptions, TaskStatus, TripoClient, WaitOptions, }; #\[tokio::main\] async fn main() -> anyhow::Result<()> { let api\_key = std::env::var("TRIPO\_API\_KEY")?; let client = TripoClient::new(ClientOptions { api\_key: Some(api\_key), base\_url: Some("https://openapi.tripo3d.ai/v3".into()), ..Default::default() })?; let task\_id = client .text\_to\_model(TextToModelParams { prompt: "a cute red panda holding bamboo".into(), model: Some(model\_version::H3\_1.to\_string()), texture: Some(true), pbr: Some(true), texture\_quality: Some("detailed".into()), ..Default::default() }) .await?; let task = client .wait\_for\_task(&task\_id, WaitOptions::default()) .await?; if task.status != TaskStatus::Success { anyhow::bail!("Task did not succeed: {}", task.status); } let downloaded = client .download\_model(&task) .await? .ok\_or\_else(|| anyhow::anyhow!("Task returned no model URL"))?; fs::write(format!("tripo-{task\_id}.glb"), downloaded.data).await?; Ok(()) } \`\`\` ### Java \`\`\`java import ai.tripo3d.sdk.api.TripoClient; import ai.tripo3d.sdk.api.TripoClientConfig; import ai.tripo3d.sdk.api.TripoRegion; import ai.tripo3d.sdk.model.request.TaskRequestPayload; import ai.tripo3d.sdk.model.response.TaskDetail; import java.io.InputStream; import java.net.URL; import java.nio.file.Files; import java.nio.file.Paths; import java.nio.file.StandardCopyOption; import java.util.Map; public final class TripoQuickStart { public static void main(String\[\] args) throws Exception { String apiKey = System.getenv("TRIPO\_API\_KEY"); if (apiKey == null || apiKey.trim().isEmpty()) { throw new IllegalStateException("TRIPO\_API\_KEY is required"); } try (TripoClient client = TripoClient.create( TripoClientConfig.builder(apiKey) .region(TripoRegion.GLOBAL) .build())) { TaskDetail created = client.textToModel(TaskRequestPayload.builder() .prompt("a wooden chair") .model("v3.1-20260211") .build()); TaskDetail done = client.pollUntilTerminal(created.taskId()); if (!"success".equalsIgnoreCase(done.status())) { throw new IllegalStateException( "Task failed: status=" + done.status() + ", message=" + done.errorMsg()); } Map output = done.output(); Object modelUrl = output == null ? null : output.get("model\_url"); if (!(modelUrl instanceof String)) { throw new IllegalStateException( "Task output does not contain model\_url"); } try (InputStream input = new URL((String) modelUrl).openStream()) { Files.copy( input, Paths.get("model.glb"), StandardCopyOption.REPLACE\_EXISTING); } } } } \`\`\` JavaScript, Python, and Java deliberately use native HTTP clients for the signed model URL and do not attach an \`Authorization\` header. The Go and Rust SDK download methods also fetch the signed URL without the API key. ## 4. V3 route support The matrix is the union of all five SDK implementations at the locked versions above. A check mark means that a public SDK flow reaches the final V3 HTTP route, directly or through an internal step; unused route constants do not count. | HTTP route | Purpose | JavaScript | Python | Go | Rust | Java | | --- | --- | :---: | :---: | :---: | :---: | :---: | | \`POST /v3/generation/text-to-model\` | Generate a model from text | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/generation/image-to-model\` | Generate a model from one image | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/generation/multiview-to-model\` | Generate a model from multiple views | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/generation/text-to-image\` | Generate an image from text | ✓ | — | ✓ | ✓ | — | | \`POST /v3/generation/image-to-image\` | Transform an image | ✓ | — | ✓ | ✓ | — | | \`POST /v3/generation/image-to-multiview\` | Generate multiview images | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/generation/edit-multiview\` | Edit multiview output | ✓ | — | ✓ | ✓ | — | | \`POST /v3/generation/image-to-splat\` | Generate a Gaussian splat | — | — | — | — | ✓ | | \`POST /v3/models/refine\` | Refine a draft model | — | — | — | — | ✓ | | \`POST /v3/models/texture\` | Apply or regenerate textures | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/models/stylize\` | Stylize a model | — | — | — | — | ✓ | | \`POST /v3/models/convert\` | Convert model format | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/models/import\` | Import an external model | — | — | — | — | ✓ | | \`POST /v3/mesh/segment\` | Segment a mesh | ✓ | ✓ | ✓ | ✓ | ✓ | | \`POST /v3/mesh/complete\` | Complete or repair a mesh | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/mesh/decimate\` | Reduce face count | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/animations/rig-check\` | Check whether a model can be rigged | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/animations/rig\` | Attach a skeleton | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/animations/retarget\` | Apply a preset animation | ✓ | — | ✓ | ✓ | ✓ | | \`GET /v3/tasks/{task\_id}\` | Get one task | ✓ | ✓ | ✓ | ✓ | ✓ | | \`POST /v3/tasks/list\` | Get multiple tasks | ✓ | — | ✓ | ✓ | ✓ | | \`POST /v3/files\` | Upload a file | ✓ | ✓ | ✓ | ✓ | ✓ | | \`POST /v3/files/presign\` | Create a presigned upload | — | — | — | — | ✓ | | \`GET /v3/account/balance\` | Get account balance | ✓ | — | ✓ | ✓ | ✓ | | \`GET /v3/account/usage\` | Get usage history | — | — | — | — | ✓ | At this locked version, Java uniquely exposes image-to-splat, refine, stylize, import, presign, and usage. Java does not expose text-to-image, image-to-image, or edit-multiview. Its internal descriptor for \`/v3/files/upload-credentials\` has no service or public client method, so it is not counted as supported. Python remains primarily a V2 SDK. Its \`mesh\_segmentation(..., model\_version="v2.0-20260430")\` branch additionally uses \`POST /v3/mesh/segment\`, \`GET /v3/tasks/{task\_id}\`, and \`POST /v3/files\` when a local \`ref\_image\` must be uploaded. ### Python V2 route support Python 0.4.2 exposes five final V2 HTTP routes. \`POST /v2/openapi/task\` is shared by its generation, model processing, mesh, and animation task methods; it is not limited to text-to-model. | HTTP route | Purpose | | --- | --- | | \`POST /v2/openapi/task\` | Submit any supported V2 task | | \`GET /v2/openapi/task/{task\_id}\` | Query task status and output | | \`GET /v2/openapi/user/balance\` | Get account balance | | \`POST /v2/openapi/upload/sts/token\` | Get STS upload credentials when \`boto3\` is available | | \`POST /v2/openapi/upload\` | Upload a file when the SDK uses its legacy multipart fallback | Java and the other V3 SDKs send the model selection through their official V3 parameter models. On the Java wire, the field name is \`model\`. ## 5. Troubleshooting - \*\*Missing key:\*\* set \`TRIPO\_API\_KEY\` in the server process. See \[Authentication\](./authentication). - \*\*Wrong region:\*\* select the matching global or China endpoint for the SDK and API version in use. - \*\*Failed or timed-out task:\*\* keep the \`task\_id\`, inspect the terminal status, and see \[Task Lifecycle\](./task-lifecycle) and \[Error Handling\](./error-handling). - \*\*Expired model URL:\*\* query the task again when the SDK supports it, then download the model immediately. Do not store a temporary signed URL as a permanent asset. ## Official repositories - \[JavaScript SDK\](https://github.com/VAST-AI-Research/tripo-js-sdk) - \[Python SDK\](https://github.com/VAST-AI-Research/tripo-python-sdk) - \[Go SDK\](https://github.com/VAST-AI-Research/tripo-go-sdk) - \[Rust SDK\](https://github.com/VAST-AI-Research/tripo-rust-sdk) - \[Java SDK\](https://github.com/VAST-AI-Research/tripo-java-sdk) SDK Integration =============== Use the official Tripo SDKs to submit a text-to-model task, wait for completion, verify the terminal status, and download the generated model. The installation sources below are locked to the versions used to verify this page. Supported SDKs -------------- | Language | API | Locked version | Installation source | | --- | --- | --- | --- | | JavaScript / TypeScript | V3 | [`e351348`](https://github.com/VAST-AI-Research/tripo-js-sdk/tree/e35134801b339caac0b84f36fe02d08e73e217b2) | Official Git commit | | Python | V2 + limited V3 | [`v0.4.2`](https://github.com/VAST-AI-Research/tripo-python-sdk/tree/v0.4.2) | PyPI `tripo3d==0.4.2` | | Go | V3 | [`2c8c8d4`](https://github.com/VAST-AI-Research/tripo-go-sdk/tree/2c8c8d4e6a9e1fc9e49699fc055140eca689ee79) | Go pseudo-version `v0.0.0-20260713072120-2c8c8d4e6a9e` | | Rust | V3 | [`f992f6a`](https://github.com/VAST-AI-Research/tripo-rust-sdk/tree/f992f6a7cf7a28c10781f9fa28e4630c7802291c) | Cargo Git dependency | | Java | V3 | [`7b6a68d`](https://github.com/VAST-AI-Research/tripo-java-sdk/tree/7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9) | Source build; local Maven `0.1.0-SNAPSHOT` | 1\. Configure an API key and region ----------------------------------- Create a key in the [Tripo Console](https://platform.tripo3d.ai/) and expose it only to your server-side process. Do not put an API key in browser code or commit it to source control. BashCopy export TRIPO_API_KEY="tsk_..." JavaScript, Go, and Rust use `https://openapi.tripo3d.ai/v3`. Java selects `TripoRegion.GLOBAL`; the SDK starts from `https://openapi.tripo3d.ai` and appends `/v3`. Python 0.4.2 uses `https://api.tripo3d.ai/v2/openapi` for its main V2 client, plus `https://openapi.tripo3d.ai` for its limited V3 segmentation flow. 2\. Install the SDK ------------------- Install each SDK from its locked production source. JavaScriptPythonGoRustJava Copy npm install github:VAST-AI-Research/tripo-js-sdk#e35134801b339caac0b84f36fe02d08e73e217b2 python -m pip install tripo3d==0.4.2 go get github.com/VAST-AI-Research/tripo-go-sdk@v0.0.0-20260713072120-2c8c8d4e6a9e [dependencies] tripo3d-sdk = { git = "https://github.com/VAST-AI-Research/tripo-rust-sdk.git", rev = "f992f6a7cf7a28c10781f9fa28e4630c7802291c" } tokio = { version = "1", features = ["full"] } anyhow = "1" git clone https://github.com/VAST-AI-Research/tripo-java-sdk.git cd tripo-java-sdk git checkout 7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9 ./mvnw install The Java build installs `ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT` in the local Maven repository. Add that coordinate to your application after the source build completes. 3\. Submit, wait, and download ------------------------------ Each server-side example reads `TRIPO_API_KEY`, submits a text-to-model task, waits for a terminal result, checks for success, and saves the primary model immediately. Generated model URLs are temporary. JavaScriptPythonGoRustJava Copy import { writeFile } from 'node:fs/promises'; import { TripoClient, ModelVersion, TaskStatus } from 'tripo3d-sdk-js'; const apiKey = process.env.TRIPO_API_KEY; if (!apiKey) throw new Error('TRIPO_API_KEY is required'); const client = new TripoClient({ apiKey, baseUrl: 'https://openapi.tripo3d.ai/v3', }); const taskId = await client.textToModel({ prompt: 'a cute red panda holding bamboo', model: ModelVersion.H3_1, texture: true, pbr: true, texture_quality: 'detailed', }); const task = await client.waitForTask(taskId, { pollingIntervalMs: 2000, onProgress: (value) => console.log(`${value.status} — ${value.progress ?? 0}%`), }); if (task.status !== TaskStatus.SUCCESS) { throw new Error(`Task did not succeed: ${task.status}`); } const modelUrl = task.output.model_url ?? task.output.model; if (!modelUrl) throw new Error('Task returned no model URL'); const response = await fetch(modelUrl); if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`); await writeFile(`tripo-${taskId}.glb`, Buffer.from(await response.arrayBuffer())); import asyncio import os import shutil from urllib.request import urlopen from tripo3d import TripoClient from tripo3d.models import TaskStatus def download_file(url, path): with urlopen(url) as response, open(path, "wb") as output: shutil.copyfileobj(response, output) async def main(): api_key = os.environ["TRIPO_API_KEY"] os.makedirs("./output", exist_ok=True) async with TripoClient(api_key=api_key) as client: task_id = await client.text_to_model( prompt="a cute red panda holding bamboo", model_version="v2.5-20250123", ) task = await client.wait_for_task(task_id, verbose=True) if task.status != TaskStatus.SUCCESS: raise RuntimeError(f"Task did not succeed: {task.status}") model_url = task.output.model if not model_url: raise RuntimeError("Task returned no model URL") output_path = "./output/model.glb" await asyncio.to_thread(download_file, model_url, output_path) print(f"Downloaded model: {output_path}") asyncio.run(main()) package main import ( "context" "fmt" "log" "os" "time" tripo3d "github.com/VAST-AI-Research/tripo-go-sdk" ) func main() { apiKey := os.Getenv("TRIPO_API_KEY") if apiKey == "" { log.Fatal("TRIPO_API_KEY is required") } client, err := tripo3d.NewClient(tripo3d.ClientOptions{ APIKey: apiKey, BaseURL: "https://openapi.tripo3d.ai/v3", }) if err != nil { log.Fatal(err) } ctx := context.Background() taskID, err := client.TextToModel(ctx, tripo3d.TextToModelParams{ Prompt: "a cute red panda holding bamboo", Model: tripo3d.String(tripo3d.ModelVersionH31), Texture: tripo3d.Bool(true), PBR: tripo3d.Bool(true), TextureQuality: tripo3d.String("detailed"), }) if err != nil { log.Fatal(err) } task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{ PollInterval: 2 * time.Second, }) if err != nil { log.Fatal(err) } if task.Status != tripo3d.TaskStatusSuccess { log.Fatalf("Task did not succeed: %s", task.Status) } downloaded, err := client.DownloadModel(ctx, task) if err != nil { log.Fatal(err) } if downloaded == nil { log.Fatal("Task returned no model URL") } filename := fmt.Sprintf("tripo-%s.glb", taskID) if err := os.WriteFile(filename, downloaded.Data, 0o644); err != nil { log.Fatal(err) } } use tokio::fs; use tripo3d_sdk::{ constants::model_version, params::TextToModelParams, ClientOptions, TaskStatus, TripoClient, WaitOptions, }; #[tokio::main] async fn main() -> anyhow::Result<()> { let api_key = std::env::var("TRIPO_API_KEY")?; let client = TripoClient::new(ClientOptions { api_key: Some(api_key), base_url: Some("https://openapi.tripo3d.ai/v3".into()), ..Default::default() })?; let task_id = client .text_to_model(TextToModelParams { prompt: "a cute red panda holding bamboo".into(), model: Some(model_version::H3_1.to_string()), texture: Some(true), pbr: Some(true), texture_quality: Some("detailed".into()), ..Default::default() }) .await?; let task = client .wait_for_task(&task_id, WaitOptions::default()) .await?; if task.status != TaskStatus::Success { anyhow::bail!("Task did not succeed: {}", task.status); } let downloaded = client .download_model(&task) .await? .ok_or_else(|| anyhow::anyhow!("Task returned no model URL"))?; fs::write(format!("tripo-{task_id}.glb"), downloaded.data).await?; Ok(()) } import ai.tripo3d.sdk.api.TripoClient; import ai.tripo3d.sdk.api.TripoClientConfig; import ai.tripo3d.sdk.api.TripoRegion; import ai.tripo3d.sdk.model.request.TaskRequestPayload; import ai.tripo3d.sdk.model.response.TaskDetail; import java.io.InputStream; import java.net.URL; import java.nio.file.Files; import java.nio.file.Paths; import java.nio.file.StandardCopyOption; import java.util.Map; public final class TripoQuickStart { public static void main(String[] args) throws Exception { String apiKey = System.getenv("TRIPO_API_KEY"); if (apiKey == null || apiKey.trim().isEmpty()) { throw new IllegalStateException("TRIPO_API_KEY is required"); } try (TripoClient client = TripoClient.create( TripoClientConfig.builder(apiKey) .region(TripoRegion.GLOBAL) .build())) { TaskDetail created = client.textToModel(TaskRequestPayload.builder() .prompt("a wooden chair") .model("v3.1-20260211") .build()); TaskDetail done = client.pollUntilTerminal(created.taskId()); if (!"success".equalsIgnoreCase(done.status())) { throw new IllegalStateException( "Task failed: status=" + done.status() + ", message=" + done.errorMsg()); } Map output = done.output(); Object modelUrl = output == null ? null : output.get("model_url"); if (!(modelUrl instanceof String)) { throw new IllegalStateException( "Task output does not contain model_url"); } try (InputStream input = new URL((String) modelUrl).openStream()) { Files.copy( input, Paths.get("model.glb"), StandardCopyOption.REPLACE_EXISTING); } } } } JavaScript, Python, and Java deliberately use native HTTP clients for the signed model URL and do not attach an `Authorization` header. The Go and Rust SDK download methods also fetch the signed URL without the API key. 4\. V3 route support -------------------- The matrix is the union of all five SDK implementations at the locked versions above. A check mark means that a public SDK flow reaches the final V3 HTTP route, directly or through an internal step; unused route constants do not count. | HTTP route | Purpose | JavaScript | Python | Go | Rust | Java | | --- | --- | --- | --- | --- | --- | --- | | `POST /v3/generation/text-to-model` | Generate a model from text | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/generation/image-to-model` | Generate a model from one image | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/generation/multiview-to-model` | Generate a model from multiple views | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/generation/text-to-image` | Generate an image from text | ✓ | — | ✓ | ✓ | — | | `POST /v3/generation/image-to-image` | Transform an image | ✓ | — | ✓ | ✓ | — | | `POST /v3/generation/image-to-multiview` | Generate multiview images | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/generation/edit-multiview` | Edit multiview output | ✓ | — | ✓ | ✓ | — | | `POST /v3/generation/image-to-splat` | Generate a Gaussian splat | — | — | — | — | ✓ | | `POST /v3/models/refine` | Refine a draft model | — | — | — | — | ✓ | | `POST /v3/models/texture` | Apply or regenerate textures | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/models/stylize` | Stylize a model | — | — | — | — | ✓ | | `POST /v3/models/convert` | Convert model format | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/models/import` | Import an external model | — | — | — | — | ✓ | | `POST /v3/mesh/segment` | Segment a mesh | ✓ | ✓ | ✓ | ✓ | ✓ | | `POST /v3/mesh/complete` | Complete or repair a mesh | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/mesh/decimate` | Reduce face count | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/animations/rig-check` | Check whether a model can be rigged | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/animations/rig` | Attach a skeleton | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/animations/retarget` | Apply a preset animation | ✓ | — | ✓ | ✓ | ✓ | | `GET /v3/tasks/{task_id}` | Get one task | ✓ | ✓ | ✓ | ✓ | ✓ | | `POST /v3/tasks/list` | Get multiple tasks | ✓ | — | ✓ | ✓ | ✓ | | `POST /v3/files` | Upload a file | ✓ | ✓ | ✓ | ✓ | ✓ | | `POST /v3/files/presign` | Create a presigned upload | — | — | — | — | ✓ | | `GET /v3/account/balance` | Get account balance | ✓ | — | ✓ | ✓ | ✓ | | `GET /v3/account/usage` | Get usage history | — | — | — | — | ✓ | At this locked version, Java uniquely exposes image-to-splat, refine, stylize, import, presign, and usage. Java does not expose text-to-image, image-to-image, or edit-multiview. Its internal descriptor for `/v3/files/upload-credentials` has no service or public client method, so it is not counted as supported. Python remains primarily a V2 SDK. Its `mesh_segmentation(..., model_version="v2.0-20260430")` branch additionally uses `POST /v3/mesh/segment`, `GET /v3/tasks/{task_id}`, and `POST /v3/files` when a local `ref_image` must be uploaded. ### Python V2 route support Python 0.4.2 exposes five final V2 HTTP routes. `POST /v2/openapi/task` is shared by its generation, model processing, mesh, and animation task methods; it is not limited to text-to-model. | HTTP route | Purpose | | --- | --- | | `POST /v2/openapi/task` | Submit any supported V2 task | | `GET /v2/openapi/task/{task_id}` | Query task status and output | | `GET /v2/openapi/user/balance` | Get account balance | | `POST /v2/openapi/upload/sts/token` | Get STS upload credentials when `boto3` is available | | `POST /v2/openapi/upload` | Upload a file when the SDK uses its legacy multipart fallback | Java and the other V3 SDKs send the model selection through their official V3 parameter models. On the Java wire, the field name is `model`. 5\. Troubleshooting ------------------- * **Missing key:** set `TRIPO_API_KEY` in the server process. See [Authentication](https://developers.tripo3d.ai/en/docs/authentication) . * **Wrong region:** select the matching global or China endpoint for the SDK and API version in use. * **Failed or timed-out task:** keep the `task_id`, inspect the terminal status, and see [Task Lifecycle](https://developers.tripo3d.ai/en/docs/task-lifecycle) and [Error Handling](https://developers.tripo3d.ai/en/docs/error-handling) . * **Expired model URL:** query the task again when the SDK supports it, then download the model immediately. Do not store a temporary signed URL as a permanent asset. Official repositories --------------------- * [JavaScript SDK](https://github.com/VAST-AI-Research/tripo-js-sdk) * [Python SDK](https://github.com/VAST-AI-Research/tripo-python-sdk) * [Go SDK](https://github.com/VAST-AI-Research/tripo-go-sdk) * [Rust SDK](https://github.com/VAST-AI-Research/tripo-rust-sdk) * [Java SDK](https://github.com/VAST-AI-Research/tripo-java-sdk) PreviousChangelogNextPlugins On this page --- # ComfyUI Nodes — Tripo Developers ComfyUI Nodes ============= CopyDownload PDF \# ComfyUI Nodes ComfyUI-Tripo is Tripo's official custom-node extension for ComfyUI. It supports generating 3D models from text, a single image, or multiview images within ComfyUI workflows, along with model import, texturing, refinement, mesh processing, low-poly optimization, stylization, rigging, animation retargeting, format conversion, and retopology. | Item | Value | | --- | --- | | Node package version | 1.3.0 | | Source tag | v1.3.1.1 | | Source | \[VAST-AI-Research/ComfyUI-Tripo\](https://github.com/VAST-AI-Research/ComfyUI-Tripo) | ## Capabilities and changelog ### Capabilities - Generate 3D models from text prompts. - Generate 3D models from images. - Import models from a URL through model\_url. - Support splitting models into separate parts. - Rig and animate 3D models. - Convert formats and retopologize models. ### Changelog - 2026-06-30: added Mesh Segmentation v2.0 for splitting models into separate parts and direct URL import through model\_url. - 2026-05-28: added model import. - 2025-06-19: updated to the newest API and added more nodes. - 2025-03-31: switched to the tripo3d package. - 2025-02-24: removed glbviewer. - 2025-02-01: adapted to the new API and switched model viewing to Preview 3D. - 2024-11-11: adapted to the new API. - 2024-10-14: added model conversion. - 2024-09-13: added support for model\_version v2.0-20240919. ## Installation \*\*Choose one\*\* method, then restart ComfyUI. ### ComfyUI-Manager Open \[Custom Nodes Manager\](https://github.com/ltdrdata/ComfyUI-Manager), search for Tripo for ComfyUI, and install it. ### comfy-cli Install \[comfy-cli\](https://github.com/Comfy-Org/comfy-cli) through \[Comfy Registry\](https://registry.comfy.org/), then run: ~~~bash comfy node registry-install comfyui-tripo ~~~ ### From source Place the repository in ComfyUI/custom\_nodes/ComfyUI-Tripo, then install its dependencies: ~~~bash cd ComfyUI/custom\_nodes git clone https://github.com/VAST-AI-Research/ComfyUI-Tripo.git python -m pip install -r ComfyUI-Tripo/requirements.txt ~~~ ## API key configuration Create an API key on the \[Tripo platform\](https://platform.tripo3d.ai/), then configure it with one of the methods below. The node package resolves an API key in this order: 1. A non-empty apikey input on the node. 2. The TRIPO\_API\_KEY environment variable. 3. config.json in the ComfyUI-Tripo directory, with a TRIPO\_API\_KEY field. The Generate and Import nodes expose apikey. Downstream nodes receive the resolved key through MODEL\_INFO. Do not expose a real API key in screenshots, shared workflows, logs, or source repositories. Clear the apikey field before sharing a workflow and prefer an environment variable for local use. ### Environment variable launch examples Windows: ~~~shell set TRIPO\_API\_KEY=tsk\_XXXXXXX python.exe main.py \[--cpu\] ~~~ Linux or macOS: ~~~bash TRIPO\_API\_KEY=tsk\_XXXXXXX python main.py \[--cpu\] ~~~ ## Node overview ComfyUI-Tripo provides the following 11 Tripo nodes: | Internal ID | Display name | Capability | Output | | --- | --- | --- | --- | | TripoAPIDraft | Tripo: Generate model | Generate from text, image, or multiple views | model\_file, MODEL\_INFO | | TripoImportModel | Tripo: Import model | Import a local model or model URL | MODEL\_INFO | | TripoTextureModel | Tripo: Texture model | Texture a model | model\_file, MODEL\_INFO | | TripoRefineModel | Tripo: Refine Draft model | Refine a draft model | model\_file, MODEL\_INFO | | TripoMeshSegmentation | Tripo: Segment mesh | Segment a mesh | model\_file, MODEL\_INFO | | TripoMeshCompletion | Tripo: Complete mesh | Complete a segmented mesh | model\_file, MODEL\_INFO | | TripoSmartLowPoly | Tripo: Smart low poly | Create a low-poly model | model\_file, MODEL\_INFO | | TripoStylizeModel | Tripo: Stylize model | Apply a geometric style | model\_file, MODEL\_INFO | | TripoAnimateRigNode | Tripo: Rig model | Automatically rig a model | model\_file, MODEL\_INFO | | TripoAnimateRetargetNode | Tripo: Retarget rigged model | Apply a preset animation | model\_file, MODEL\_INFO | | TripoConvertNode | Tripo: Convert model | Convert and export a model | model\_file | Preview 3D is provided by ComfyUI and is not one of these 11 nodes. ## Connections and data flow ~~~mermaid flowchart LR G\["Generate model"\] -->|MODEL\_INFO| P\["Model processing"\] I\["Import model"\] -->|MODEL\_INFO| P P -->|MODEL\_INFO| R\["Rig model"\] R -->|MODEL\_INFO| A\["Retarget rigged model"\] A -->|MODEL\_INFO| C\["Convert model"\] ~~~ - model\_file is the downloaded path produced by a generation or processing task. It can be sent to a ComfyUI preview or file-handling node. - MODEL\_INFO contains the Tripo task context used by downstream Tripo nodes: task\_id, resolved apikey, file\_prefix, and output\_directory. - A model from outside this node chain must first pass through TripoImportModel. A file path alone cannot replace MODEL\_INFO. - Connect nodes through MODEL\_INFO when further Tripo processing is required. The model\_file output is not the processing context. ## Complete node reference “Required” indicates whether a node parameter must be provided. The apikey field may be left empty to use the environment or configuration fallback. A dash means no explicit default is set. ### Generation and import ### TripoAPIDraft — Tripo: Generate model Creates the first Tripo task in a workflow. It has no node prerequisite. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | mode | ENUM | Yes | first value | text\_to\_model, image\_to\_model, multiview\_to\_model | | apikey | STRING | Yes | empty | API key or fallback | | prompt | STRING, multiline | No | empty | Text prompt | | negative\_prompt | STRING, multiline | No | empty | Negative text prompt | | image | IMAGE | No | — | Source image; front image in multiview mode | | image\_left | IMAGE | No | — | Optional left view | | image\_back | IMAGE | No | — | Optional back view | | image\_right | IMAGE | No | — | Optional right view | | model\_version | ENUM | No | v3.1-20260211 | v1.4-20240625, v2.0-20240919, v2.5-20250123, v3.0-20250812, v3.1-20260211 | | texture | BOOLEAN | No | true | Enable texture generation | | pbr | BOOLEAN | No | true | Enable PBR maps | | image\_seed | INT | No | 42 | Used by text mode | | model\_seed | INT | No | 42 | Model seed | | texture\_seed | INT | No | 42 | Texture seed | | texture\_quality | ENUM | No | standard | standard, detailed | | geometry\_quality | ENUM | No | standard | standard, detailed; image mode only | | texture\_alignment | ENUM | No | original\_image | original\_image, geometry | | face\_limit | INT | No | -1 | -1–500000; values ≤ 0 are sent as unset | | quad | BOOLEAN | No | false | Request quad topology | | compress | BOOLEAN | No | false | Compress output | | generate\_parts | BOOLEAN | No | false | Generate parts | | smart\_low\_poly | BOOLEAN | No | false | Enable smart low-poly generation | | auto\_size | BOOLEAN | No | false | Automatically size the model | | orientation | ENUM | No | default | default, align\_image; image and multiview modes | | file\_prefix | STRING | No | empty | Prefix for the downloaded filename | | output\_directory | STRING | No | empty | Destination directory override | Mode requirements: | Mode | Conditionally required | Notes | | --- | --- | --- | | text\_to\_model | prompt | Fails with “Prompt is required” when empty | | image\_to\_model | image | Fails with “Image is required” when absent | | multiview\_to\_model | image | image is the front view; left, back, and right are optional | Outputs: STRING model\_file and MODEL\_INFO. Common failures: missing conditional input, missing/invalid API key, rejected API task, or output move failure. Minimum connection: prompt or image → TripoAPIDraft → Preview 3D; use MODEL\_INFO for later processing. ### TripoImportModel — Tripo: Import model Creates Tripo task context for a model that did not originate in this node chain. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | apikey | STRING | Yes | empty | API key or fallback | | model\_file | file selector | No | none | Model in the ComfyUI input directory | | model\_url | STRING | No | empty | Direct URL to a model | | file\_prefix | STRING | No | empty | Prefix propagated to downstream downloads | | output\_directory | STRING | No | empty | Directory propagated to downstream downloads | A non-empty model\_url takes priority over model\_file. If both are empty, the node fails. The upload control accepts .glb, .fbx, .obj, .stl, .ply, .3mf, and .gltf; the backend input scan also recognizes .zip. Output: MODEL\_INFO only. Common failures: neither source is provided, a local file is missing, the URL cannot be fetched, the format is rejected, or the import task fails. Minimum connection: local file or URL → TripoImportModel → any processor that accepts MODEL\_INFO. ### Model processing ### TripoTextureModel — Tripo: Texture model Requires MODEL\_INFO from Generate, Import, or another compatible processor. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | model\_version | ENUM | No | v3.0-20250812 | v2.5-20250123, v3.0-20250812 | | texture | BOOLEAN | No | true | Enable texture | | pbr | BOOLEAN | No | true | Enable PBR maps | | texture\_seed | INT | No | 42 | Texture seed | | texture\_quality | ENUM | No | standard | standard, detailed | | texture\_alignment | ENUM | No | original\_image | original\_image, geometry | | text\_prompt | STRING, multiline | No | empty | Texture guidance text | | image\_prompt | IMAGE | No | — | Texture reference | | style\_image | IMAGE | No | — | Style reference | | part\_names | STRING, multiline | No | empty | One part name per line | | compress | BOOLEAN | No | false | Compress output | | bake | BOOLEAN | No | true | Bake texture | Outputs: STRING model\_file and MODEL\_INFO. Common failures: incompatible task context, invalid reference image, or API task failure. Minimum connection: Generate/Import MODEL\_INFO → TripoTextureModel → Preview 3D or another processor. ### TripoRefineModel — Tripo: Refine Draft model | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Draft-model task context | Outputs: STRING model\_file and MODEL\_INFO. The upstream task must be a refinable draft; an incompatible task or failed API task causes failure. Minimum connection: Generate draft MODEL\_INFO → TripoRefineModel → Preview 3D. ### TripoMeshSegmentation — Tripo: Segment mesh | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | model\_version | ENUM | Yes | v1.0-20250506 | v1.0-20250506, v2.0-20260430 | | segmentation\_granularity | ENUM | No | balanced | simple, balanced, detailed | | ref\_image | IMAGE | No | — | Segmentation reference image | | split\_by\_connectivity | BOOLEAN | No | true | Split disconnected geometry | segmentation\_granularity, ref\_image, and split\_by\_connectivity are sent only with v2.0-20260430; v1 ignores them. Outputs: STRING model\_file and MODEL\_INFO. Common failures: incompatible model, invalid reference image, or API task failure. Minimum connection: Generate/Import MODEL\_INFO → TripoMeshSegmentation → Completion or Preview 3D. ### TripoMeshCompletion — Tripo: Complete mesh | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Segmented-model task context | | model\_version | ENUM | Yes | v1.0-20250506 | v1.0-20250506 | | part\_names | STRING, multiline | No | empty | One part name per line | Outputs: STRING model\_file and MODEL\_INFO. A task that is not suitable for completion or a failed API task causes failure. Minimum connection: Segment MODEL\_INFO → TripoMeshCompletion → Preview 3D. ### TripoSmartLowPoly — Tripo: Smart low poly | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | model\_version | ENUM | Yes | P-v2.0-20251225 | P-v2.0-20251225 | | quad | BOOLEAN | No | false | Request quad topology | | part\_names | STRING, multiline | No | empty | One part name per line | | face\_limit | INT | No | 10000 | -1–20000 | | bake | BOOLEAN | No | true | Bake output | Outputs: STRING model\_file and MODEL\_INFO. Common failures: incompatible model/parts or API task failure. Minimum connection: Generate/Import MODEL\_INFO → TripoSmartLowPoly → Preview 3D or Convert. ### TripoStylizeModel — Tripo: Stylize model | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | style | ENUM | Yes | first value | lego, voxel, voronoi, minecraft | | block\_size | INT | Yes | 80 | 1–1000 | Outputs: STRING model\_file and MODEL\_INFO. Common failures: incompatible model, unsupported style for the task, or API task failure. Minimum connection: Generate/Import MODEL\_INFO → TripoStylizeModel → Preview 3D. ### Rigging and animation ### TripoAnimateRigNode — Tripo: Rig model The node checks whether the model is riggable and obtains a rig type before submitting the rig task. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | model\_version | ENUM | Yes | v2.0-20250506 | v1.0-20240301, v2.0-20250506 | | out\_format | ENUM | Yes | glb | glb, fbx | | spec | ENUM | Yes | tripo | mixamo, tripo | Outputs: STRING model\_file and MODEL\_INFO. It fails when the model cannot be rigged, no suitable rig type is found, or the API task fails. Minimum connection: Generate/Import MODEL\_INFO → TripoAnimateRigNode → Retarget or Preview 3D. ### TripoAnimateRetargetNode — Tripo: Retarget rigged model Requires MODEL\_INFO from a successfully rigged model. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Rigged-model task context | | animation | ENUM | Yes | first value | See all 16 presets below | | out\_format | ENUM | Yes | glb | glb, fbx | | bake\_animation | BOOLEAN | No | true | Bake the animation | | export\_with\_geometry | BOOLEAN | No | false | Include geometry in export | The 16 animation values are: preset:idle, preset:walk, preset:run, preset:dive, preset:climb, preset:jump, preset:slash, preset:shoot, preset:hurt, preset:fall, preset:turn, preset:quadruped:walk, preset:hexapod:walk, preset:octopod:walk, preset:serpentine:march, and preset:aquatic:march. Outputs: STRING model\_file and MODEL\_INFO. An unrigged/incompatible task or failed API task causes failure. Minimum connection: Rig MODEL\_INFO → TripoAnimateRetargetNode → Preview 3D or Convert. ### Format output ### TripoConvertNode — Tripo: Convert model This is an output node and returns no MODEL\_INFO. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | model\_info | MODEL\_INFO | Yes | — | Upstream task context | | format | ENUM | Yes | first value | GLTF, USDZ, FBX, OBJ, STL, 3MF | | quad | BOOLEAN | No | false | Request quad topology | | force\_symmetry | BOOLEAN | No | false | Force symmetry | | face\_limit | INT | No | -1 | -1–500000 | | flatten\_bottom | BOOLEAN | No | false | Flatten the bottom | | flatten\_bottom\_threshold | FLOAT | No | 0.01 | 0.0–1.0 | | texture\_size | INT | No | 4096 | 128–4096 | | texture\_format | ENUM | No | JPEG | BMP, DPX, HDR, JPEG, OPEN\_EXR, PNG, TARGA, TIFF, WEBP | | pivot\_to\_center\_bottom | BOOLEAN | No | false | Move pivot to center-bottom | | scale\_factor | FLOAT | No | 1.0 | Minimum 0 | | with\_animation | BOOLEAN | No | true | Preserve animation | | pack\_uv | BOOLEAN | No | false | Pack UVs | | bake | BOOLEAN | No | true | Bake output | | part\_names | STRING, multiline | No | empty | One part name per line | | fbx\_preset | ENUM | No | blender | blender, mixamo, 3dsmax | | export\_vertex\_colors | BOOLEAN | No | false | Export vertex colors | | export\_orientation | ENUM | No | +x | +x, +y, -x, -y | | animate\_in\_place | BOOLEAN | No | false | Export animation in place | Output: STRING model\_file. Common failures: unsupported conversion for the source task, invalid export settings, or API/output move failure. Minimum connection: any compatible MODEL\_INFO → TripoConvertNode. ## Workflow examples Preview 3D is shown as an optional ComfyUI viewer and is not included in the Tripo node count. ~~~mermaid flowchart LR T\["Text"\] --> GT\["Generate model
mode: text\_to\_model"\] IM\["Image"\] --> GI\["Generate model
mode: image\_to\_model"\] MV\["Front + optional views"\] --> GM\["Generate model
mode: multiview\_to\_model"\] GT --> V\["Preview 3D"\] GI --> V GM --> V ~~~ 1. \*\*Text to Model:\*\* provide prompt, select text\_to\_model, then send model\_file to Preview 3D. 2. \*\*Image to Model:\*\* connect an IMAGE to image, select image\_to\_model, then preview model\_file. 3. \*\*Multiview to Model:\*\* connect the front image to image and optional views to image\_left, image\_back, and image\_right. 4. \*\*Texture Model:\*\* Generate or Import → connect MODEL\_INFO to Texture → preview the new model\_file. 5. \*\*Refine Model:\*\* Generate a compatible draft → connect MODEL\_INFO to Refine → preview the refined file. 6. \*\*Rig and Retarget:\*\* Generate or Import → Rig → Retarget; use MODEL\_INFO for both links, then preview or Convert. 7. \*\*Import and Process:\*\* local file or URL → Import → Segment/Smart low poly/Stylize/Texture. Import returns context, not a preview file. 8. \*\*Convert and Export:\*\* connect the final MODEL\_INFO from Generate, Import, processing, Rig, or Retarget to Convert and choose the output format. ### Official workflow PNGs The six PNG files below contain embedded ComfyUI workflow data. Save an original PNG with its download link, then drag it into ComfyUI or load it manually. Values visible in the images are workflow examples; use the parameter tables above for current defaults. #### Text to Mesh !\[ComfyUI text-to-mesh workflow connecting Tripo Generate model to Preview 3D\](/assets/images/docs/comfyui-nodes/text\_to\_model.png) Generate a model from a text prompt and send model\_file to Preview 3D. Download the original workflow PNG #### Image to Mesh !\[ComfyUI image-to-mesh workflow connecting Load Image, Tripo Generate model, and Preview 3D\](/assets/images/docs/comfyui-nodes/image\_to\_model.png) Load an image, connect it to Generate model in image\_to\_model mode, and preview the result. Download the original workflow PNG #### Multiview Images to Mesh !\[ComfyUI multiview workflow connecting three Load Image nodes to Tripo Generate model and Preview 3D\](/assets/images/docs/comfyui-nodes/multiview\_to\_model.png) Connect the front and optional side views to Generate model in multiview\_to\_model mode. Download the original workflow PNG #### Texture a generated model !\[ComfyUI workflow connecting Generate model to Texture model with before and after Preview 3D nodes\](/assets/images/docs/comfyui-nodes/texture\_model.png) Pass MODEL\_INFO from Generate model to Texture model and preview both outputs. Download the original workflow PNG #### Refine a draft Mesh !\[ComfyUI workflow connecting a draft Generate model task to Refine Draft model and Preview 3D\](/assets/images/docs/comfyui-nodes/refine\_model.png) Generate a compatible draft, pass its MODEL\_INFO to Refine Draft model, and preview the refined file. Download the original workflow PNG #### Animation / Rig and export !\[ComfyUI workflow connecting Generate model, Rig model, Preview 3D, and Convert model\](/assets/images/docs/comfyui-nodes/retarget.png) Download the original workflow PNG ## Output and troubleshooting By default, downloaded models are written to ComfyUI/output. Generate and Import establish file\_prefix and output\_directory; that metadata is propagated through downstream MODEL\_INFO. A non-empty prefix is prepended to the downloaded filename. A non-empty directory moves the downloaded file to that directory and creates it when needed. | Symptom | Check | | --- | --- | | TRIPO API key is required | Set a non-empty node key, TRIPO\_API\_KEY, or the field in config.json. | | Prompt/front image is required | Match mode with its conditionally required input. | | Import does not start | Provide a reachable model\_url or an existing model\_file; URL has priority. | | Model cannot be rigged | Try a suitable character model; Rig stops when the riggable check fails or returns no rig type. | | API task fails | Read the reported error\_code and error\_msg; also verify account access and balance. | | Output cannot be moved | Check that output\_directory is valid and writable and that the source file still exists. | | Nodes do not appear | Restart ComfyUI, verify the repository directory, and install requirements.txt. | | Import upload button fails | Verify the extension listed by the upload control and inspect the ComfyUI upload response. | ComfyUI Nodes ============= ComfyUI-Tripo is Tripo’s official custom-node extension for ComfyUI. It supports generating 3D models from text, a single image, or multiview images within ComfyUI workflows, along with model import, texturing, refinement, mesh processing, low-poly optimization, stylization, rigging, animation retargeting, format conversion, and retopology. | Item | Value | | --- | --- | | Node package version | `1.3.0` | | Source tag | `v1.3.1.1` | | Source | [VAST-AI-Research/ComfyUI-Tripo](https://github.com/VAST-AI-Research/ComfyUI-Tripo) | Capabilities and changelog -------------------------- ### Capabilities * Generate 3D models from text prompts. * Generate 3D models from images. * Import models from a URL through `model_url`. * Support splitting models into separate parts. * Rig and animate 3D models. * Convert formats and retopologize models. ### Changelog * 2026-06-30: added Mesh Segmentation v2.0 for splitting models into separate parts and direct URL import through `model_url`. * 2026-05-28: added model import. * 2025-06-19: updated to the newest API and added more nodes. * 2025-03-31: switched to the `tripo3d` package. * 2025-02-24: removed `glbviewer`. * 2025-02-01: adapted to the new API and switched model viewing to Preview 3D. * 2024-11-11: adapted to the new API. * 2024-10-14: added model conversion. * 2024-09-13: added support for `model_version` `v2.0-20240919`. Installation ------------ **Choose one** method, then restart ComfyUI. ### ComfyUI-Manager Open [Custom Nodes Manager](https://github.com/ltdrdata/ComfyUI-Manager) , search for `Tripo for ComfyUI`, and install it. ### comfy-cli Install [comfy-cli](https://github.com/Comfy-Org/comfy-cli) through [Comfy Registry](https://registry.comfy.org/) , then run: BashCopy comfy node registry-install comfyui-tripo ### From source Place the repository in `ComfyUI/custom_nodes/ComfyUI-Tripo`, then install its dependencies: BashCopy cd ComfyUI/custom_nodes git clone https://github.com/VAST-AI-Research/ComfyUI-Tripo.git python -m pip install -r ComfyUI-Tripo/requirements.txt API key configuration --------------------- Create an API key on the [Tripo platform](https://platform.tripo3d.ai/) , then configure it with one of the methods below. The node package resolves an API key in this order: 1. A non-empty `apikey` input on the node. 2. The `TRIPO_API_KEY` environment variable. 3. `config.json` in the ComfyUI-Tripo directory, with a `TRIPO_API_KEY` field. The Generate and Import nodes expose `apikey`. Downstream nodes receive the resolved key through `MODEL_INFO`. Do not expose a real API key in screenshots, shared workflows, logs, or source repositories. Clear the `apikey` field before sharing a workflow and prefer an environment variable for local use. ### Environment variable launch examples Windows: ShellCopy set TRIPO_API_KEY=tsk_XXXXXXX python.exe main.py [--cpu] Linux or macOS: BashCopy TRIPO_API_KEY=tsk_XXXXXXX python main.py [--cpu] Node overview ------------- ComfyUI-Tripo provides the following 11 Tripo nodes: | Internal ID | Display name | Capability | Output | | --- | --- | --- | --- | | `TripoAPIDraft` | Tripo: Generate model | Generate from text, image, or multiple views | `model_file`, `MODEL_INFO` | | `TripoImportModel` | Tripo: Import model | Import a local model or model URL | `MODEL_INFO` | | `TripoTextureModel` | Tripo: Texture model | Texture a model | `model_file`, `MODEL_INFO` | | `TripoRefineModel` | Tripo: Refine Draft model | Refine a draft model | `model_file`, `MODEL_INFO` | | `TripoMeshSegmentation` | Tripo: Segment mesh | Segment a mesh | `model_file`, `MODEL_INFO` | | `TripoMeshCompletion` | Tripo: Complete mesh | Complete a segmented mesh | `model_file`, `MODEL_INFO` | | `TripoSmartLowPoly` | Tripo: Smart low poly | Create a low-poly model | `model_file`, `MODEL_INFO` | | `TripoStylizeModel` | Tripo: Stylize model | Apply a geometric style | `model_file`, `MODEL_INFO` | | `TripoAnimateRigNode` | Tripo: Rig model | Automatically rig a model | `model_file`, `MODEL_INFO` | | `TripoAnimateRetargetNode` | Tripo: Retarget rigged model | Apply a preset animation | `model_file`, `MODEL_INFO` | | `TripoConvertNode` | Tripo: Convert model | Convert and export a model | `model_file` | Preview 3D is provided by ComfyUI and is not one of these 11 nodes. Connections and data flow ------------------------- flowchart LR G["Generate model"] -->|MODEL_INFO| P["Model processing"] I["Import model"] -->|MODEL_INFO| P P -->|MODEL_INFO| R["Rig model"] R -->|MODEL_INFO| A["Retarget rigged model"] A -->|MODEL_INFO| C["Convert model"] * `model_file` is the downloaded path produced by a generation or processing task. It can be sent to a ComfyUI preview or file-handling node. * `MODEL_INFO` contains the Tripo task context used by downstream Tripo nodes: `task_id`, resolved `apikey`, `file_prefix`, and `output_directory`. * A model from outside this node chain must first pass through `TripoImportModel`. A file path alone cannot replace `MODEL_INFO`. * Connect nodes through `MODEL_INFO` when further Tripo processing is required. The `model_file` output is not the processing context. Complete node reference ----------------------- “Required” indicates whether a node parameter must be provided. The `apikey` field may be left empty to use the environment or configuration fallback. A dash means no explicit default is set. ### Generation and import ### TripoAPIDraft — Tripo: Generate model Creates the first Tripo task in a workflow. It has no node prerequisite. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `mode` | ENUM | Yes | first value | `text_to_model`, `image_to_model`, `multiview_to_model` | | `apikey` | STRING | Yes | empty | API key or fallback | | `prompt` | STRING, multiline | No | empty | Text prompt | | `negative_prompt` | STRING, multiline | No | empty | Negative text prompt | | `image` | IMAGE | No | — | Source image; front image in multiview mode | | `image_left` | IMAGE | No | — | Optional left view | | `image_back` | IMAGE | No | — | Optional back view | | `image_right` | IMAGE | No | — | Optional right view | | `model_version` | ENUM | No | `v3.1-20260211` | `v1.4-20240625`, `v2.0-20240919`, `v2.5-20250123`, `v3.0-20250812`, `v3.1-20260211` | | `texture` | BOOLEAN | No | `true` | Enable texture generation | | `pbr` | BOOLEAN | No | `true` | Enable PBR maps | | `image_seed` | INT | No | `42` | Used by text mode | | `model_seed` | INT | No | `42` | Model seed | | `texture_seed` | INT | No | `42` | Texture seed | | `texture_quality` | ENUM | No | `standard` | `standard`, `detailed` | | `geometry_quality` | ENUM | No | `standard` | `standard`, `detailed`; image mode only | | `texture_alignment` | ENUM | No | `original_image` | `original_image`, `geometry` | | `face_limit` | INT | No | `-1` | `-1`–`500000`; values ≤ 0 are sent as unset | | `quad` | BOOLEAN | No | `false` | Request quad topology | | `compress` | BOOLEAN | No | `false` | Compress output | | `generate_parts` | BOOLEAN | No | `false` | Generate parts | | `smart_low_poly` | BOOLEAN | No | `false` | Enable smart low-poly generation | | `auto_size` | BOOLEAN | No | `false` | Automatically size the model | | `orientation` | ENUM | No | `default` | `default`, `align_image`; image and multiview modes | | `file_prefix` | STRING | No | empty | Prefix for the downloaded filename | | `output_directory` | STRING | No | empty | Destination directory override | Mode requirements: | Mode | Conditionally required | Notes | | --- | --- | --- | | `text_to_model` | `prompt` | Fails with “Prompt is required” when empty | | `image_to_model` | `image` | Fails with “Image is required” when absent | | `multiview_to_model` | `image` | `image` is the front view; left, back, and right are optional | Outputs: STRING `model_file` and `MODEL_INFO`. Common failures: missing conditional input, missing/invalid API key, rejected API task, or output move failure. Minimum connection: prompt or image → `TripoAPIDraft` → Preview 3D; use `MODEL_INFO` for later processing. ### TripoImportModel — Tripo: Import model Creates Tripo task context for a model that did not originate in this node chain. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `apikey` | STRING | Yes | empty | API key or fallback | | `model_file` | file selector | No | `none` | Model in the ComfyUI input directory | | `model_url` | STRING | No | empty | Direct URL to a model | | `file_prefix` | STRING | No | empty | Prefix propagated to downstream downloads | | `output_directory` | STRING | No | empty | Directory propagated to downstream downloads | A non-empty `model_url` takes priority over `model_file`. If both are empty, the node fails. The upload control accepts `.glb`, `.fbx`, `.obj`, `.stl`, `.ply`, `.3mf`, and `.gltf`; the backend input scan also recognizes `.zip`. Output: `MODEL_INFO` only. Common failures: neither source is provided, a local file is missing, the URL cannot be fetched, the format is rejected, or the import task fails. Minimum connection: local file or URL → `TripoImportModel` → any processor that accepts `MODEL_INFO`. ### Model processing ### TripoTextureModel — Tripo: Texture model Requires `MODEL_INFO` from Generate, Import, or another compatible processor. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `model_version` | ENUM | No | `v3.0-20250812` | `v2.5-20250123`, `v3.0-20250812` | | `texture` | BOOLEAN | No | `true` | Enable texture | | `pbr` | BOOLEAN | No | `true` | Enable PBR maps | | `texture_seed` | INT | No | `42` | Texture seed | | `texture_quality` | ENUM | No | `standard` | `standard`, `detailed` | | `texture_alignment` | ENUM | No | `original_image` | `original_image`, `geometry` | | `text_prompt` | STRING, multiline | No | empty | Texture guidance text | | `image_prompt` | IMAGE | No | — | Texture reference | | `style_image` | IMAGE | No | — | Style reference | | `part_names` | STRING, multiline | No | empty | One part name per line | | `compress` | BOOLEAN | No | `false` | Compress output | | `bake` | BOOLEAN | No | `true` | Bake texture | Outputs: STRING `model_file` and `MODEL_INFO`. Common failures: incompatible task context, invalid reference image, or API task failure. Minimum connection: Generate/Import `MODEL_INFO` → `TripoTextureModel` → Preview 3D or another processor. ### TripoRefineModel — Tripo: Refine Draft model | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Draft-model task context | Outputs: STRING `model_file` and `MODEL_INFO`. The upstream task must be a refinable draft; an incompatible task or failed API task causes failure. Minimum connection: Generate draft `MODEL_INFO` → `TripoRefineModel` → Preview 3D. ### TripoMeshSegmentation — Tripo: Segment mesh | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `model_version` | ENUM | Yes | `v1.0-20250506` | `v1.0-20250506`, `v2.0-20260430` | | `segmentation_granularity` | ENUM | No | `balanced` | `simple`, `balanced`, `detailed` | | `ref_image` | IMAGE | No | — | Segmentation reference image | | `split_by_connectivity` | BOOLEAN | No | `true` | Split disconnected geometry | `segmentation_granularity`, `ref_image`, and `split_by_connectivity` are sent only with `v2.0-20260430`; v1 ignores them. Outputs: STRING `model_file` and `MODEL_INFO`. Common failures: incompatible model, invalid reference image, or API task failure. Minimum connection: Generate/Import `MODEL_INFO` → `TripoMeshSegmentation` → Completion or Preview 3D. ### TripoMeshCompletion — Tripo: Complete mesh | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Segmented-model task context | | `model_version` | ENUM | Yes | `v1.0-20250506` | `v1.0-20250506` | | `part_names` | STRING, multiline | No | empty | One part name per line | Outputs: STRING `model_file` and `MODEL_INFO`. A task that is not suitable for completion or a failed API task causes failure. Minimum connection: Segment `MODEL_INFO` → `TripoMeshCompletion` → Preview 3D. ### TripoSmartLowPoly — Tripo: Smart low poly | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `model_version` | ENUM | Yes | `P-v2.0-20251225` | `P-v2.0-20251225` | | `quad` | BOOLEAN | No | `false` | Request quad topology | | `part_names` | STRING, multiline | No | empty | One part name per line | | `face_limit` | INT | No | `10000` | `-1`–`20000` | | `bake` | BOOLEAN | No | `true` | Bake output | Outputs: STRING `model_file` and `MODEL_INFO`. Common failures: incompatible model/parts or API task failure. Minimum connection: Generate/Import `MODEL_INFO` → `TripoSmartLowPoly` → Preview 3D or Convert. ### TripoStylizeModel — Tripo: Stylize model | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `style` | ENUM | Yes | first value | `lego`, `voxel`, `voronoi`, `minecraft` | | `block_size` | INT | Yes | `80` | `1`–`1000` | Outputs: STRING `model_file` and `MODEL_INFO`. Common failures: incompatible model, unsupported style for the task, or API task failure. Minimum connection: Generate/Import `MODEL_INFO` → `TripoStylizeModel` → Preview 3D. ### Rigging and animation ### TripoAnimateRigNode — Tripo: Rig model The node checks whether the model is riggable and obtains a rig type before submitting the rig task. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `model_version` | ENUM | Yes | `v2.0-20250506` | `v1.0-20240301`, `v2.0-20250506` | | `out_format` | ENUM | Yes | `glb` | `glb`, `fbx` | | `spec` | ENUM | Yes | `tripo` | `mixamo`, `tripo` | Outputs: STRING `model_file` and `MODEL_INFO`. It fails when the model cannot be rigged, no suitable rig type is found, or the API task fails. Minimum connection: Generate/Import `MODEL_INFO` → `TripoAnimateRigNode` → Retarget or Preview 3D. ### TripoAnimateRetargetNode — Tripo: Retarget rigged model Requires `MODEL_INFO` from a successfully rigged model. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Rigged-model task context | | `animation` | ENUM | Yes | first value | See all 16 presets below | | `out_format` | ENUM | Yes | `glb` | `glb`, `fbx` | | `bake_animation` | BOOLEAN | No | `true` | Bake the animation | | `export_with_geometry` | BOOLEAN | No | `false` | Include geometry in export | The 16 animation values are: `preset:idle`, `preset:walk`, `preset:run`, `preset:dive`, `preset:climb`, `preset:jump`, `preset:slash`, `preset:shoot`, `preset:hurt`, `preset:fall`, `preset:turn`, `preset:quadruped:walk`, `preset:hexapod:walk`, `preset:octopod:walk`, `preset:serpentine:march`, and `preset:aquatic:march`. Outputs: STRING `model_file` and `MODEL_INFO`. An unrigged/incompatible task or failed API task causes failure. Minimum connection: Rig `MODEL_INFO` → `TripoAnimateRetargetNode` → Preview 3D or Convert. ### Format output ### TripoConvertNode — Tripo: Convert model This is an output node and returns no `MODEL_INFO`. | Input | Type | Required | Default | Values or range | | --- | --- | --- | --- | --- | | `model_info` | MODEL\_INFO | Yes | — | Upstream task context | | `format` | ENUM | Yes | first value | `GLTF`, `USDZ`, `FBX`, `OBJ`, `STL`, `3MF` | | `quad` | BOOLEAN | No | `false` | Request quad topology | | `force_symmetry` | BOOLEAN | No | `false` | Force symmetry | | `face_limit` | INT | No | `-1` | `-1`–`500000` | | `flatten_bottom` | BOOLEAN | No | `false` | Flatten the bottom | | `flatten_bottom_threshold` | FLOAT | No | `0.01` | `0.0`–`1.0` | | `texture_size` | INT | No | `4096` | `128`–`4096` | | `texture_format` | ENUM | No | `JPEG` | `BMP`, `DPX`, `HDR`, `JPEG`, `OPEN_EXR`, `PNG`, `TARGA`, `TIFF`, `WEBP` | | `pivot_to_center_bottom` | BOOLEAN | No | `false` | Move pivot to center-bottom | | `scale_factor` | FLOAT | No | `1.0` | Minimum `0` | | `with_animation` | BOOLEAN | No | `true` | Preserve animation | | `pack_uv` | BOOLEAN | No | `false` | Pack UVs | | `bake` | BOOLEAN | No | `true` | Bake output | | `part_names` | STRING, multiline | No | empty | One part name per line | | `fbx_preset` | ENUM | No | `blender` | `blender`, `mixamo`, `3dsmax` | | `export_vertex_colors` | BOOLEAN | No | `false` | Export vertex colors | | `export_orientation` | ENUM | No | `+x` | `+x`, `+y`, `-x`, `-y` | | `animate_in_place` | BOOLEAN | No | `false` | Export animation in place | Output: STRING `model_file`. Common failures: unsupported conversion for the source task, invalid export settings, or API/output move failure. Minimum connection: any compatible `MODEL_INFO` → `TripoConvertNode`. Workflow examples ----------------- Preview 3D is shown as an optional ComfyUI viewer and is not included in the Tripo node count. flowchart LR T["Text"] --> GT["Generate model
mode: text_to_model"] IM["Image"] --> GI["Generate model
mode: image_to_model"] MV["Front + optional views"] --> GM["Generate model
mode: multiview_to_model"] GT --> V["Preview 3D"] GI --> V GM --> V 1. **Text to Model:** provide `prompt`, select `text_to_model`, then send `model_file` to Preview 3D. 2. **Image to Model:** connect an IMAGE to `image`, select `image_to_model`, then preview `model_file`. 3. **Multiview to Model:** connect the front image to `image` and optional views to `image_left`, `image_back`, and `image_right`. 4. **Texture Model:** Generate or Import → connect `MODEL_INFO` to Texture → preview the new `model_file`. 5. **Refine Model:** Generate a compatible draft → connect `MODEL_INFO` to Refine → preview the refined file. 6. **Rig and Retarget:** Generate or Import → Rig → Retarget; use `MODEL_INFO` for both links, then preview or Convert. 7. **Import and Process:** local file or URL → Import → Segment/Smart low poly/Stylize/Texture. Import returns context, not a preview file. 8. **Convert and Export:** connect the final `MODEL_INFO` from Generate, Import, processing, Rig, or Retarget to Convert and choose the output format. ### Official workflow PNGs The six PNG files below contain embedded ComfyUI workflow data. Save an original PNG with its download link, then drag it into ComfyUI or load it manually. Values visible in the images are workflow examples; use the parameter tables above for current defaults. #### Text to Mesh ![ComfyUI text-to-mesh workflow connecting Tripo Generate model to Preview 3D](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/text_to_model.png) Generate a model from a text prompt and send `model_file` to Preview 3D. [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/text_to_model.png) #### Image to Mesh ![ComfyUI image-to-mesh workflow connecting Load Image, Tripo Generate model, and Preview 3D](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/image_to_model.png) Load an image, connect it to Generate model in `image_to_model` mode, and preview the result. [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/image_to_model.png) #### Multiview Images to Mesh ![ComfyUI multiview workflow connecting three Load Image nodes to Tripo Generate model and Preview 3D](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/multiview_to_model.png) Connect the front and optional side views to Generate model in `multiview_to_model` mode. [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/multiview_to_model.png) #### Texture a generated model ![ComfyUI workflow connecting Generate model to Texture model with before and after Preview 3D nodes](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/texture_model.png) Pass `MODEL_INFO` from Generate model to Texture model and preview both outputs. [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/texture_model.png) #### Refine a draft Mesh ![ComfyUI workflow connecting a draft Generate model task to Refine Draft model and Preview 3D](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/refine_model.png) Generate a compatible draft, pass its `MODEL_INFO` to Refine Draft model, and preview the refined file. [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/refine_model.png) #### Animation / Rig and export ![ComfyUI workflow connecting Generate model, Rig model, Preview 3D, and Convert model](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/retarget.png) [Download the original workflow PNG](https://developers.tripo3d.ai/assets/images/docs/comfyui-nodes/retarget.png) Output and troubleshooting -------------------------- By default, downloaded models are written to `ComfyUI/output`. Generate and Import establish `file_prefix` and `output_directory`; that metadata is propagated through downstream `MODEL_INFO`. A non-empty prefix is prepended to the downloaded filename. A non-empty directory moves the downloaded file to that directory and creates it when needed. | Symptom | Check | | --- | --- | | `TRIPO API key is required` | Set a non-empty node key, `TRIPO_API_KEY`, or the field in `config.json`. | | Prompt/front image is required | Match `mode` with its conditionally required input. | | Import does not start | Provide a reachable `model_url` or an existing `model_file`; URL has priority. | | Model cannot be rigged | Try a suitable character model; Rig stops when the riggable check fails or returns no rig type. | | API task fails | Read the reported `error_code` and `error_msg`; also verify account access and balance. | | Output cannot be moved | Check that `output_directory` is valid and writable and that the source file still exists. | | Nodes do not appear | Restart ComfyUI, verify the repository directory, and install `requirements.txt`. | | Import upload button fails | Verify the extension listed by the upload control and inspect the ComfyUI upload response. | PreviousPluginsNextTripo CLI On this page --- # Tripo CLI — Tripo Developers Tripo CLI: Let AI Turn Text and Images into 3D Models ===================================================== CopyDownload PDF \# Tripo CLI: Let AI Turn Text and Images into 3D Models Tripo CLI is built for AI agents, making 3D creation as simple as chatting. Whether you are working in an AI coding tool such as Codex, Claude Code, or Cursor, or using the CLI directly, a single natural-language description, an image, or an existing model is all it takes to generate or transform 3D models, animations, and other assets. The CLI completes the entire workflow automatically—no need to understand APIs, model versions, or complex parameters. ## Should I use the CLI or the API? Tripo comes in two flavors—take ten seconds to pick the right one: | Product | Best for | Where to go | | --- | --- | --- | | \*\*Tripo CLI (this page)\*\* | Beginners: quickly tap into AI 3D capabilities through popular vibe coding tools | Keep reading | | \*\*Tripo API\*\* | Professional developers: integrate AI 3D capabilities into websites, apps, or your own business systems | \[Quick start\](/en/docs/quick-start) | Not sure? Just try this page first: installing is free, and credits are only spent when you actually generate a model. ## Install and sign in (pick one of two paths) Pick one of the two installation paths below. ### Path one: let AI install it for me (recommended) If you already use Cursor, Claude Code, Codex, or another AI assistant that can run terminal commands, this is the easiest path. Copy the prompt below and send it to your assistant in full: \`\`\`text Set up Tripo CLI for me and explain each step. Check that Node.js 20 or later is installed, then run npm install -g tripo-cli. If this is Windows PowerShell and running scripts is disabled, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (not as Administrator) and retry. Ask me to complete tripo login in the browser; do not ask me to paste an API key into chat. Finally, run tripo doctor and tell me whether authentication, network access, and balance checks pass. \`\`\` What happens next: 1. The AI checks your computer and helps you install Node.js first if it is missing; 2. The AI runs the install command; 3. Your turn: a browser window opens the Tripo sign-in page—sign in and approve the verification code shown in your terminal (this step must be done by you; never send any key to the AI); 4. The AI runs \`tripo doctor\`; once every check passes, setup is complete. Then jump straight to the next section, "Create your first 3D model".
Trouble? The AI got stuck or hit an error - Paste the terminal error back to the AI as-is and let it continue; it can solve most problems; - Sign-in did not complete: reopen the sign-in page and double-check the verification code shown in your terminal before approving; - If nothing works, fall back to "Path two: install it myself" below—it is only three commands.
### Path two: install it myself No AI assistant? No problem—the whole process is three commands. \*\*Step 1: install Tripo CLI\*\* This command installs the \`tripo\` command on your computer: \`\`\`bash npm install -g tripo-cli \`\`\` Normally the progress finishes without red error text, which means the install succeeded.
Trouble? npm not found, or a permissions error - \`npm\` not found: Node.js is not installed yet. Install the current LTS version (20 or later) from the \[Node.js website\](https://nodejs.org/), then reopen the terminal and try again; - Permission error on macOS (EACCES): run \`sudo npm install -g tripo-cli\` instead and enter your computer password when asked; - Windows says "running scripts is disabled": run \`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned\` in PowerShell (Administrator is not required), reopen the terminal, and try again. More examples are in "Windows / PowerShell" below.
\*\*Step 2: sign in to your Tripo account\*\* \`\`\`bash tripo login \`\`\` Your browser opens an authorization page automatically (register there first if you do not have an account yet). The page shows a verification code—\*\*approve it only after confirming it matches the code shown in your terminal.\*\* After signing in, the terminal confirms you are logged in. !\[Tripo CLI browser device-authorization page with a verification code\](/assets/images/docs/cli/device-authorization-en.webp)
Trouble? The browser did not open, or sign-in did not complete - Sign-in did not complete: run \`tripo login\` again, and approve only after double-checking the code shown in your terminal; - The browser never reacts: copy the URL printed in the terminal into your browser manually; - Browser authorization is temporarily unavailable: the CLI opens the API key page instead—see "Backup sign-in and regions" at the end of this section.
\*\*Step 3: check that everything is ready\*\* \`\`\`bash tripo doctor \`\`\` It checks your sign-in status, network access, and credit balance in turn. When all three pass, setup is complete.
Trouble? One of the checks failed - Authentication failed: sign-in did not complete—run \`tripo login\` and sign in again; - Network failed: confirm your computer can open web pages; corporate or campus networks may need a proxy; - Balance failed: you do not have enough credits; nothing has started generating and nothing is charged. Run \`tripo topup\` to open the billing page.
Backup sign-in and regions (only if browser sign-in is unavailable) - If you already have an API key, run \`tripo login --key tsk\_...\`, or set the \`TRIPO\_API\_KEY\` environment variable; - An API key is an account credential: never paste it into chat, source code, screenshots, or logs; - The same installation works for both international and China mainland accounts: the CLI probes both regions with your key and saves the accepted region automatically.
## Windows / PowerShell Commands on this page are shown as Bash. They also run on Windows; PowerShell just parses a few tokens differently from Bash or cURL. Use the examples below in PowerShell instead of copying the Bash blocks as-is. \*\*Allow \`tripo\` to run\*\* npm installs a \`tripo.ps1\` shim that PowerShell blocks by default: \`\`\`powershell Set-ExecutionPolicy -Scope CurrentUser RemoteSigned \`\`\` Reopen the terminal and run \`tripo doctor\`. Administrator rights are not required. Prefer not to change the policy? Use Command Prompt (\`cmd.exe\`) instead. \*\*Quote \`@last\` and comma-separated flags\*\* PowerShell treats \`@name\` as special syntax and \`,\` as a list separator: \`\`\`powershell tripo make "a cute low poly fox" tripo view '@last' tripo make hero.glb --then 'texture,rig' tripo make '@last' --then 'convert:fbx' \`\`\` Command Prompt does not need these extra quotes. \*\*Environment variables\*\* \`\`\`powershell # Current window only $env:TRIPO\_API\_KEY = "tsk\_..." $env:TRIPO\_PROFILE = "work-cn" # Persist for your Windows user \[System.Environment\]::SetEnvironmentVariable("TRIPO\_API\_KEY", "tsk\_...", "User") \`\`\` Config and history live in \`%USERPROFILE%\\.tripo\` (the Windows equivalent of \`~/.tripo\`). \*\*JSON pipelines\*\* \`\`\`powershell # PowerShell 7+ (recommended) tripo make cat.png --json | tripo model texture --json | tripo anim rig --json # Windows PowerShell 5.1 $json = tripo make cat.png --json --no-open $json | tripo model texture --json \`\`\` If a non-English prompt looks garbled, use \[Windows Terminal\](https://aka.ms/terminal) or run \`chcp 65001\` first. ## Create your first 3D model \*\*Step 1: generate from one sentence\*\* The words inside the quotation marks are your prompt—replace them with whatever you want to create: \`\`\`bash tripo make "a cute low poly fox" \`\`\` Keep the terminal open while the command runs. Tripo CLI picks the right workflow and model, waits for the task to finish, and downloads the files into a \`tripo-out\` folder in the current directory. The whole run usually finishes within a few minutes and costs a small amount of credits.
Trouble? Generation did not start, or failed midway - Insufficient credits: your model has not started generating and nothing is charged. Run \`tripo topup\` to add credits, then retry; - Network error: make sure your computer is online, then run the same command again; - Task failed: any charged credits are refunded automatically—try a different description.
\*\*Step 2: open the preview\*\* \`\`\`bash tripo view @last \`\`\` \`@last\` means "the most recent task." Your browser opens an interactive 3D preview you can rotate by dragging—when you see your model, you made it! In PowerShell, write \`tripo view '@last'\`. \*\*After the first success: what you have now\*\* - \*\*Where the files are\*\*: a new folder under \`tripo-out\` holds the downloaded 3D model and \`task.json\`, which records how the task was created; if the server provides a preview image you also get \`preview.png\`. - \*\*Open it again\*\*: run \`tripo view @last\` any time, or \`tripo view \` to open any model file. - \*\*What it cost\*\*: run \`tripo balance\` to check your credit balance. - \*\*Hate memorizing commands?\*\* Just run \`tripo\` to open a guided interactive menu—sign-in, generation, preview, and top-up all live there. - \*\*Next steps\*\*: generate from images (next section), let an AI assistant drive ("Let AI coding agents master the CLI"), or process in bulk ("Ready-made workflows and pipelines"). ## Generate from an image or an existing model Once the text example works, you can pass local files instead. \`concept.png\`, \`front.png\`, and \`hero.glb\` below are example names—replace them with your own file paths: \`\`\`bash tripo make concept.png --for print tripo make front.png back.png tripo make hero.glb --then texture,rig tripo make @last --then convert:fbx \`\`\` - Line 1: turn a concept image into a print-ready model; - Line 2: generate from front and back images together for more accurate detail; - Line 3: texture and rig an existing model; - Line 4: convert the most recent result to FBX. ## Let AI coding agents master the CLI If you use \*\*Codex\*\*, start with the \[Tripo 3D Codex plugin\](/en/docs/codex-plugin) instead: you talk in plain language and do not run CLI commands yourself. Skip this section if you do not use an AI coding agent. The npm package bundles an Agent Skill—command references, scenario recipes, and error-recovery guidance—so an agent can use the CLI correctly. Have the agent run these commands to print the full instructions or a single topic in the terminal: \`\`\`bash tripo docs --llm tripo docs --topic commands/make tripo docs --topic examples/game-asset \`\`\`
Files bundled in the Skill \`\`\`text skill/ ├── SKILL.md ├── common-errors.md ├── commands/ │ ├── account.md │ ├── batch.md │ ├── generate.md │ ├── make.md │ ├── process.md │ ├── task.md │ └── view.md └── examples/ ├── animation.md ├── ar-web.md ├── film.md ├── game-asset.md ├── pipes.md └── print.md \`\`\`
## Command reference No need to memorize this table: day to day, new users only need \`tripo\` (interactive menu), \`tripo make\` (generate), \`tripo view\` (preview), and \`tripo doctor\` (health check). Expand the rest only when a specific need comes up.
Show the full command table and common flags | Command | What it does | | --- | --- | | \`tripo make \` | Generate, process, and download with one command | | \`tripo ai \[description\]\` | Plan a job, confirm it, and execute it | | \`tripo view \[task\\|file\]\` | Open an interactive local 3D preview | | \`tripo redo \[task\]\` | Repeat a request with a fresh seed | | \`tripo login / logout / whoami / use\` | Authorize and switch named account profiles | | \`tripo topup / balance / usage\` | Open regional billing and inspect credits | | \`tripo generate \` | Access all eight generation endpoints explicitly | | \`tripo model / anim / mesh \` | Run refine, texture, rig, convert, segmentation, and other processing steps | | \`tripo task get/list/watch\` | Query, list, or wait for tasks | | \`tripo history \[--limit \]\` | Show recent local task history | | \`tripo files upload \` | Upload a file and return its \`file\_token\` | | \`tripo batch run \` | Run resumable bulk pipelines with concurrency and retries | | \`tripo config / doctor\` | Manage settings and diagnose the local environment | | \`tripo docs \[--topic \]\` | Print the bundled Agent and command documentation | | \`tripo mcp\` | Run the CLI as an MCP server | | \`tripo completion \` | Generate completion for Bash, Zsh, or Fish (not PowerShell) | The \`make\`, \`ai\`, and \`generate\` commands, plus the processing subcommands under \`model\`, \`anim\`, and \`mesh\`, support \`-o/--out\`, \`--no-wait\`, \`--no-download\`, \`--name\`, \`--timeout\`, \`--notify\`, and repeatable \`--param key=value\`. Global automation flags include \`--json\`, \`--yes\`, \`--quiet\`, \`--no-open\`, and \`--profile\`.
## Ready-made workflows and pipelines This is an advanced section; your first generation does not need it. Seven built-in presets apply useful parameters and processing steps at once via \`--for \`: \`game-mobile\` · \`game-pc\` · \`film\` · \`print\` · \`ar-web\` · \`anim\` · \`toy\` \`\`\`bash # Mobile game asset: low-poly generation, texture, then FBX tripo make "sci-fi crate" --for game-mobile # Print asset: watertight output, STL, and a flat bottom tripo make "chess knight" --for print # Explicit processing chain tripo make cat.png --then texture,rig,convert:fbx # The same chain as NDJSON pipes tripo make cat.png --json | tripo model texture --json | tripo anim rig --json # Resumable batch processing tripo batch run assets.yaml --concurrency 2 \`\`\` Task references such as \`@last\`, \`@2\`, and \`@name\` work anywhere a task ID is accepted. ## Multiple accounts and regions Skip this section if you use one Tripo account. Credentials are stored in named profiles, so signing into a second account does not overwrite the first: \`\`\`bash tripo login tripo login --profile work-cn tripo use tripo whoami tripo make "a fox" --profile work-cn tripo logout \`\`\` Each profile keeps its own key and region. The \`TRIPO\_PROFILE\` environment variable selects a profile for the current environment, while \`TRIPO\_API\_KEY\` bypasses all profiles and has the highest priority. ## Notes for AI coding agents Human users can skip this section. These rules help an AI coding agent wait for tasks correctly and read machine-readable output. - \`tripo make\` and \`tripo task watch\` are blocking commands. Wait for the process to finish instead of implementing another polling loop. - With \`--json\`, most one-shot commands write one final JSON line to stdout. \`tripo task watch --json\` instead streams NDJSON progress events followed by the final result. - If \`preview.png\` exists, inspect it before deciding whether to continue a pipeline or run \`tripo redo\`. - Do not invent parameters or force legacy model versions. Use \`tripo docs --topic ...\` for the supported flags. - A low-poly request or face budget of 20,000 or less selects \`tripo-p1\`; other work defaults to \`tripo-v3.1\`.
Show the exit-code table | Exit code | Meaning | | --- | --- | | \`0\` | Success | | \`1\` | Unexpected or internal error | | \`2\` | Invalid usage or parameters | | \`3\` | Authentication error | | \`4\` | Insufficient credits | | \`5\` | Content policy rejection | | \`6\` | Task failed; credits are automatically refunded | | \`7\` | Network error | | \`8\` | Resource not found | | \`9\` | Rate limited; retry with backoff |
## Environment variables for automation You do not need environment variables for normal interactive use; they exist for CI, scripts, and advanced agent workflows. Remember: never commit an API key to a repository, paste it into documentation, or include it in screenshots or logs.
Show the environment-variable table | Variable | Purpose | | --- | --- | | \`TRIPO\_API\_KEY\` | API key; highest precedence and suitable for CI or Agents | | \`TRIPO\_PROFILE\` | Named account profile, equivalent to \`--profile\` | | \`TRIPO\_REGION\` | Optional \`ov\` or \`cn\` override; normally auto-detected | | \`TRIPO\_API\_BASE\_URL\` | API endpoint override | | \`TRIPO\_PLATFORM\_BASE\_URL\` | Platform endpoint override | | \`TRIPO\_HOME\` | Config and history directory; defaults to \`~/.tripo\` | | \`TRIPO\_LLM\_BASE\_URL\` | Optional OpenAI-compatible endpoint for \`tripo ai\` | | \`TRIPO\_LLM\_API\_KEY\` | Optional LLM key for \`tripo ai\` | | \`TRIPO\_LLM\_MODEL\` | Optional LLM model for \`tripo ai\` |
Tripo CLI: Let AI Turn Text and Images into 3D Models ===================================================== Tripo CLI is built for AI agents, making 3D creation as simple as chatting. Whether you are working in an AI coding tool such as Codex, Claude Code, or Cursor, or using the CLI directly, a single natural-language description, an image, or an existing model is all it takes to generate or transform 3D models, animations, and other assets. The CLI completes the entire workflow automatically—no need to understand APIs, model versions, or complex parameters. Should I use the CLI or the API? -------------------------------- Tripo comes in two flavors—take ten seconds to pick the right one: | Product | Best for | Where to go | | --- | --- | --- | | **Tripo CLI (this page)** | Beginners: quickly tap into AI 3D capabilities through popular vibe coding tools | Keep reading | | **Tripo API** | Professional developers: integrate AI 3D capabilities into websites, apps, or your own business systems | [Quick start](https://developers.tripo3d.ai/en/docs/quick-start) | Not sure? Just try this page first: installing is free, and credits are only spent when you actually generate a model. Install and sign in (pick one of two paths) ------------------------------------------- Pick one of the two installation paths below. ### Path one: let AI install it for me (recommended) If you already use Cursor, Claude Code, Codex, or another AI assistant that can run terminal commands, this is the easiest path. Copy the prompt below and send it to your assistant in full: Copy Set up Tripo CLI for me and explain each step. Check that Node.js 20 or later is installed, then run npm install -g tripo-cli. If this is Windows PowerShell and running scripts is disabled, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (not as Administrator) and retry. Ask me to complete tripo login in the browser; do not ask me to paste an API key into chat. Finally, run tripo doctor and tell me whether authentication, network access, and balance checks pass. What happens next: 1. The AI checks your computer and helps you install Node.js first if it is missing; 2. The AI runs the install command; 3. Your turn: a browser window opens the Tripo sign-in page—sign in and approve the verification code shown in your terminal (this step must be done by you; never send any key to the AI); 4. The AI runs `tripo doctor`; once every check passes, setup is complete. Then jump straight to the next section, “Create your first 3D model”. **Trouble?** The AI got stuck or hit an error * Paste the terminal error back to the AI as-is and let it continue; it can solve most problems; * Sign-in did not complete: reopen the sign-in page and double-check the verification code shown in your terminal before approving; * If nothing works, fall back to “Path two: install it myself” below—it is only three commands. ### Path two: install it myself No AI assistant? No problem—the whole process is three commands. **Step 1: install Tripo CLI** This command installs the `tripo` command on your computer: BashCopy npm install -g tripo-cli Normally the progress finishes without red error text, which means the install succeeded. **Trouble?** npm not found, or a permissions error * `npm` not found: Node.js is not installed yet. Install the current LTS version (20 or later) from the [Node.js website](https://nodejs.org/) , then reopen the terminal and try again; * Permission error on macOS (EACCES): run `sudo npm install -g tripo-cli` instead and enter your computer password when asked; * Windows says “running scripts is disabled”: run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` in PowerShell (Administrator is not required), reopen the terminal, and try again. More examples are in “Windows / PowerShell” below. **Step 2: sign in to your Tripo account** BashCopy tripo login Your browser opens an authorization page automatically (register there first if you do not have an account yet). The page shows a verification code—**approve it only after confirming it matches the code shown in your terminal.** After signing in, the terminal confirms you are logged in. ![Tripo CLI browser device-authorization page with a verification code](https://developers.tripo3d.ai/assets/images/docs/cli/device-authorization-en.webp) **Trouble?** The browser did not open, or sign-in did not complete * Sign-in did not complete: run `tripo login` again, and approve only after double-checking the code shown in your terminal; * The browser never reacts: copy the URL printed in the terminal into your browser manually; * Browser authorization is temporarily unavailable: the CLI opens the API key page instead—see “Backup sign-in and regions” at the end of this section. **Step 3: check that everything is ready** BashCopy tripo doctor It checks your sign-in status, network access, and credit balance in turn. When all three pass, setup is complete. **Trouble?** One of the checks failed * Authentication failed: sign-in did not complete—run `tripo login` and sign in again; * Network failed: confirm your computer can open web pages; corporate or campus networks may need a proxy; * Balance failed: you do not have enough credits; nothing has started generating and nothing is charged. Run `tripo topup` to open the billing page. **Backup sign-in and regions** (only if browser sign-in is unavailable) * If you already have an API key, run `tripo login --key tsk_...`, or set the `TRIPO_API_KEY` environment variable; * An API key is an account credential: never paste it into chat, source code, screenshots, or logs; * The same installation works for both international and China mainland accounts: the CLI probes both regions with your key and saves the accepted region automatically. Windows / PowerShell -------------------- Commands on this page are shown as Bash. They also run on Windows; PowerShell just parses a few tokens differently from Bash or cURL. Use the examples below in PowerShell instead of copying the Bash blocks as-is. **Allow `tripo` to run** npm installs a `tripo.ps1` shim that PowerShell blocks by default: PowerShellCopy Set-ExecutionPolicy -Scope CurrentUser RemoteSigned Reopen the terminal and run `tripo doctor`. Administrator rights are not required. Prefer not to change the policy? Use Command Prompt (`cmd.exe`) instead. **Quote `@last` and comma-separated flags** PowerShell treats `@name` as special syntax and `,` as a list separator: PowerShellCopy tripo make "a cute low poly fox" tripo view '@last' tripo make hero.glb --then 'texture,rig' tripo make '@last' --then 'convert:fbx' Command Prompt does not need these extra quotes. **Environment variables** PowerShellCopy # Current window only $env:TRIPO_API_KEY = "tsk_..." $env:TRIPO_PROFILE = "work-cn" # Persist for your Windows user [System.Environment]::SetEnvironmentVariable("TRIPO_API_KEY", "tsk_...", "User") Config and history live in `%USERPROFILE%\.tripo` (the Windows equivalent of `~/.tripo`). **JSON pipelines** PowerShellCopy # PowerShell 7+ (recommended) tripo make cat.png --json | tripo model texture --json | tripo anim rig --json # Windows PowerShell 5.1 $json = tripo make cat.png --json --no-open $json | tripo model texture --json If a non-English prompt looks garbled, use [Windows Terminal](https://aka.ms/terminal) or run `chcp 65001` first. Create your first 3D model -------------------------- **Step 1: generate from one sentence** The words inside the quotation marks are your prompt—replace them with whatever you want to create: BashCopy tripo make "a cute low poly fox" Keep the terminal open while the command runs. Tripo CLI picks the right workflow and model, waits for the task to finish, and downloads the files into a `tripo-out` folder in the current directory. The whole run usually finishes within a few minutes and costs a small amount of credits. **Trouble?** Generation did not start, or failed midway * Insufficient credits: your model has not started generating and nothing is charged. Run `tripo topup` to add credits, then retry; * Network error: make sure your computer is online, then run the same command again; * Task failed: any charged credits are refunded automatically—try a different description. **Step 2: open the preview** BashCopy tripo view @last `@last` means “the most recent task.” Your browser opens an interactive 3D preview you can rotate by dragging—when you see your model, you made it! In PowerShell, write `tripo view '@last'`. **After the first success: what you have now** * **Where the files are**: a new folder under `tripo-out` holds the downloaded 3D model and `task.json`, which records how the task was created; if the server provides a preview image you also get `preview.png`. * **Open it again**: run `tripo view @last` any time, or `tripo view ` to open any model file. * **What it cost**: run `tripo balance` to check your credit balance. * **Hate memorizing commands?** Just run `tripo` to open a guided interactive menu—sign-in, generation, preview, and top-up all live there. * **Next steps**: generate from images (next section), let an AI assistant drive (“Let AI coding agents master the CLI”), or process in bulk (“Ready-made workflows and pipelines”). Generate from an image or an existing model ------------------------------------------- Once the text example works, you can pass local files instead. `concept.png`, `front.png`, and `hero.glb` below are example names—replace them with your own file paths: BashCopy tripo make concept.png --for print tripo make front.png back.png tripo make hero.glb --then texture,rig tripo make @last --then convert:fbx * Line 1: turn a concept image into a print-ready model; * Line 2: generate from front and back images together for more accurate detail; * Line 3: texture and rig an existing model; * Line 4: convert the most recent result to FBX. Let AI coding agents master the CLI ----------------------------------- If you use **Codex**, start with the [Tripo 3D Codex plugin](https://developers.tripo3d.ai/en/docs/codex-plugin) instead: you talk in plain language and do not run CLI commands yourself. Skip this section if you do not use an AI coding agent. The npm package bundles an Agent Skill—command references, scenario recipes, and error-recovery guidance—so an agent can use the CLI correctly. Have the agent run these commands to print the full instructions or a single topic in the terminal: BashCopy tripo docs --llm tripo docs --topic commands/make tripo docs --topic examples/game-asset **Files bundled in the Skill** skill/ ├── SKILL.md ├── common-errors.md ├── commands/ │ ├── account.md │ ├── batch.md │ ├── generate.md │ ├── make.md │ ├── process.md │ ├── task.md │ └── view.md └── examples/ ├── animation.md ├── ar-web.md ├── film.md ├── game-asset.md ├── pipes.md └── print.md Command reference ----------------- No need to memorize this table: day to day, new users only need `tripo` (interactive menu), `tripo make` (generate), `tripo view` (preview), and `tripo doctor` (health check). Expand the rest only when a specific need comes up. **Show the full command table and common flags** | Command | What it does | | --- | --- | | `tripo make ` | Generate, process, and download with one command | | `tripo ai [description]` | Plan a job, confirm it, and execute it | | `tripo view [task\|file]` | Open an interactive local 3D preview | | `tripo redo [task]` | Repeat a request with a fresh seed | | `tripo login / logout / whoami / use` | Authorize and switch named account profiles | | `tripo topup / balance / usage` | Open regional billing and inspect credits | | `tripo generate ` | Access all eight generation endpoints explicitly | | `tripo model / anim / mesh ` | Run refine, texture, rig, convert, segmentation, and other processing steps | | `tripo task get/list/watch` | Query, list, or wait for tasks | | `tripo history [--limit ]` | Show recent local task history | | `tripo files upload ` | Upload a file and return its `file_token` | | `tripo batch run ` | Run resumable bulk pipelines with concurrency and retries | | `tripo config / doctor` | Manage settings and diagnose the local environment | | `tripo docs [--topic ]` | Print the bundled Agent and command documentation | | `tripo mcp` | Run the CLI as an MCP server | | `tripo completion ` | Generate completion for Bash, Zsh, or Fish (not PowerShell) | The `make`, `ai`, and `generate` commands, plus the processing subcommands under `model`, `anim`, and `mesh`, support `-o/--out`, `--no-wait`, `--no-download`, `--name`, `--timeout`, `--notify`, and repeatable `--param key=value`. Global automation flags include `--json`, `--yes`, `--quiet`, `--no-open`, and `--profile`. Ready-made workflows and pipelines ---------------------------------- This is an advanced section; your first generation does not need it. Seven built-in presets apply useful parameters and processing steps at once via `--for `: `game-mobile` · `game-pc` · `film` · `print` · `ar-web` · `anim` · `toy` BashCopy # Mobile game asset: low-poly generation, texture, then FBX tripo make "sci-fi crate" --for game-mobile # Print asset: watertight output, STL, and a flat bottom tripo make "chess knight" --for print # Explicit processing chain tripo make cat.png --then texture,rig,convert:fbx # The same chain as NDJSON pipes tripo make cat.png --json | tripo model texture --json | tripo anim rig --json # Resumable batch processing tripo batch run assets.yaml --concurrency 2 Task references such as `@last`, `@2`, and `@name` work anywhere a task ID is accepted. Multiple accounts and regions ----------------------------- Skip this section if you use one Tripo account. Credentials are stored in named profiles, so signing into a second account does not overwrite the first: BashCopy tripo login tripo login --profile work-cn tripo use tripo whoami tripo make "a fox" --profile work-cn tripo logout Each profile keeps its own key and region. The `TRIPO_PROFILE` environment variable selects a profile for the current environment, while `TRIPO_API_KEY` bypasses all profiles and has the highest priority. Notes for AI coding agents -------------------------- Human users can skip this section. These rules help an AI coding agent wait for tasks correctly and read machine-readable output. * `tripo make` and `tripo task watch` are blocking commands. Wait for the process to finish instead of implementing another polling loop. * With `--json`, most one-shot commands write one final JSON line to stdout. `tripo task watch --json` instead streams NDJSON progress events followed by the final result. * If `preview.png` exists, inspect it before deciding whether to continue a pipeline or run `tripo redo`. * Do not invent parameters or force legacy model versions. Use `tripo docs --topic ...` for the supported flags. * A low-poly request or face budget of 20,000 or less selects `tripo-p1`; other work defaults to `tripo-v3.1`. **Show the exit-code table** | Exit code | Meaning | | --- | --- | | `0` | Success | | `1` | Unexpected or internal error | | `2` | Invalid usage or parameters | | `3` | Authentication error | | `4` | Insufficient credits | | `5` | Content policy rejection | | `6` | Task failed; credits are automatically refunded | | `7` | Network error | | `8` | Resource not found | | `9` | Rate limited; retry with backoff | Environment variables for automation ------------------------------------ You do not need environment variables for normal interactive use; they exist for CI, scripts, and advanced agent workflows. Remember: never commit an API key to a repository, paste it into documentation, or include it in screenshots or logs. **Show the environment-variable table** | Variable | Purpose | | --- | --- | | `TRIPO_API_KEY` | API key; highest precedence and suitable for CI or Agents | | `TRIPO_PROFILE` | Named account profile, equivalent to `--profile` | | `TRIPO_REGION` | Optional `ov` or `cn` override; normally auto-detected | | `TRIPO_API_BASE_URL` | API endpoint override | | `TRIPO_PLATFORM_BASE_URL` | Platform endpoint override | | `TRIPO_HOME` | Config and history directory; defaults to `~/.tripo` | | `TRIPO_LLM_BASE_URL` | Optional OpenAI-compatible endpoint for `tripo ai` | | `TRIPO_LLM_API_KEY` | Optional LLM key for `tripo ai` | | `TRIPO_LLM_MODEL` | Optional LLM model for `tripo ai` | PreviousComfyUI NodesNextCodex Plugin On this page --- # Codex Plugin — Tripo Developers Use Tripo in Codex ================== CopyDownload PDF \# Use Tripo in Codex Talk to Codex the way you talk to a person. Ask for a 3D model; the \*\*Tripo 3D\*\* plugin generates it and saves the file into your project. You do not need to know APIs, terminals, or 3D software. This is a start-from-zero walkthrough. Do the steps in order. If one step fails, fix it before going on. ## What you need 1. \*\*A computer\*\* (Mac or Windows). 2. \*\*Codex\*\* — OpenAI's coding assistant. It lives in the ChatGPT desktop app or the Codex CLI. It is \*\*not\*\* a normal ChatGPT chat window. 3. \*\*Node.js 20 or later.\*\* The plugin uses it in the background. You will not write any Node code. 4. \*\*A Tripo account.\*\* New accounts receive free credits. Create one at \[developers.tripo3d.ai\](https://developers.tripo3d.ai) if you do not have one. Check Node.js. Open Terminal (Mac) or PowerShell (Windows) and run: \`\`\`bash node -v \`\`\` You should see a number like \`v20.11.0\` or higher. If the command is not found, install the LTS version from \[nodejs.org\](https://nodejs.org/), then close and reopen the terminal and try again. Installing the plugin and signing in are free. \*\*Generating a model spends Tripo credits.\*\* ## Step 1. Open Codex, not ChatGPT chat This is the most common mistake. 1. Open the \*\*ChatGPT desktop app\*\* (or the Codex CLI). 2. Switch to \*\*Codex\*\*. 3. Open the folder where you want the 3D files to appear. If you do not have a project yet, create an empty folder and open that. If you stay in a normal ChatGPT conversation, the Tripo plugin will not load. That is expected: this plugin only works in Codex. ## Step 2. Install the Tripo 3D plugin 1. In Codex, open \*\*Plugins\*\*. 2. Open the \*\*Plugins Directory\*\*. 3. Search for \*\*Tripo 3D\*\*. 4. Install it, then confirm it is \*\*enabled\*\*. !\[Codex Plugins directory search results for “tripo”, with the Tripo 3D plugin highlighted\](/assets/images/docs/codex-plugin/plugin-search-en.webp) After a successful install you should see two capabilities: generate a 3D asset, and build game-ready assets. You do not need to turn them on one by one — keep the plugin enabled. !\[Tripo 3D plugin detail page in Codex, with the Install plugin button and its two skills\](/assets/images/docs/codex-plugin/plugin-detail.webp)
Trouble? You cannot find Tripo 3D - Confirm you are in \*\*Codex\*\*, not ChatGPT chat. - Quit the ChatGPT desktop app completely and open it again, then search once more. - If it still does not appear, use \[Tripo CLI\](/en/docs/cli) instead. It is the same generation engine, driven from the terminal.
## Step 3. Send your first message Copy the whole block below and paste it into Codex: \`\`\`text I want a low-poly treasure chest with textures. Save the GLB file in the ./assets folder. If Tripo is not set up yet, walk me through every step like I have never used it. Do not ask me to paste an API key into the chat. \`\`\` Press send. Codex should now: 1. Check whether Tripo is ready on your computer. 2. If you are not signed in, show a \*\*verification URL\*\* and a \*\*one-time code\*\*. 3. Wait while you finish sign-in in the browser. 4. Generate the model and write it into \`./assets\`. \*\*Never paste an API key into the chat.\*\* The plugin does not need you to do that. If Codex asks for a key, reply: \`Sign in with the browser instead. Do not ask me for a key.\` ## Step 4. Sign in in the browser (first time only) When Codex shows a URL and a code, complete these clicks yourself. Leave Codex running — do not stop it. 1. Open the verification URL in your browser. 2. If the page asks you to sign in, sign in or create an account at \[developers.tripo3d.ai\](https://developers.tripo3d.ai), then return to the verification page. 3. Type the one-time code into the \*\*Verification code\*\* field. Check that it matches the code in Codex \*\*exactly\*\*. 4. If your account already has API keys, pick any one of them. If you have none, one is created for you — there is nothing to choose. 5. Click \*\*Authorize\*\*. !\[Tripo CLI browser device-authorization page with a verification code\](/assets/images/docs/cli/device-authorization-en.webp) When authorization succeeds, Codex continues by itself. You should not copy anything back into the chat. The code expires after a while. If it fails, ask Codex: \`Please sign in to Tripo again.\`
Trouble? The browser did not open, or sign-in did not finish - Copy the URL from Codex and paste it into the browser yourself. - The code in the page must match the code in Codex. If you are unsure, ask Codex to sign in again for a fresh code. - Keep Codex waiting. Sign-in can take several minutes; stopping it early throws the code away.
## Step 5. Wait, then open the files Keep Codex open. The first generation often takes a few minutes. Codex is waiting for Tripo to finish — that is normal, not a freeze. When it is done, Codex should: - Tell you where the files were saved (usually under \`./assets\`) - Mention how many credits were used - Look at a preview image if one was generated Open that folder. You typically get: - A model file such as \`model.glb\` - \`preview.png\` — a picture of the model - \`task.json\` — a record of the job If the preview is not what you asked for, tell Codex: \`That is not what I wanted. Try again with a new seed.\` ## What to say next Use ordinary language. These are ready to copy. \*\*Turn an image into 3D\*\* (put \`concept.png\` in your project folder first): \`\`\`text Turn concept.png into a 3D model and save it in ./assets. \`\`\` \*\*Continue from the last model\*\* (does not generate from scratch — cheaper): \`\`\`text From the last model, make a 1500-face LOD and save it in ./assets. \`\`\` \*\*Game props, then wire them into code:\*\* \`\`\`text Make three placeholder props for my scene as GLB files in ./assets, then load them in the project code. \`\`\` If you ask for several models at once, Codex should \*\*ask you to confirm\*\* before spending credits. That is working as designed. ## If something goes wrong | What you see | What to do | | --- | --- | | The plugin does not appear | You are in ChatGPT chat. Switch to Codex. | | Codex asks you to paste an API key | Refuse. Say: \`Sign in with the browser. Do not ask me for a key.\` | | Sign-in page does nothing | Paste the URL from Codex into the browser. Check that the codes match. | | "Not enough credits" | Nothing finished generating. Add credits in the \[console\](https://developers.tripo3d.ai), then ask Codex to try again. | | Generation failed midway | Credits for a failed task are refunded automatically. Ask Codex to try again. | | Files are not in your project | Tell Codex the exact folder, for example \`Save it in ./assets\`. | | The result looks bad | Ask Codex to redo it. Do not keep regenerating in a silent loop. | ## Related pages - \[Tripo CLI\](/en/docs/cli) — the same engine, used from the terminal - \[Plugins\](/en/docs/plugins) — Unity, Blender, and other editors - \[Authentication\](/en/docs/authentication) — API keys (you should not need this for Codex) - \[Billing\](/en/docs/billing) — how credits work Use Tripo in Codex ================== Talk to Codex the way you talk to a person. Ask for a 3D model; the **Tripo 3D** plugin generates it and saves the file into your project. You do not need to know APIs, terminals, or 3D software. This is a start-from-zero walkthrough. Do the steps in order. If one step fails, fix it before going on. What you need ------------- 1. **A computer** (Mac or Windows). 2. **Codex** — OpenAI’s coding assistant. It lives in the ChatGPT desktop app or the Codex CLI. It is **not** a normal ChatGPT chat window. 3. **Node.js 20 or later.** The plugin uses it in the background. You will not write any Node code. 4. **A Tripo account.** New accounts receive free credits. Create one at [developers.tripo3d.ai](https://developers.tripo3d.ai/) if you do not have one. Check Node.js. Open Terminal (Mac) or PowerShell (Windows) and run: BashCopy node -v You should see a number like `v20.11.0` or higher. If the command is not found, install the LTS version from [nodejs.org](https://nodejs.org/) , then close and reopen the terminal and try again. Installing the plugin and signing in are free. **Generating a model spends Tripo credits.** Step 1. Open Codex, not ChatGPT chat ------------------------------------ This is the most common mistake. 1. Open the **ChatGPT desktop app** (or the Codex CLI). 2. Switch to **Codex**. 3. Open the folder where you want the 3D files to appear. If you do not have a project yet, create an empty folder and open that. If you stay in a normal ChatGPT conversation, the Tripo plugin will not load. That is expected: this plugin only works in Codex. Step 2. Install the Tripo 3D plugin ----------------------------------- 1. In Codex, open **Plugins**. 2. Open the **Plugins Directory**. 3. Search for **Tripo 3D**. 4. Install it, then confirm it is **enabled**. ![Codex Plugins directory search results for “tripo”, with the Tripo 3D plugin highlighted](https://developers.tripo3d.ai/assets/images/docs/codex-plugin/plugin-search-en.webp) After a successful install you should see two capabilities: generate a 3D asset, and build game-ready assets. You do not need to turn them on one by one — keep the plugin enabled. ![Tripo 3D plugin detail page in Codex, with the Install plugin button and its two skills](https://developers.tripo3d.ai/assets/images/docs/codex-plugin/plugin-detail.webp) **Trouble?** You cannot find Tripo 3D * Confirm you are in **Codex**, not ChatGPT chat. * Quit the ChatGPT desktop app completely and open it again, then search once more. * If it still does not appear, use [Tripo CLI](https://developers.tripo3d.ai/en/docs/cli) instead. It is the same generation engine, driven from the terminal. Step 3. Send your first message ------------------------------- Copy the whole block below and paste it into Codex: Copy I want a low-poly treasure chest with textures. Save the GLB file in the ./assets folder. If Tripo is not set up yet, walk me through every step like I have never used it. Do not ask me to paste an API key into the chat. Press send. Codex should now: 1. Check whether Tripo is ready on your computer. 2. If you are not signed in, show a **verification URL** and a **one-time code**. 3. Wait while you finish sign-in in the browser. 4. Generate the model and write it into `./assets`. **Never paste an API key into the chat.** The plugin does not need you to do that. If Codex asks for a key, reply: `Sign in with the browser instead. Do not ask me for a key.` Step 4. Sign in in the browser (first time only) ------------------------------------------------ When Codex shows a URL and a code, complete these clicks yourself. Leave Codex running — do not stop it. 1. Open the verification URL in your browser. 2. If the page asks you to sign in, sign in or create an account at [developers.tripo3d.ai](https://developers.tripo3d.ai/) , then return to the verification page. 3. Type the one-time code into the **Verification code** field. Check that it matches the code in Codex **exactly**. 4. If your account already has API keys, pick any one of them. If you have none, one is created for you — there is nothing to choose. 5. Click **Authorize**. ![Tripo CLI browser device-authorization page with a verification code](https://developers.tripo3d.ai/assets/images/docs/cli/device-authorization-en.webp) When authorization succeeds, Codex continues by itself. You should not copy anything back into the chat. The code expires after a while. If it fails, ask Codex: `Please sign in to Tripo again.` **Trouble?** The browser did not open, or sign-in did not finish * Copy the URL from Codex and paste it into the browser yourself. * The code in the page must match the code in Codex. If you are unsure, ask Codex to sign in again for a fresh code. * Keep Codex waiting. Sign-in can take several minutes; stopping it early throws the code away. Step 5. Wait, then open the files --------------------------------- Keep Codex open. The first generation often takes a few minutes. Codex is waiting for Tripo to finish — that is normal, not a freeze. When it is done, Codex should: * Tell you where the files were saved (usually under `./assets`) * Mention how many credits were used * Look at a preview image if one was generated Open that folder. You typically get: * A model file such as `model.glb` * `preview.png` — a picture of the model * `task.json` — a record of the job If the preview is not what you asked for, tell Codex: `That is not what I wanted. Try again with a new seed.` What to say next ---------------- Use ordinary language. These are ready to copy. **Turn an image into 3D** (put `concept.png` in your project folder first): Copy Turn concept.png into a 3D model and save it in ./assets. **Continue from the last model** (does not generate from scratch — cheaper): Copy From the last model, make a 1500-face LOD and save it in ./assets. **Game props, then wire them into code:** Copy Make three placeholder props for my scene as GLB files in ./assets, then load them in the project code. If you ask for several models at once, Codex should **ask you to confirm** before spending credits. That is working as designed. If something goes wrong ----------------------- | What you see | What to do | | --- | --- | | The plugin does not appear | You are in ChatGPT chat. Switch to Codex. | | Codex asks you to paste an API key | Refuse. Say: `Sign in with the browser. Do not ask me for a key.` | | Sign-in page does nothing | Paste the URL from Codex into the browser. Check that the codes match. | | “Not enough credits” | Nothing finished generating. Add credits in the [console](https://developers.tripo3d.ai/)
, then ask Codex to try again. | | Generation failed midway | Credits for a failed task are refunded automatically. Ask Codex to try again. | | Files are not in your project | Tell Codex the exact folder, for example `Save it in ./assets`. | | The result looks bad | Ask Codex to redo it. Do not keep regenerating in a silent loop. | Related pages ------------- * [Tripo CLI](https://developers.tripo3d.ai/en/docs/cli) — the same engine, used from the terminal * [Plugins](https://developers.tripo3d.ai/en/docs/plugins) — Unity, Blender, and other editors * [Authentication](https://developers.tripo3d.ai/en/docs/authentication) — API keys (you should not need this for Codex) * [Billing](https://developers.tripo3d.ai/en/docs/billing) — how credits work PreviousTripo CLINextTask Lifecycle On this page --- # Task Lifecycle — Tripo Developers Task Lifecycle ============== CopyDownload PDF \# Task Lifecycle All generation APIs in the Tripo API use an asynchronous task pattern. After you submit a request, the API returns a \`task\_id\`. You can then poll the task status and result. ## State Machine \`\`\` queued -> running -> success -> failed -> cancelled \`\`\` ## Status Descriptions | Status | Description | progress | | :-: | :-: | :-: | | \`queued\` | The task has been created and is waiting in the queue | 0 | | \`running\` | The task is being processed | 0-100 | | \`success\` | The task is complete, and the \`output\` field is available | 100 | | \`failed\` | The task failed, usually due to a server-side issue. Contact support | - | | \`banned\` | The input content violates the content policy | - | | \`expired\` | The task has expired, and output files are no longer available | - | | \`cancelled\` | The task has been cancelled | - | ## Task Flow \`\`\` 1. Create a task (POST /v3/generation/\*) | v 2. Return task\_id | v 3. Poll status (GET /v3/tasks/{task\_id}) | v 4a. status=success -> Get download links from output 4b. status=failed -> Check error details and contact support 4c. status=banned -> Modify the input content and submit again \`\`\` ## Credit Freeze Model Tripo uses a credit "freeze-then-deduct" model to ensure users are not charged for failed tasks: | Stage | Credit Change | Description | | :-: | :-: | :-: | | Task creation | Freeze the required credits | Credits are pre-authorized from the available balance and moved into a frozen state | | Task succeeds | Frozen credits become consumed credits | Credits are formally deducted | | Task fails | Frozen credits are released | Credits are returned to the available balance | | Task is cancelled | Frozen credits are released | Credits are returned to the available balance | Query the current balance and frozen credits: \`\`\`bash curl -X GET https://openapi.tripo3d.ai/v3/account/balance \\ -H "Authorization: Bearer {api\_key}" \`\`\` \`\`\`json { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } \`\`\` ## Polling Recommendations - \*\*Polling interval\*\*: Query once every 1-2 seconds - \*\*Use the \`progress\` field to display progress\*\*: The value is an integer from 0 to 100 - \*\*Set a timeout\*\*: We recommend setting a maximum polling duration, such as 5 minutes. If it times out, tell the user to check again later - \*\*Use \`POST /v3/tasks/list\` for batch tasks\*\*: Reduce the number of requests ### Python Polling Example \`\`\`python import time import requests def wait\_for\_task(task\_id, api\_key, interval=2, timeout=300): url = f"https://openapi.tripo3d.ai/v3/tasks/{task\_id}" headers = {"Authorization": f"Bearer {api\_key}"} start = time.time() while time.time() - start < timeout: response = requests.get(url, headers=headers) task = response.json()\["data"\] status = task\["status"\] progress = task.get("progress", 0) print(f"\[{task\_id}\] {status} ({progress}%)") if status == "success": return task\["output"\] if status in ("failed", "cancelled", "banned"): raise Exception(f"Task terminated: {status}") time.sleep(interval) raise TimeoutError(f"Task {task\_id} timed out") \`\`\` ### JavaScript Polling Example \`\`\`javascript async function waitForTask(taskId, apiKey, interval = 2000, timeout = 300000) { const url = \`https://openapi.tripo3d.ai/v3/tasks/${taskId}\`; const headers = { "Authorization": \`Bearer ${apiKey}\` }; const start = Date.now(); while (Date.now() - start < timeout) { const response = await fetch(url, { headers }); const { data: task } = await response.json(); const { status, progress = 0 } = task; console.log(\`\[${taskId}\] ${status} (${progress}%)\`); if (status === "success") return task.output; if (\["failed", "cancelled", "banned"\].includes(status)) { throw new Error(\`Task terminated: ${status}\`); } await new Promise(resolve => setTimeout(resolve, interval)); } throw new Error(\`Task ${taskId} timed out\`); } \`\`\` Task Lifecycle ============== All generation APIs in the Tripo API use an asynchronous task pattern. After you submit a request, the API returns a `task_id`. You can then poll the task status and result. State Machine ------------- Copy queued -> running -> success -> failed -> cancelled Status Descriptions ------------------- | Status | Description | progress | | --- | --- | --- | | `queued` | The task has been created and is waiting in the queue | 0 | | `running` | The task is being processed | 0-100 | | `success` | The task is complete, and the `output` field is available | 100 | | `failed` | The task failed, usually due to a server-side issue. Contact support | \- | | `banned` | The input content violates the content policy | \- | | `expired` | The task has expired, and output files are no longer available | \- | | `cancelled` | The task has been cancelled | \- | Task Flow --------- Copy 1. Create a task (POST /v3/generation/*) | v 2. Return task_id | v 3. Poll status (GET /v3/tasks/{task_id}) | v 4a. status=success -> Get download links from output 4b. status=failed -> Check error details and contact support 4c. status=banned -> Modify the input content and submit again Credit Freeze Model ------------------- Tripo uses a credit “freeze-then-deduct” model to ensure users are not charged for failed tasks: | Stage | Credit Change | Description | | --- | --- | --- | | Task creation | Freeze the required credits | Credits are pre-authorized from the available balance and moved into a frozen state | | Task succeeds | Frozen credits become consumed credits | Credits are formally deducted | | Task fails | Frozen credits are released | Credits are returned to the available balance | | Task is cancelled | Frozen credits are released | Credits are returned to the available balance | Query the current balance and frozen credits: BashCopy curl -X GET https://openapi.tripo3d.ai/v3/account/balance \ -H "Authorization: Bearer {api_key}" JSONCopy { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } Polling Recommendations ----------------------- * **Polling interval**: Query once every 1-2 seconds * **Use the `progress` field to display progress**: The value is an integer from 0 to 100 * **Set a timeout**: We recommend setting a maximum polling duration, such as 5 minutes. If it times out, tell the user to check again later * **Use `POST /v3/tasks/list` for batch tasks**: Reduce the number of requests ### Python Polling Example PythonCopy import time import requests def wait_for_task(task_id, api_key, interval=2, timeout=300): url = f"https://openapi.tripo3d.ai/v3/tasks/{task_id}" headers = {"Authorization": f"Bearer {api_key}"} start = time.time() while time.time() - start < timeout: response = requests.get(url, headers=headers) task = response.json()["data"] status = task["status"] progress = task.get("progress", 0) print(f"[{task_id}] {status} ({progress}%)") if status == "success": return task["output"] if status in ("failed", "cancelled", "banned"): raise Exception(f"Task terminated: {status}") time.sleep(interval) raise TimeoutError(f"Task {task_id} timed out") ### JavaScript Polling Example JavaScriptCopy async function waitForTask(taskId, apiKey, interval = 2000, timeout = 300000) { const url = `https://openapi.tripo3d.ai/v3/tasks/${taskId}`; const headers = { "Authorization": `Bearer ${apiKey}` }; const start = Date.now(); while (Date.now() - start < timeout) { const response = await fetch(url, { headers }); const { data: task } = await response.json(); const { status, progress = 0 } = task; console.log(`[${taskId}] ${status} (${progress}%)`); if (status === "success") return task.output; if (["failed", "cancelled", "banned"].includes(status)) { throw new Error(`Task terminated: ${status}`); } await new Promise(resolve => setTimeout(resolve, interval)); } throw new Error(`Task ${taskId} timed out`); } PreviousCodex PluginNextModels & Versions On this page --- # Billing — Tripo Developers Billing ======= CopyDownload PDF \# Billing ## Credit System The Tripo API uses credits for billing. Different task types consume different numbers of credits. ## Credit Freeze/Deduction Model | Stage | Description | | :-: | :-: | | Task creation | Freeze the required credits from the available balance | | Task succeeds | Frozen credits become consumed credits and are formally deducted | | Task fails | Frozen credits are returned to the available balance | | Task is cancelled | Frozen credits are returned to the available balance | Failed and cancelled tasks are not charged. ## Query Balance > \*\*GET\*\* \`/v3/account/balance\` ### curl \`\`\`bash curl -X GET https://openapi.tripo3d.ai/v3/account/balance \\ -H "Authorization: Bearer {api\_key}" \`\`\` ### Python \`\`\`python import requests url = "https://openapi.tripo3d.ai/v3/account/balance" headers = { "Authorization": "Bearer {api\_key}" } response = requests.get(url, headers=headers) print(response.json()) \`\`\` ### JavaScript \`\`\`javascript const response = await fetch("https://openapi.tripo3d.ai/v3/account/balance", { headers: { "Authorization": "Bearer {api\_key}" } }); const data = await response.json(); console.log(data); \`\`\` ### Response Example \`\`\`json { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } \`\`\` | Field | Type | Description | | :-: | :-: | :-: | | balance | number | Available credit balance | | frozen | number | Frozen credits, pre-authorized for in-progress tasks | ## View Usage > \*\*GET\*\* \`/v3/account/usage\` ### curl \`\`\`bash curl -X GET https://openapi.tripo3d.ai/v3/account/usage \\ -H "Authorization: Bearer {api\_key}" \`\`\` ### Python \`\`\`python import requests url = "https://openapi.tripo3d.ai/v3/account/usage" headers = { "Authorization": "Bearer {api\_key}" } response = requests.get(url, headers=headers) print(response.json()) \`\`\` ### JavaScript \`\`\`javascript const response = await fetch("https://openapi.tripo3d.ai/v3/account/usage", { headers: { "Authorization": "Bearer {api\_key}" } }); const data = await response.json(); console.log(data); \`\`\` ### Response Example \`\`\`json { "code": 0, "data": \[ { "task\_id": "task\_abc123", "type": "text\_to\_model", "credits\_consumed": 100.00, "created\_at": "2026-01-01T00:00:00Z" } \] } \`\`\` | Field | Type | Description | | :-: | :-: | :-: | | task\_id | string | Unique task identifier | | type | string | Task type | | credits\_consumed | number | Credits consumed | | created\_at | string | Creation time, in ISO 8601 format | Billing ======= Credit System ------------- The Tripo API uses credits for billing. Different task types consume different numbers of credits. Credit Freeze/Deduction Model ----------------------------- | Stage | Description | | --- | --- | | Task creation | Freeze the required credits from the available balance | | Task succeeds | Frozen credits become consumed credits and are formally deducted | | Task fails | Frozen credits are returned to the available balance | | Task is cancelled | Frozen credits are returned to the available balance | Failed and cancelled tasks are not charged. Query Balance ------------- > **GET** `/v3/account/balance` cURLPythonJavaScript Copy curl -X GET https://openapi.tripo3d.ai/v3/account/balance \ -H "Authorization: Bearer {api_key}" import requests url = "https://openapi.tripo3d.ai/v3/account/balance" headers = { "Authorization": "Bearer {api_key}" } response = requests.get(url, headers=headers) print(response.json()) const response = await fetch("https://openapi.tripo3d.ai/v3/account/balance", { headers: { "Authorization": "Bearer {api_key}" } }); const data = await response.json(); console.log(data); ### Response Example JSONCopy { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } | Field | Type | Description | | --- | --- | --- | | balance | number | Available credit balance | | frozen | number | Frozen credits, pre-authorized for in-progress tasks | View Usage ---------- > **GET** `/v3/account/usage` cURLPythonJavaScript Copy curl -X GET https://openapi.tripo3d.ai/v3/account/usage \ -H "Authorization: Bearer {api_key}" import requests url = "https://openapi.tripo3d.ai/v3/account/usage" headers = { "Authorization": "Bearer {api_key}" } response = requests.get(url, headers=headers) print(response.json()) const response = await fetch("https://openapi.tripo3d.ai/v3/account/usage", { headers: { "Authorization": "Bearer {api_key}" } }); const data = await response.json(); console.log(data); ### Response Example JSONCopy { "code": 0, "data": [\ {\ "task_id": "task_abc123",\ "type": "text_to_model",\ "credits_consumed": 100.00,\ "created_at": "2026-01-01T00:00:00Z"\ }\ ] } | Field | Type | Description | | --- | --- | --- | | task\_id | string | Unique task identifier | | type | string | Task type | | credits\_consumed | number | Credits consumed | | created\_at | string | Creation time, in ISO 8601 format | PreviousModels & VersionsNextText to 3D Model — H Series On this page --- # Text to 3D Model — P Series — Tripo Developers Text to 3D Model — P Series =========================== CopyDownload PDF \# Text to 3D Model — P Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/text-to-model\` Generate a 3D model from a text prompt using P Series. Optimized for low-poly output with clean topology. ## Request Parameters ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Required Text prompt, up to 1024 characters. Describe shape, material, style, and scale. - Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." - Bad: "A box." - Include material and style hints for better PBR results. ### negative\_prompt - \*\*Type:\*\* string - \*\*Required:\*\* Optional Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". ### image\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required P Series model version. - \`P1-20260311\` — optimized for low-poly generation. - \`P2-20260801\` — next-gen P Series with quad output support. Preview ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - \`P1-20260311\`: \*\*50 – 20,000\*\* - \`P2-20260801\` triangle: \*\*48 – 50,000\*\*; with \`quad=true\`: \*\*48 – 25,000\*\* - If omitted, adaptively determined. For best quality: simple models start from \*\*150\*\* faces, complex models start from \*\*250\*\* faces. Lower values may result in poor generation quality. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping. Set \`false\` for faster generation and smaller file size. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` \*\*P2-20260801 only.\*\* Whether to output a quad mesh (four-sided polygons) instead of triangles. ## Request Example ### P Series \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A cat wearing a spacesuit", "model": "P1-20260311", "face\_limit": 3000, "texture": true, "pbr": true }' \`\`\` ### P2 Series \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A low-poly wooden chair", "model": "P2-20260801", "quad": true, "face\_limit": 5000, "texture": true, "pbr": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body promptstringRequired Text prompt, up to 1024 characters. Describe shape, material, style, and scale. Notes * Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." * Bad: "A box." * Include material and style hints for better PBR results. negative\_promptstring Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". image\_seedinteger Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. modelstringRequired P Series model version. * `P1-20260311` — optimized for low-poly generation. * `P2-20260801` — next-gen P Series with quad output support. Preview model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. face\_limitinteger Maximum polycount for the output mesh. Notes * `P1-20260311`: **50 – 20,000** * `P2-20260801` triangle: **48 – 50,000**; with `quad=true`: **48 – 25,000** * If omitted, adaptively determined. For best quality: simple models start from **150** faces, complex models start from **250** faces. Lower values may result in poor generation quality. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. export\_uvbooleandefault: true Controls UV unwrapping. Set `false` for faster generation and smaller file size. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. quadbooleandefault: false **P2-20260801 only.** Whether to output a quad mesh (four-sided polygons) instead of triangles. Examples -------- P SeriesCopy { "prompt": "A cat wearing a spacesuit", "model": "P1-20260311", "face_limit": 3000, "texture": true, "pbr": true } P2 SeriesCopy { "prompt": "A low-poly wooden chair", "model": "P2-20260801", "quad": true, "face_limit": 5000, "texture": true, "pbr": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousText to 3D Model — H SeriesNextImage to 3D Model — H Series --- # Text to 3D Model — H Series — Tripo Developers Text to 3D Model — H Series =========================== CopyDownload PDF \# Text to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/text-to-model\` Generate a 3D model from a text prompt. Produces geometry, optional textures, and optional PBR material maps. ## Request Parameters ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Required Text prompt, up to 1024 characters. Describe shape, material, style, and scale. - Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." - Bad: "A box." - Include material and style hints for better PBR results. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### negative\_prompt - \*\*Type:\*\* string - \*\*Required:\*\* Optional Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### image\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### Basic \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A cat wearing a spacesuit", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### Advanced \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A futuristic sci-fi helmet with glowing blue visor.", "model": "v3.1-20260211", "face\_limit": 80000, "geometry\_quality": "detailed", "auto\_size": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body promptstringRequired Text prompt, up to 1024 characters. Describe shape, material, style, and scale. Notes * Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." * Bad: "A box." * Include material and style hints for better PBR results. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. negative\_promptstring Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. image\_seedinteger Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- BasicCopy { "prompt": "A cat wearing a spacesuit", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} AdvancedCopy { "prompt": "A futuristic sci-fi helmet with glowing blue visor.", "model": "v3.1-20260211", "face_limit": 80000, "geometry_quality": "detailed", "auto_size": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousBillingNextText to 3D Model — P Series --- # Models & Versions — Tripo Developers Models and Versions =================== CopyDownload PDF \# Models and Versions ## 3D Generation Models The \`model\` parameter used by 3D generation endpoints such as \`POST /v3/generation/text-to-model\` and \`POST /v3/generation/image-to-model\`. | Model ID | Description | Recommended Use Case | | :-: | :-: | :-: | | \`tripo-p1\` | Best low-poly performance | Game pipelines / UGC generative gameplay / Mobile 3D assets | | \`tripo-v3.1\` | Latest high-precision model (default) | AAA production pipelines / 3D printing & flexible manufacturing | | \`tripo-v3.0\` | Previous-generation stable version | Backward compatibility | | \`tripo-v2.5\` | Legacy version | Historical project compatibility | ## Image Generation Models The \`model\` parameter used by \`POST /v3/generation/text-to-image\` and \`POST /v3/generation/image-to-image\` endpoints. | Model ID | Provider | Characteristics | | :-: | :-: | :-: | | \`seedream\_v4\` | ByteDance | Default model with balanced results | | \`seedream\_v5\` | ByteDance | Latest version with improved quality | | \`gemini-2.5-flash\` | Google | Fast generation | | \`gemini-3-pro\` | Google | High-quality generation | | \`gemini-3.1-flash\` | Google | Latest fast version | | \`chat\_image\_1\` | OpenAI | GPT image generation (retiring 2026-10-23) | | \`chat\_image\_1.5\` | OpenAI | GPT higher quality (retiring 2026-12-01) | | \`chat\_image\_2\` | OpenAI | GPT latest | | \`chat\_image\_2.5\_flare\` | OpenAI | GPT 2.5, speed tier | | \`chat\_image\_2.5\_sunburst\` | OpenAI | GPT 2.5, fidelity tier | ## Version Selection Recommendations - \*\*New projects\*\*: Use the default versions, \`tripo-v3.1\` for 3D and \`seedream\_v4\` for images, for the best balance of quality and stability - \*\*Production environments\*\*: Pin a specific model version to avoid output inconsistencies caused by model updates - \*\*Highest quality\*\*: Use \`tripo-p1\` for 3D, and choose \`gemini-3-pro\` or \`seedream\_v5\` for images depending on the scenario - \*\*Low-poly / game assets\*\*: Use \`tripo-p1\` for 3D — cleaner topology and more precise face-count control ## Request Examples \`\`\`bash # Use the default model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer {api\_key}" \\ -d '{"prompt": "a robot"}' # Specify the flagship model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer {api\_key}" \\ -d '{"prompt": "a robot", "model": "tripo-p1"}' # Use an image generation model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-image \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer {api\_key}" \\ -d '{"prompt": "a futuristic city", "model": "seedream-v5"}' \`\`\` Models and Versions =================== 3D Generation Models -------------------- The `model` parameter used by 3D generation endpoints such as `POST /v3/generation/text-to-model` and `POST /v3/generation/image-to-model`. | Model ID | Description | Recommended Use Case | | --- | --- | --- | | `tripo-p1` | Best low-poly performance | Game pipelines / UGC generative gameplay / Mobile 3D assets | | `tripo-v3.1` | Latest high-precision model (default) | AAA production pipelines / 3D printing & flexible manufacturing | | `tripo-v3.0` | Previous-generation stable version | Backward compatibility | | `tripo-v2.5` | Legacy version | Historical project compatibility | Image Generation Models ----------------------- The `model` parameter used by `POST /v3/generation/text-to-image` and `POST /v3/generation/image-to-image` endpoints. | Model ID | Provider | Characteristics | | --- | --- | --- | | `seedream_v4` | ByteDance | Default model with balanced results | | `seedream_v5` | ByteDance | Latest version with improved quality | | `gemini-2.5-flash` | Google | Fast generation | | `gemini-3-pro` | Google | High-quality generation | | `gemini-3.1-flash` | Google | Latest fast version | | `chat_image_1` | OpenAI | GPT image generation (retiring 2026-10-23) | | `chat_image_1.5` | OpenAI | GPT higher quality (retiring 2026-12-01) | | `chat_image_2` | OpenAI | GPT latest | | `chat_image_2.5_flare` | OpenAI | GPT 2.5, speed tier | | `chat_image_2.5_sunburst` | OpenAI | GPT 2.5, fidelity tier | Version Selection Recommendations --------------------------------- * **New projects**: Use the default versions, `tripo-v3.1` for 3D and `seedream_v4` for images, for the best balance of quality and stability * **Production environments**: Pin a specific model version to avoid output inconsistencies caused by model updates * **Highest quality**: Use `tripo-p1` for 3D, and choose `gemini-3-pro` or `seedream_v5` for images depending on the scenario * **Low-poly / game assets**: Use `tripo-p1` for 3D — cleaner topology and more precise face-count control Request Examples ---------------- BashCopy # Use the default model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {api_key}" \ -d '{"prompt": "a robot"}' # Specify the flagship model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {api_key}" \ -d '{"prompt": "a robot", "model": "tripo-p1"}' # Use an image generation model curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-image \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {api_key}" \ -d '{"prompt": "a futuristic city", "model": "seedream-v5"}' PreviousTask LifecycleNextBilling On this page --- # Image to 3D Model — H Series — Tripo Developers Image to 3D Model — H Series ============================ CopyDownload PDF \# Image to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/image-to-model\` Generate a 3D model from an image. The system infers geometry and texture from the input. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/photo.png\` - task\_id — The task ID from a previous image generation task (\`text\_to\_image\` or \`image\_to\_image\`). The system automatically extracts the output image. Example: \`task\_abc123\` - Supported formats: \`PNG\`, \`JPEG\`, \`WebP\` - Max file size: \*\*20 MB\*\* - Recommended resolution: at least \*\*256 × 256 px\*\*. Subject should be clearly visible with a clean background and minimal occlusion. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### enable\_image\_autofix - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### From URL \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/image.png", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### With autofix \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "file\_abc123", "model": "v3.1-20260211", "enable\_image\_autofix": true, "orientation": "align\_image" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/photo.png` * task\_id — The task ID from a previous image generation task (`text_to_image` or `image_to_image`). The system automatically extracts the output image. Example: `task_abc123` Notes * Supported formats: `PNG`, `JPEG`, `WebP` * Max file size: **20 MB** * Recommended resolution: at least **256 × 256 px**. Subject should be clearly visible with a clean background and minimal occlusion. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. enable\_image\_autofixbooleandefault: false Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- From URLCopy { "input": "https://example.com/image.png", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} With autofixCopy { "input": "file_abc123", "model": "v3.1-20260211", "enable_image_autofix": true, "orientation": "align_image"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousText to 3D Model — P SeriesNextImage to 3D Model — P Series --- # Image to 3D Model — P Series — Tripo Developers Image to 3D Model — P Series ============================ CopyDownload PDF \# Image to 3D Model — P Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/image-to-model\` Generate a 3D model from an image using P Series. Optimized for low-poly output with clean topology. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/photo.png\` - task\_id — The task ID from a previous image generation task (\`text\_to\_image\` or \`image\_to\_image\`). The system automatically extracts the output image. Example: \`task\_abc123\` - Supported formats: \`PNG\`, \`JPEG\`, \`WebP\` - Max file size: \*\*20 MB\*\* - Recommended resolution: at least \*\*256 × 256 px\*\*. Subject should be clearly visible with a clean background and minimal occlusion. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required P Series model version. - \`P1-20260311\` — optimized for low-poly generation. - \`P2-20260801\` — next-gen P Series with quad output support. Preview ### enable\_image\_autofix - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - \`P1-20260311\`: \*\*50 – 20,000\*\* - \`P2-20260801\` triangle: \*\*48 – 50,000\*\*; with \`quad=true\`: \*\*48 – 25,000\*\* - If omitted, adaptively determined. For best quality: simple models start from \*\*150\*\* faces, complex models start from \*\*250\*\* faces. Lower values may result in poor generation quality. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping. Set \`false\` for faster generation and smaller file size. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` \*\*P2-20260801 only.\*\* Whether to output a quad mesh (four-sided polygons) instead of triangles. ## Request Example ### P Series \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/image.png", "model": "P1-20260311", "face\_limit": 5000, "texture": true, "pbr": true }' \`\`\` ### P2 Series \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/image.png", "model": "P2-20260801", "quad": true, "texture": true, "pbr": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/photo.png` * task\_id — The task ID from a previous image generation task (`text_to_image` or `image_to_image`). The system automatically extracts the output image. Example: `task_abc123` Notes * Supported formats: `PNG`, `JPEG`, `WebP` * Max file size: **20 MB** * Recommended resolution: at least **256 × 256 px**. Subject should be clearly visible with a clean background and minimal occlusion. modelstringRequired P Series model version. * `P1-20260311` — optimized for low-poly generation. * `P2-20260801` — next-gen P Series with quad output support. Preview enable\_image\_autofixbooleandefault: false Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. face\_limitinteger Maximum polycount for the output mesh. Notes * `P1-20260311`: **50 – 20,000** * `P2-20260801` triangle: **48 – 50,000**; with `quad=true`: **48 – 25,000** * If omitted, adaptively determined. For best quality: simple models start from **150** faces, complex models start from **250** faces. Lower values may result in poor generation quality. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. export\_uvbooleandefault: true Controls UV unwrapping. Set `false` for faster generation and smaller file size. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. quadbooleandefault: false **P2-20260801 only.** Whether to output a quad mesh (four-sided polygons) instead of triangles. Examples -------- P SeriesCopy { "input": "https://example.com/image.png", "model": "P1-20260311", "face_limit": 5000, "texture": true, "pbr": true } P2 SeriesCopy { "input": "https://example.com/image.png", "model": "P2-20260801", "quad": true, "texture": true, "pbr": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousImage to 3D Model — H SeriesNextMultiview to 3D Model — H Series --- # Multiview to 3D Model — H Series — Tripo Developers Multiview to 3D Model — H Series ================================ CopyDownload PDF \# Multiview to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/multiview-to-model\` Generate a 3D model from multiview images. Multiple angles improve geometry accuracy and texture coverage. ## Request Parameters ### inputs - \*\*Type:\*\* object\[\] | string\[\] - \*\*Required:\*\* Required \*\*Three formats — use exactly one, do not mix.\*\* - \*\*view-key (recommended)\*\* — Array of objects; each object has exactly one key among \`front\`, \`left\`, \`back\`, \`right\`. Values may be a URL, \`file\_token\`, or nested \`{url}\` / \`{file\_token}\` / \`{object:{bucket,key}}\`. Order does not matter; the server canonicalizes to \*\*\[front, left, back, right\]\*\*. - \*\*legacy positional\*\* — Exactly 4 strings in order \*\*\[front, left, back, right\]\*\*. Use an empty string \`""\` to skip a view. - \*\*task\_id\*\* — Pass the ID of a previous Image to Multiview or Edit Multiview task to reuse its 4-view output. Only \`\[{"task\_id":""}\]\` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be \`success\` with type \`generate\_multiview\_image\` or \`edit\_multiview\_image\`. For view-key and legacy positional, each image value accepts: - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/front.png\` - The front view \*\*cannot be omitted\*\*. You may omit other views, but at least 2 images are required. - All images should depict the same object under consistent lighting. - Formats: \`PNG\`, \`JPEG\`, \`WebP\` - Recommended resolution: at least \*\*256 × 256 px\*\*. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### View-key with URLs \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "https://example.com/front.png" }, { "back": "https://example.com/back.png" }, { "right": "https://example.com/right.png" } \], "model": "v3.1-20260211", "texture": false, "geometry\_quality": "detailed" }' \`\`\` ### View-key with file\_tokens \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "3154b4b0-4647-4032-aa82-827441ae92ef" }, { "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d" }, { "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6" } \], "model": "v3.1-20260211", "texture": false, "geometry\_quality": "detailed" }' \`\`\` ### Legacy positional \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ "https://example.com/front.png", "", "https://example.com/back.png", "https://example.com/right.png" \], "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### From multiview task \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "task\_id": "550e8400-e29b-41d4-a716-446655440000" } \], "model": "v3.1-20260211", "texture": true, "pbr": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputsobject\[\] | string\[\]Required **Three formats — use exactly one, do not mix.** * **view-key (recommended)** — Array of objects; each object has exactly one key among `front`, `left`, `back`, `right`. Values may be a URL, `file_token`, or nested `{url}` / `{file_token}` / `{object:{bucket,key}}`. Order does not matter; the server canonicalizes to **\[front, left, back, right\]**. * **legacy positional** — Exactly 4 strings in order **\[front, left, back, right\]**. Use an empty string `""` to skip a view. * **task\_id** — Pass the ID of a previous [Image to Multiview](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) or Edit Multiview task to reuse its 4-view output. Only `[{"task_id":""}]` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be `success` with type `generate_multiview_image` or `edit_multiview_image`. For view-key and legacy positional, each image value accepts: * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/front.png` Notes * The front view **cannot be omitted**. You may omit other views, but at least 2 images are required. * All images should depict the same object under consistent lighting. * Formats: `PNG`, `JPEG`, `WebP` * Recommended resolution: at least **256 × 256 px**. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- View-key with URLsCopy { "inputs": [\ {\ "front": "https://example.com/front.png"},\ {\ "back": "https://example.com/back.png"},\ {\ "right": "https://example.com/right.png"}\ ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed"} View-key with file\_tokensCopy { "inputs": [\ {\ "front": "3154b4b0-4647-4032-aa82-827441ae92ef"},\ {\ "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},\ {\ "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}\ ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed"} Legacy positionalCopy { "inputs": [\ "https://example.com/front.png",\ "",\ "https://example.com/back.png",\ "https://example.com/right.png"], "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} From multiview taskCopy { "inputs": [\ {\ "task_id": "550e8400-e29b-41d4-a716-446655440000"}\ ], "model": "v3.1-20260211", "texture": true, "pbr": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousImage to 3D Model — P SeriesNextMultiview to 3D Model — P Series --- # Multiview to 3D Model — P Series — Tripo Developers Multiview to 3D Model — P Series ================================ CopyDownload PDF \# Multiview to 3D Model — P Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/multiview-to-model\` Generate a 3D model from multiview images using P Series. Optimized for low-poly output with clean topology. ## Request Parameters ### inputs - \*\*Type:\*\* object\[\] | string\[\] - \*\*Required:\*\* Required \*\*Three formats — use exactly one, do not mix.\*\* - \*\*view-key (recommended)\*\* — Array of objects; each object has exactly one key among \`front\`, \`left\`, \`back\`, \`right\`. Values may be a URL, \`file\_token\`, or nested \`{url}\` / \`{file\_token}\` / \`{object:{bucket,key}}\`. Order does not matter; the server canonicalizes to \*\*\[front, left, back, right\]\*\*. - \*\*legacy positional\*\* — Exactly 4 strings in order \*\*\[front, left, back, right\]\*\*. Use an empty string \`""\` to skip a view. - \*\*task\_id\*\* — Pass the ID of a previous Image to Multiview or Edit Multiview task to reuse its 4-view output. Only \`\[{"task\_id":""}\]\` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be \`success\` with type \`generate\_multiview\_image\` or \`edit\_multiview\_image\`. For view-key and legacy positional, each image value accepts: - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/front.png\` - The front view \*\*cannot be omitted\*\*. You may omit other views, but at least 2 images are required. - All images should depict the same object under consistent lighting. - Formats: \`PNG\`, \`JPEG\`, \`WebP\` - Recommended resolution: at least \*\*256 × 256 px\*\*. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required P Series model version. - \`P1-20260311\` — optimized for low-poly generation. - \`P2-20260801\` — next-gen P Series with quad output support. Preview ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - \`P1-20260311\`: \*\*50 – 20,000\*\* - \`P2-20260801\` triangle: \*\*48 – 50,000\*\*; with \`quad=true\`: \*\*48 – 25,000\*\* - If omitted, adaptively determined. For best quality: simple models start from \*\*150\*\* faces, complex models start from \*\*250\*\* faces. Lower values may result in poor generation quality. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping. Set \`false\` for faster generation and smaller file size. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` \*\*P2-20260801 only.\*\* Whether to output a quad mesh (four-sided polygons) instead of triangles. ## Request Example ### View-key with URLs \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "https://example.com/front.png" }, { "back": "https://example.com/back.png" }, { "right": "https://example.com/right.png" } \], "model": "P1-20260311", "texture": true, "pbr": true }' \`\`\` ### P2 Series \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "https://example.com/front.png" }, { "back": "https://example.com/back.png" } \], "model": "P2-20260801", "quad": true, "texture": true, "pbr": true }' \`\`\` ### View-key with file\_tokens \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "3154b4b0-4647-4032-aa82-827441ae92ef" }, { "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d" }, { "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6" } \], "model": "P1-20260311", "texture": true, "pbr": true }' \`\`\` ### Legacy positional \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ "https://example.com/front.png", "", "https://example.com/back.png", "https://example.com/right.png" \], "model": "P1-20260311", "texture": true, "pbr": true }' \`\`\` ### From multiview task \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "task\_id": "550e8400-e29b-41d4-a716-446655440000" } \], "model": "P1-20260311", "texture": true, "pbr": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputsobject\[\] | string\[\]Required **Three formats — use exactly one, do not mix.** * **view-key (recommended)** — Array of objects; each object has exactly one key among `front`, `left`, `back`, `right`. Values may be a URL, `file_token`, or nested `{url}` / `{file_token}` / `{object:{bucket,key}}`. Order does not matter; the server canonicalizes to **\[front, left, back, right\]**. * **legacy positional** — Exactly 4 strings in order **\[front, left, back, right\]**. Use an empty string `""` to skip a view. * **task\_id** — Pass the ID of a previous [Image to Multiview](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) or Edit Multiview task to reuse its 4-view output. Only `[{"task_id":""}]` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be `success` with type `generate_multiview_image` or `edit_multiview_image`. For view-key and legacy positional, each image value accepts: * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/front.png` Notes * The front view **cannot be omitted**. You may omit other views, but at least 2 images are required. * All images should depict the same object under consistent lighting. * Formats: `PNG`, `JPEG`, `WebP` * Recommended resolution: at least **256 × 256 px**. modelstringRequired P Series model version. * `P1-20260311` — optimized for low-poly generation. * `P2-20260801` — next-gen P Series with quad output support. Preview texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. face\_limitinteger Maximum polycount for the output mesh. Notes * `P1-20260311`: **50 – 20,000** * `P2-20260801` triangle: **48 – 50,000**; with `quad=true`: **48 – 25,000** * If omitted, adaptively determined. For best quality: simple models start from **150** faces, complex models start from **250** faces. Lower values may result in poor generation quality. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. export\_uvbooleandefault: true Controls UV unwrapping. Set `false` for faster generation and smaller file size. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. quadbooleandefault: false **P2-20260801 only.** Whether to output a quad mesh (four-sided polygons) instead of triangles. Examples -------- View-key with URLsCopy { "inputs": [\ {\ "front": "https://example.com/front.png"},\ {\ "back": "https://example.com/back.png"},\ {\ "right": "https://example.com/right.png"}\ ], "model": "P1-20260311", "texture": true, "pbr": true } P2 SeriesCopy { "inputs": [\ {\ "front": "https://example.com/front.png"},\ {\ "back": "https://example.com/back.png"}\ ], "model": "P2-20260801", "quad": true, "texture": true, "pbr": true } View-key with file\_tokensCopy { "inputs": [\ {\ "front": "3154b4b0-4647-4032-aa82-827441ae92ef"},\ {\ "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},\ {\ "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}\ ], "model": "P1-20260311", "texture": true, "pbr": true } Legacy positionalCopy { "inputs": [\ "https://example.com/front.png",\ "",\ "https://example.com/back.png",\ "https://example.com/right.png"], "model": "P1-20260311", "texture": true, "pbr": true } From multiview taskCopy { "inputs": [\ {\ "task_id": "550e8400-e29b-41d4-a716-446655440000"}\ ], "model": "P1-20260311", "texture": true, "pbr": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousMultiview to 3D Model — H SeriesNextImage to Gaussian Splat --- # Text to Image — Tripo Developers Text to Image ============= CopyDownload PDF \# Text to Image \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/text-to-image\` Generate an image from a text prompt. Does not accept reference images — use image-to-image for that. ## Request Parameters ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`seedream\_v4\` Image generation model. Available models: - \`seedream\_v5\` — latest quality, stronger prompt following. - \`seedream\_v4\` — default balanced model. - \`banana\` — fast generation. - \`banana\_pro\` — higher quality. - \`banana2\` — latest fast option. - \`chat\_image\_1\` — base image model. \*\*Retiring 2026-10-23.\*\* - \`chat\_image\_1.5\` — higher quality. \*\*Retiring 2026-12-01.\*\* - \`chat\_image\_2\` — latest, best quality. - \`chat\_image\_2.5\_flare\` — 2.5 speed tier; quality on par with \`chat\_image\_2\`, noticeably faster. - \`chat\_image\_2.5\_sunburst\` — 2.5 fidelity tier; best at preserving the rest of the image when editing. ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Required Text prompt for image generation. Supports Chinese and English. - Recommended: ≤ 300 Chinese characters or ≤ 600 English words. - Put the most important elements first. - Negative prompts: append after \`--no\`. ### size - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`2048x2048\` Output image size. Accepts semantic keywords (e.g. 2K / 4K) or explicit WxH pixels (e.g. 2048x2048). Supported values vary by model — see tabs below. ### quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`low\` Rendering quality tier. Only \`chat\_image\_2\`, \`chat\_image\_2.5\_flare\` and \`chat\_image\_2.5\_sunburst\` accept this parameter; passing it with any other model returns an error. - \`chat\_image\_2\` — \`low\`, \`medium\`, \`high\`. - \`chat\_image\_2.5\_flare\` / \`chat\_image\_2.5\_sunburst\` — \`low\`, \`medium\`, \`high\`, \`xhigh\`, \`max\`. Omitting it is equivalent to \`low\`. Note this differs from OpenAI's own default of \`auto\`, and \`auto\` is \*\*not\*\* supported here — we need a known tier up front in order to price the request. \`high\`, \`xhigh\` and \`max\` cost more credits and take noticeably longer; \`low\` and \`medium\` are billed at the base price. See the Pricing page. ### background - \*\*Type:\*\* string - \*\*Required:\*\* Optional Background handling. Only \`chat\_image\_2.5\_flare\` and \`chat\_image\_2.5\_sunburst\` support it — one of \`auto\`, \`opaque\` or \`transparent\`. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so the request still succeeds but the background is left to the model. \`transparent\` requires \`output\_format=png\`. JPEG carries no alpha channel, so combining the two returns an error instead of silently flattening the transparency. ### aspect\_ratio - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`1:1\` Output aspect ratio. Default \`1:1\` when omitted (banana series only; filled by the gateway when both \`size\` and \`aspect\_ratio\` are absent). - \`banana\` / \`banana\_pro\`: \`1:1\`, \`2:3\`, \`3:2\`, \`3:4\`, \`4:3\`, \`4:5\`, \`5:4\`, \`9:16\`, \`16:9\`, \`21:9\`. - \`banana2\` additionally supports \`1:8\`, \`1:4\`, \`4:1\`, \`8:1\`. Only the \*\*banana\*\* series supports this field. seedream / chat\_image generate by \`size\` — use the \`size\` parameter instead. ### output\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`png\` Output image format. - \`png\` — lossless, supports transparency. - \`jpeg\` — smaller file size, no transparency. ### watermark - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Add an AI-generated content watermark. Only effective for the seedream series; the banana series always embeds a non-removable invisible watermark, and the chat\_image series has no watermark control. ### template - \*\*Type:\*\* string - \*\*Required:\*\* Optional Generation template. - \`asset\_extraction\` — extract a subject from a scene. - \`character\_completion\` — complete a partial character. - \`t\_pose\` — generate a character in T-pose. - \`variants\` — generate design variations. - \`figure\` — generate a full-body figure. ## Request Example ### seedream\_v5 \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-image \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A high-fashion editorial portrait, dramatic studio lighting.", "model": "seedream\_v5", "size": "2K", "output\_format": "png", "watermark": false }' \`\`\` ### banana \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-image \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A cinematic product render of a glass sneaker on a dark stage.", "model": "banana", "size": "1248x832", "output\_format": "png" }' \`\`\` ### banana\_pro \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-image \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A cinematic product render of a glass sneaker on a dark stage.", "model": "banana\_pro", "size": "2K", "aspect\_ratio": "3:2", "output\_format": "png" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_image", "status": "success", "progress": 100, "output": { "generated\_image\_url": "https://cdn.tripo3d.ai/output/image.png" }, "credits\_consumed": 20.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:00:08Z" } } \`\`\` Request Parameters ------------------ ### Request Body modelstringdefault: seedream\_v4 Image generation model. Available models: * `seedream_v5` — latest quality, stronger prompt following. * `seedream_v4` — default balanced model. * `banana` — fast generation. * `banana_pro` — higher quality. * `banana2` — latest fast option. * `chat_image_1` — base image model. **Retiring 2026-10-23.** * `chat_image_1.5` — higher quality. **Retiring 2026-12-01.** * `chat_image_2` — latest, best quality. * `chat_image_2.5_flare` — 2.5 speed tier; quality on par with `chat_image_2`, noticeably faster. * `chat_image_2.5_sunburst` — 2.5 fidelity tier; best at preserving the rest of the image when editing. seedreambananachat\_image seedream:  * `seedream_v5` — latest quality, stronger prompt following. * `seedream_v4` — default balanced model. banana:  * `banana` — fast. * `banana_pro` — higher quality. * `banana2` — latest fast option. chat\_image:  * `chat_image_1` — base image model. **Retiring 2026-10-23.** * `chat_image_1.5` — higher quality. **Retiring 2026-12-01.** * `chat_image_2` — latest, best quality. * `chat_image_2.5_flare` — 2.5 speed tier. * `chat_image_2.5_sunburst` — 2.5 fidelity tier. promptstringRequired Text prompt for image generation. Supports Chinese and English. Notes * Recommended: ≤ 300 Chinese characters or ≤ 600 English words. * Put the most important elements first. * Negative prompts: append after `--no`. sizestringdefault: 2048x2048 Output image size. Accepts semantic keywords (e.g. 2K / 4K) or explicit WxH pixels (e.g. 2048x2048). Supported values vary by model — see tabs below. seedream\_v5seedream\_v4bananachat\_image seedream\_v5:  **Pick exactly one of the two ways below — they cannot be combined.** * **Resolution tier**: `2K` / `3K`. Describe the aspect ratio / shape in the prompt; the model decides the exact dimensions. * **Explicit pixels**: `WxH` (default `2048x2048`). Total pixels 3.69–10.40 MP, aspect ratio \[1:16, 16:1\]. seedream\_v4:  **Pick exactly one of the two ways below — they cannot be combined.** * **Resolution tier**: `2K` / `4K`. Describe the aspect ratio / shape in the prompt; the model decides the exact dimensions. * **Explicit pixels**: `WxH` (default `2048x2048`). Total pixels ~3.69–16.78 MP (min ~3.69 MP), aspect ratio \[1:16, 16:1\]. banana:  `banana`: fixed pixel sizes only — `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672`. Default when omitted: `2048x2048` (=2K). `banana_pro`: semantic keywords `1K` / `2K` / `4K`, or explicit `WxH` pixels. Default: `2K` (`2048x2048`). `banana2`: semantic keywords `0.5K` / `1K` / `2K` / `4K` only (`0.5K` is banana2-exclusive). Default: `2K`. chat\_image:  `chat_image_1` / `chat_image_1.5`: fixed sizes `1024x1024`, `1024x1536`, `1536x1024`, `auto`. Default: `auto`. `chat_image_2`, `chat_image_2.5_flare`, `chat_image_2.5_sunburst`: presets `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, `auto`. Default: `2048x2048`. A custom `WIDTHxHEIGHT` is also accepted when it satisfies all four rules: each edge at most `3840`px; both edges a multiple of `16`; the long edge no more than `3x` the short edge; total pixels between `655360` and `8294400`. For example `1536x864` works, while `1080x1920` is rejected because 1080 is not a multiple of 16 — use `1088x1920`. qualitystringdefault: low Rendering quality tier. Only `chat_image_2`, `chat_image_2.5_flare` and `chat_image_2.5_sunburst` accept this parameter; passing it with any other model returns an error. * `chat_image_2` — `low`, `medium`, `high`. * `chat_image_2.5_flare` / `chat_image_2.5_sunburst` — `low`, `medium`, `high`, `xhigh`, `max`. Omitting it is equivalent to `low`. Note this differs from OpenAI's own default of `auto`, and `auto` is **not** supported here — we need a known tier up front in order to price the request. `high`, `xhigh` and `max` cost more credits and take noticeably longer; `low` and `medium` are billed at the base price. See the Pricing page. backgroundstring Background handling. Only `chat_image_2.5_flare` and `chat_image_2.5_sunburst` support it — one of `auto`, `opaque` or `transparent`. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so the request still succeeds but the background is left to the model. `transparent` requires `output_format=png`. JPEG carries no alpha channel, so combining the two returns an error instead of silently flattening the transparency. aspect\_ratiostringdefault: 1:1 Output aspect ratio. Default `1:1` when omitted (banana series only; filled by the gateway when both `size` and `aspect_ratio` are absent). * `banana` / `banana_pro`: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. * `banana2` additionally supports `1:8`, `1:4`, `4:1`, `8:1`. Only the **banana** series supports this field. seedream / chat\_image generate by `size` — use the `size` parameter instead. output\_formatstringdefault: png Output image format. * `png` — lossless, supports transparency. * `jpeg` — smaller file size, no transparency. watermarkbooleandefault: false Add an AI-generated content watermark. Only effective for the seedream series; the banana series always embeds a non-removable invisible watermark, and the chat\_image series has no watermark control. templatestring Generation template. * `asset_extraction` — extract a subject from a scene. * `character_completion` — complete a partial character. * `t_pose` — generate a character in T-pose. * `variants` — generate design variations. * `figure` — generate a full-body figure. Examples -------- seedream\_v5Copy { "prompt": "A high-fashion editorial portrait, dramatic studio lighting.", "model": "seedream_v5", "size": "2K", "output_format": "png", "watermark": false } bananaCopy { "prompt": "A cinematic product render of a glass sneaker on a dark stage.", "model": "banana", "size": "1248x832", "output_format": "png"} banana\_proCopy { "prompt": "A cinematic product render of a glass sneaker on a dark stage.", "model": "banana_pro", "size": "2K", "aspect_ratio": "3:2", "output_format": "png"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_image", "status": "success", "progress": 100, "output": { "generated_image_url": "https://cdn.tripo3d.ai/output/image.png"}, "credits_consumed": 20.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:00:08Z"} } PreviousImage to Gaussian SplatNextImage to Image --- # Image to Image — Tripo Developers Image to Image ============== CopyDownload PDF \# Image to Image \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/image-to-image\` Generate or edit an image from reference images. Supports editing, style transfer, and multi-image fusion. ## Request Parameters ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`seedream\_v5\` Image editing model. - \`seedream\_v5\` — strongest editing, style transfer, and multi-image fusion. - \`banana\` — fast editing. - \`banana\_pro\` — higher quality editing. - \`banana2\` — latest fast editing. - \`chat\_image\_1\` — base image editing. \*\*Retiring 2026-10-23.\*\* - \`chat\_image\_1.5\` — higher quality editing. \*\*Retiring 2026-12-01.\*\* - \`chat\_image\_2\` — latest, best editing. - \`chat\_image\_2.5\_flare\` — 2.5 speed tier; noticeably faster than sunburst at the same cost. - \`chat\_image\_2.5\_sunburst\` — 2.5 fidelity tier; keeps untouched parts of the image closest to the original. ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Primary reference image. Accepts a public URL, \`file\_token\`, or \`task\_id\`.\*\*Choose exactly one\*\* — do not pass multiple types simultaneously. - Formats: \`jpeg\`, \`png\` (recommended); \`webp\` is rejected on some provider routes - Max file size: \*\*20 MB\*\* - Max total pixels: \*\*6000 × 6000 = 36 MP\*\* - Min width/height: 14 px - Aspect ratio (W/H): \*\*\[1/3, 3\]\*\* - URL images must be publicly accessible. Private files require \`/v3/files\` first. ### inputs - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Optional Multiple reference images. Each follows the same format as \`input\`. - Max: \*\*4\*\* (seedream), \*\*10\*\* (banana), \*\*16\*\* (chat\_image) - Reference: \`image\[1\]\`, \`image\[2\]\`, etc. ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Conditional Editing instruction. \*\*Required when no template is specified.\*\* ### size - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`2048x2048\` Output image size. Accepts semantic keywords (e.g. 2K / 4K) or explicit WxH pixels (e.g. 2048x2048). Supported values vary by model — see tabs below. ### quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`low\` Rendering quality tier. Only \`chat\_image\_2\`, \`chat\_image\_2.5\_flare\` and \`chat\_image\_2.5\_sunburst\` accept this parameter; passing it with any other model returns an error. - \`chat\_image\_2\` — \`low\`, \`medium\`, \`high\`. - \`chat\_image\_2.5\_flare\` / \`chat\_image\_2.5\_sunburst\` — \`low\`, \`medium\`, \`high\`, \`xhigh\`, \`max\`. Omitting it is equivalent to \`low\`. Note this differs from OpenAI's own default of \`auto\`, and \`auto\` is \*\*not\*\* supported here — we need a known tier up front in order to price the request. \`high\`, \`xhigh\` and \`max\` cost more credits and take noticeably longer; \`low\` and \`medium\` are billed at the base price. See the Pricing page. ### background - \*\*Type:\*\* string - \*\*Required:\*\* Optional Background handling. Only \`chat\_image\_2.5\_flare\` and \`chat\_image\_2.5\_sunburst\` support it — one of \`auto\`, \`opaque\` or \`transparent\`. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so the request still succeeds but the background is left to the model. \`transparent\` requires \`output\_format=png\`. JPEG carries no alpha channel, so combining the two returns an error instead of silently flattening the transparency. ### aspect\_ratio - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`1:1\` Output aspect ratio. Default \`1:1\` when omitted (banana series only; filled by the gateway when both \`size\` and \`aspect\_ratio\` are absent). - \`banana\` / \`banana\_pro\`: \`1:1\`, \`2:3\`, \`3:2\`, \`3:4\`, \`4:3\`, \`4:5\`, \`5:4\`, \`9:16\`, \`16:9\`, \`21:9\`. - \`banana2\` additionally supports \`1:8\`, \`1:4\`, \`4:1\`, \`8:1\`. Only the \*\*banana\*\* series supports this field. seedream / chat\_image generate by \`size\` — use the \`size\` parameter instead. ### template - \*\*Type:\*\* string - \*\*Required:\*\* Optional Editing template. When set, \`prompt\` becomes optional. - \`t\_pose\` — convert to T-pose. - \`character\_completion\` — complete a partial character. - \`3d\_enhance\` — enhance for 3D generation. - \`variants\` — generate design variations. - \`figure\` — generate a full-body figure. ### output\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`png\` Output image format. - \`png\` — lossless, supports transparency. - \`jpeg\` — smaller file size, no transparency. ## Request Example ### Single image \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-image \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/reference.png", "prompt": "Change the silver outfit into transparent glass.", "model": "seedream\_v5", "size": "2K" }' \`\`\` ### Multi-image \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-image \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ "https://example.com/photo1.png", "https://example.com/photo2.png" \], "prompt": "Use character from image\[1\] and outfit from image\[2\].", "model": "seedream\_v5" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "image\_to\_image", "status": "success", "progress": 100, "output": { "generated\_image\_url": "https://cdn.tripo3d.ai/output/image.png" }, "credits\_consumed": 20.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:00:08Z" } } \`\`\` Request Parameters ------------------ ### Request Body modelstringdefault: seedream\_v5 Image editing model. * `seedream_v5` — strongest editing, style transfer, and multi-image fusion. * `banana` — fast editing. * `banana_pro` — higher quality editing. * `banana2` — latest fast editing. * `chat_image_1` — base image editing. **Retiring 2026-10-23.** * `chat_image_1.5` — higher quality editing. **Retiring 2026-12-01.** * `chat_image_2` — latest, best editing. * `chat_image_2.5_flare` — 2.5 speed tier; noticeably faster than sunburst at the same cost. * `chat_image_2.5_sunburst` — 2.5 fidelity tier; keeps untouched parts of the image closest to the original. seedreambananachat\_image seedream:  * `seedream_v5` — strongest editing, style transfer, and multi-image fusion. banana:  * `banana` — fast. * `banana_pro` — higher quality. * `banana2` — latest fast option. chat\_image:  * `chat_image_1` — base image editing. **Retiring 2026-10-23.** * `chat_image_1.5` — higher quality. **Retiring 2026-12-01.** * `chat_image_2` — latest, best quality. * `chat_image_2.5_flare` — 2.5 speed tier. * `chat_image_2.5_sunburst` — 2.5 fidelity tier. inputstringRequired Primary reference image. Accepts a public URL, `file_token`, or `task_id`. **Choose exactly one** — do not pass multiple types simultaneously. seedreambananachat\_image seedream:  * Single: `input`. Multiple: `inputs`, up to 4. * Accepted: public URL, `file_token`, or image task output. banana:  * Up to 10 reference images. * Reference: `image[1]`, `image[2]`, etc. chat\_image:  * Up to 16 reference images. * Reference: `image[1]`, `image[2]`, etc. Notes * Formats: `jpeg`, `png` (recommended); `webp` is rejected on some provider routes * Max file size: **20 MB** * Max total pixels: **6000 × 6000 = 36 MP** * Min width/height: 14 px * Aspect ratio (W/H): **\[1/3, 3\]** * URL images must be publicly accessible. Private files require `/v3/files` first. inputsstring\[\] Multiple reference images. Each follows the same format as `input`. seedreambananachat\_image seedream:  * Single: `input`. Multiple: `inputs`, up to 4. * Accepted: public URL, `file_token`, or image task output. banana:  * Up to 10 reference images. * Reference: `image[1]`, `image[2]`, etc. chat\_image:  * Up to 16 reference images. * Reference: `image[1]`, `image[2]`, etc. Notes * Max: **4** (seedream), **10** (banana), **16** (chat\_image) * Reference: `image[1]`, `image[2]`, etc. promptstringConditional Editing instruction. **Required when no template is specified.** sizestringdefault: 2048x2048 Output image size. Accepts semantic keywords (e.g. 2K / 4K) or explicit WxH pixels (e.g. 2048x2048). Supported values vary by model — see tabs below. seedream\_v5bananachat\_image seedream\_v5:  **Pick exactly one of the two ways below — they cannot be combined.** * **Resolution tier**: `2K` / `3K`. Describe the aspect ratio / shape in the prompt; the model decides the exact dimensions. * **Explicit pixels**: `WxH` (default `2048x2048`). Total pixels 3.69–10.40 MP, aspect ratio \[1:16, 16:1\]. banana:  `banana`: fixed pixel sizes only — `1024x1024`, `832x1248`, `1248x832`, `864x1184`, `1184x864`, `896x1152`, `1152x896`, `768x1344`, `1344x768`, `1536x672`. Default when omitted: `2048x2048` (=2K). `banana_pro`: semantic keywords `1K` / `2K` / `4K`, or explicit `WxH` pixels. Default: `2K` (`2048x2048`). `banana2`: semantic keywords `0.5K` / `1K` / `2K` / `4K` only (`0.5K` is banana2-exclusive). Default: `2K`. chat\_image:  `chat_image_1` / `chat_image_1.5`: fixed sizes `1024x1024`, `1024x1536`, `1536x1024`, `auto`. Default: `auto`. `chat_image_2`, `chat_image_2.5_flare`, `chat_image_2.5_sunburst`: presets `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, `auto`. Default: `2048x2048`. A custom `WIDTHxHEIGHT` is also accepted when it satisfies all four rules: each edge at most `3840`px; both edges a multiple of `16`; the long edge no more than `3x` the short edge; total pixels between `655360` and `8294400`. For example `1536x864` works, while `1080x1920` is rejected because 1080 is not a multiple of 16 — use `1088x1920`. qualitystringdefault: low Rendering quality tier. Only `chat_image_2`, `chat_image_2.5_flare` and `chat_image_2.5_sunburst` accept this parameter; passing it with any other model returns an error. * `chat_image_2` — `low`, `medium`, `high`. * `chat_image_2.5_flare` / `chat_image_2.5_sunburst` — `low`, `medium`, `high`, `xhigh`, `max`. Omitting it is equivalent to `low`. Note this differs from OpenAI's own default of `auto`, and `auto` is **not** supported here — we need a known tier up front in order to price the request. `high`, `xhigh` and `max` cost more credits and take noticeably longer; `low` and `medium` are billed at the base price. See the Pricing page. backgroundstring Background handling. Only `chat_image_2.5_flare` and `chat_image_2.5_sunburst` support it — one of `auto`, `opaque` or `transparent`. Omit it to let the model decide. Passing it with any other model is ignored rather than rejected, so the request still succeeds but the background is left to the model. `transparent` requires `output_format=png`. JPEG carries no alpha channel, so combining the two returns an error instead of silently flattening the transparency. aspect\_ratiostringdefault: 1:1 Output aspect ratio. Default `1:1` when omitted (banana series only; filled by the gateway when both `size` and `aspect_ratio` are absent). * `banana` / `banana_pro`: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. * `banana2` additionally supports `1:8`, `1:4`, `4:1`, `8:1`. Only the **banana** series supports this field. seedream / chat\_image generate by `size` — use the `size` parameter instead. templatestring Editing template. When set, `prompt` becomes optional. * `t_pose` — convert to T-pose. * `character_completion` — complete a partial character. * `3d_enhance` — enhance for 3D generation. * `variants` — generate design variations. * `figure` — generate a full-body figure. output\_formatstringdefault: png Output image format. * `png` — lossless, supports transparency. * `jpeg` — smaller file size, no transparency. Examples -------- Single imageCopy { "input": "https://example.com/reference.png", "prompt": "Change the silver outfit into transparent glass.", "model": "seedream_v5", "size": "2K"} Multi-imageCopy { "inputs": [\ "https://example.com/photo1.png",\ "https://example.com/photo2.png"], "prompt": "Use character from image[1] and outfit from image[2].", "model": "seedream_v5"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "image_to_image", "status": "success", "progress": 100, "output": { "generated_image_url": "https://cdn.tripo3d.ai/output/image.png"}, "credits_consumed": 20.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:00:08Z"} } PreviousText to ImageNextImage to Multiview --- # Image to Multiview — Tripo Developers Image to Multiview ================== CopyDownload PDF \# Image to Multiview \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/image-to-multiview\` Generate multiview images from a single image. Useful as preprocessing for multiview-to-model, or for turntable previews. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Source image for multiview generation. Accepts the following input types:\*\*Choose exactly one\*\* — do not pass multiple types simultaneously. - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/character.png\` - Formats: \`PNG\`, \`JPEG\`, \`WebP\` - Subject should be clearly visible against a clean background. ## Request Example ### Basic \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-multiview \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/character.png" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "status": "success", "output": { "front\_view\_url": "https://cdn.tripo3d.ai/front.png", "left\_view\_url": "https://cdn.tripo3d.ai/left.png", "back\_view\_url": "https://cdn.tripo3d.ai/back.png", "right\_view\_url": "https://cdn.tripo3d.ai/right.png" } } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Source image for multiview generation. Accepts the following input types: **Choose exactly one** — do not pass multiple types simultaneously. * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/character.png` Notes * Formats: `PNG`, `JPEG`, `WebP` * Subject should be clearly visible against a clean background. Examples -------- BasicCopy { "input": "https://example.com/character.png"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "status": "success", "output": { "front_view_url": "https://cdn.tripo3d.ai/front.png", "left_view_url": "https://cdn.tripo3d.ai/left.png", "back_view_url": "https://cdn.tripo3d.ai/back.png", "right_view_url": "https://cdn.tripo3d.ai/right.png"} } } PreviousImage to ImageNextEdit Multiview --- # Edit Multiview — Tripo Developers Edit Multiview ============== CopyDownload PDF \# Edit Multiview \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/edit-multiview\` Edit existing multiview images. Apply consistent changes across all views. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Source multiview image to edit. Accepts the following input types:\*\*Choose exactly one\*\* — do not pass multiple types simultaneously. - task\_id — The task ID from a previous multiview generation task. The system automatically uses the output multiview image. To generate multiview images first, use the Image to Multiview API. Example: \`task\_abc123\` - file\_token — Upload a multiview image via the File Upload API first. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a multiview image. Example: \`https://example.com/multiview.png\` ### prompts - \*\*Type:\*\* object\[\] - \*\*Required:\*\* Required A list of edit instructions, each targeting a specific view. Each item contains: - prompt — The edit instruction describing the desired change. Example: \`change the shirt color to red\` - view — The view to apply the edit to. - \`front\` — front view - \`left\` — left view - \`back\` — back view - \`right\` — right view ## Request Example ### Edit views \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/edit-multiview \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "prompts": \[ { "prompt": "change the shirt color to red", "view": "front" }, { "prompt": "add a logo on the back", "view": "back" } \] }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Source multiview image to edit. Accepts the following input types: **Choose exactly one** — do not pass multiple types simultaneously. * task\_id — The task ID from a previous multiview generation task. The system automatically uses the output multiview image. To generate multiview images first, use the [Image to Multiview API](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) . Example: `task_abc123` * file\_token — Upload a multiview image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first. Example: `file_abc123` * URL — A publicly accessible direct link to a multiview image. Example: `https://example.com/multiview.png` promptsobject\[\]Required A list of edit instructions, each targeting a specific view. Each item contains: * prompt — The edit instruction describing the desired change. Example: `change the shirt color to red` * view — The view to apply the edit to. * `front` — front view * `left` — left view * `back` — back view * `right` — right view Examples -------- Edit viewsCopy { "input": "task_abc123", "prompts": [\ {\ "prompt": "change the shirt color to red",\ "view": "front"},\ {\ "prompt": "add a logo on the back",\ "view": "back"}\ ] } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } PreviousImage to MultiviewNextTexture --- # Texture — Tripo Developers Texture ======= CopyDownload PDF \# Texture \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /models/texture\` Regenerate texture maps for an existing model. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`v3.0-20250812\` Texture model version. Choose based on the generation model used for the source 3D model: - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default. Recommended for models generated with \`v3.0-20250812\` or \`v3.1-20260211\`. - \`v2.5-20250123\` — recommended for models generated with \`v2.5-20250123\`. ### texture\_prompt - \*\*Type:\*\* object - \*\*Required:\*\* Optional Texture guidance input. Optional if the model was generated via Tripo.\*\*\`text\` / \`image\` / \`images\` are mutually exclusive — use exactly one (\`style\_image\` may accompany \`text\`).\*\* - text — A text prompt describing the desired texture style. Example: \`{"text": "worn leather with scratches"}\` - style\_image — A reference image to influence artistic style. Only used with \`text\` mode. Accepts \`file\_token\` or \`url\`. Recommended resolution: at least 256×256 px. Example: \`{"text": "cyberpunk style", "style\_image": {"url": "https://..."}}\` - image — A single reference image for texture generation. Accepts file\_token or URL. - images — A list of exactly 4 reference images in the order \[front, left, back, right\] for multi-angle texture guidance. - When initiating a texture task based on an existing task\_id, it is \*\*strongly recommended\*\* to re-supply the reference image in this request. - \`text\`, \`image\`, and \`images\` are mutually exclusive. - Optional \`style\_image\` can be added alongside \`text\` to influence artistic style. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material generation. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### part\_names - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Optional List of part names from a previous mesh segmentation task. If omitted, all parts are textured. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### bake - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Bake advanced material effects into base textures for broader compatibility. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ## Request Example ### Basic (v2.5 model) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/texture \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v2.5-20250123", "texture\_quality": "detailed", "pbr": true }' \`\`\` ### Fast (v3.5 model) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/texture \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v3.5-20260815", "texture\_quality": "fast", "delight": true, "pbr": true }' \`\`\` ### For v3.x model \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/texture \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v3.0-20250812", "texture\_quality": "detailed", "pbr": true }' \`\`\` ### With prompt \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/texture \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v3.0-20250812", "texture\_prompt": { "text": "worn leather with scratches" }, "texture\_quality": "detailed" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** modelstringdefault: v3.0-20250812 Texture model version. Choose based on the generation model used for the source 3D model: * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default. Recommended for models generated with `v3.0-20250812` or `v3.1-20260211`. * `v2.5-20250123` — recommended for models generated with `v2.5-20250123`. texture\_promptobject Texture guidance input. Optional if the model was generated via Tripo. **`text` / `image` / `images` are mutually exclusive — use exactly one (`style_image` may accompany `text`).** * text — A text prompt describing the desired texture style. Example: `{"text": "worn leather with scratches"}` * style\_image — A reference image to influence artistic style. Only used with `text` mode. Accepts `file_token` or `url`. Recommended resolution: at least 256×256 px. Example: `{"text": "cyberpunk style", "style_image": {"url": "https://..."}}` * image — A single reference image for texture generation. Accepts file\_token or URL. * images — A list of exactly 4 reference images in the order \[front, left, back, right\] for multi-angle texture guidance. Notes * When initiating a texture task based on an existing task\_id, it is **strongly recommended** to re-supply the reference image in this request. * `text`, `image`, and `images` are mutually exclusive. * Optional `style_image` can be added alongside `text` to influence artistic style. pbrbooleandefault: true Enable PBR material generation. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. part\_namesstring\[\] List of part names from a previous mesh segmentation task. If omitted, all parts are textured. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. bakebooleandefault: true Bake advanced material effects into base textures for broader compatibility. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. Examples -------- Basic (v2.5 model)Copy { "input": "task_abc123", "model": "v2.5-20250123", "texture_quality": "detailed", "pbr": true } Fast (v3.5 model)Copy { "input": "task_abc123", "model": "v3.5-20260815", "texture_quality": "fast", "delight": true, "pbr": true } For v3.x modelCopy { "input": "task_abc123", "model": "v3.0-20250812", "texture_quality": "detailed", "pbr": true } With promptCopy { "input": "task_abc123", "model": "v3.0-20250812", "texture_prompt": { "text": "worn leather with scratches"}, "texture_quality": "detailed"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousEdit MultiviewNextSegmentation --- # Segmentation — Tripo Developers Mesh Segmentation ================= CopyDownload PDF \# Mesh Segmentation \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /mesh/segment\` Perform semantic segmentation on a 3D model and automatically split it into parts. Supports v1 (geometry-based, default) and v2 (semantic labeling + geometry, Beta). ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`v1.0-20250506\` Segmentation model version. - \`v1.0-20250506\` — default, geometry-based segmentation. - \`v2.0-20260430\` Beta — semantic segmentation with labeling. ### segmentation\_granularity - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`balanced\` \*\*v2 only.\*\* Segmentation granularity. - \`simple\` - \`balanced\` — default - \`detailed\` ### split\_by\_connectivity - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` \*\*v2 only.\*\* Whether to split by connected components. ### ref\_image - \*\*Type:\*\* string - \*\*Required:\*\* Optional \*\*v2 only.\*\* Optional reference image for semantic analysis. Accepts \`file\_token\` (from file upload) or a public URL.When \`ref\_image\` is provided, \`segmentation\_granularity\` and \`split\_by\_connectivity\` are \*\*ignored\*\*. Left: 3D model (.glb)  |  Right: segmentation mask used as \`ref\_image\` ## Request Example ### Segment (v1) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/segment \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123" }' \`\`\` ### Segment (v2 + granularity) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/segment \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "model": "v2.0-20260430", "input": "task\_abc123", "segmentation\_granularity": "balanced", "split\_by\_connectivity": true }' \`\`\` ### Segment (v2 + ref\_image) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/segment \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "model": "v2.0-20260430", "input": "task\_abc123", "ref\_image": "file\_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_def456", "type": "mesh\_segmentation", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/mesh\_seg.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/mesh\_seg.webp" }, "credits\_consumed": 40.00, "created\_at": "2026-05-27T02:22:56Z", "completed\_at": "2026-05-27T02:25:33Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** modelstringdefault: v1.0-20250506 Segmentation model version. * `v1.0-20250506` — default, geometry-based segmentation. * `v2.0-20260430` Beta — semantic segmentation with labeling. segmentation\_granularitystringdefault: balanced **v2 only.** Segmentation granularity. * `simple` * `balanced` — default * `detailed` split\_by\_connectivitybooleandefault: true **v2 only.** Whether to split by connected components. ref\_imagestring **v2 only.** Optional reference image for semantic analysis. Accepts `file_token` (from file upload) or a public URL. When `ref_image` is provided, `segmentation_granularity` and `split_by_connectivity` are **ignored**. ![ref_image example: 3D model (.glb) on the left, color-coded segmentation mask (ref_image) on the right](https://developers.tripo3d.ai/assets/images/docs/ref-image-example.png) Left: 3D model (.glb)  |  Right: segmentation mask used as `ref_image` Examples -------- Segment (v1)Copy { "input": "task_abc123"} Segment (v2 + granularity)Copy { "model": "v2.0-20260430", "input": "task_abc123", "segmentation_granularity": "balanced", "split_by_connectivity": true } Segment (v2 + ref\_image)Copy { "model": "v2.0-20260430", "input": "task_abc123", "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_def456", "type": "mesh_segmentation", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/mesh_seg.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/mesh_seg.webp"}, "credits_consumed": 40.00, "created_at": "2026-05-27T02:22:56Z", "completed_at": "2026-05-27T02:25:33Z"} } PreviousTextureNextSmart Segmentation --- # Mesh Complete — Tripo Developers Mesh Part Completion ==================== CopyDownload PDF \# Mesh Part Completion \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /mesh/complete\` Complete segmented mesh parts and repair missing regions. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required task\_id of a \`mesh/segment\` task, starting with \`task\_\`. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`v1.0-20250506\` Completion model version. - \`v1.0-20250506\` — default (current only version). ### part\_names - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Optional List of part names to complete. If omitted, all parts are completed. ### completion\_mode - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`ai\_completion\` Completion mode. - \`ai\_completion\` — AI diffusion-based completion (default). Generates realistic geometry to fill missing regions. - \`quick\_cap\` — Quick hole-fill. Fast sealing of open boundaries without AI generation. ## Request Example ### Complete (AI) \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/complete \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "part\_names": \[ "head", "body" \] }' \`\`\` ### Quick Cap \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/complete \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "completion\_mode": "quick\_cap" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired task\_id of a `mesh/segment` task, starting with `task_`. modelstringdefault: v1.0-20250506 Completion model version. * `v1.0-20250506` — default (current only version). part\_namesstring\[\] List of part names to complete. If omitted, all parts are completed. completion\_modestringdefault: ai\_completion Completion mode. * `ai_completion` — AI diffusion-based completion (default). Generates realistic geometry to fill missing regions. * `quick_cap` — Quick hole-fill. Fast sealing of open boundaries without AI generation. Examples -------- Complete (AI)Copy { "input": "task_abc123", "part_names": [\ "head",\ "body"] } Quick CapCopy { "input": "task_abc123", "completion_mode": "quick_cap"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousSmart SegmentationNextRetopology --- # Retopology — Tripo Developers Retopology ========== CopyDownload PDF \# Retopology \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /mesh/decimate\` Reduce model polycount with two algorithm tiers. Use model=v2.0 (default) for smart highpoly-to-lowpoly retopology with clean topology preservation, or model=v1.0 for basic decimation. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id or file\_token. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`v2.0\` Retopology algorithm version. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Conditional Target polycount. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Output a quad mesh. Supported by both v1.0 and v2.0. ### bake - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` - \*\*Note:\*\* v1.0 does not support this parameter. Bake textures onto the low-poly model. ### part\_names - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Optional - \*\*Note:\*\* v1.0 does not support this parameter. Names of parts to decimate (from segmentation). ## Request Example ### v2.0 Smart \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/decimate \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v2.0", "face\_limit": 5000, "quad": false, "bake": true }' \`\`\` ### v1.0 Basic \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/mesh/decimate \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v1.0", "face\_limit": 3000 }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id or file\_token. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** modelstringdefault: v2.0 Retopology algorithm version. v2.0 (30 credits)v1.0 (10 credits) v2.0 (30 credits): **Smart Retopology** — rebuilds clean topology with edge preservation and detail retention. * `face_limit`: optional. Triangle: 500–20,000; Quad: 500–10,000. Adaptive if omitted. * `quad`: supported * `bake`: supported (default true) * `part_names`: supported * `format`: not supported (output GLB) v1.0 (10 credits): **Basic Decimation** — post-processing pipeline decimation. * `face_limit`: **required**. Triangle up to 2,000,000; Quad up to 150,000. * `quad`: supported * `bake`, `part_names`: not supported face\_limitintegerConditional Target polycount. v2.0v1.0 v2.0: Optional. Triangle: 500–20,000. Quad: 500–10,000. Omit for adaptive reduction. v1.0: Required. Maximum polycount by mode: Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | quadbooleandefault: false Output a quad mesh. Supported by both v1.0 and v2.0. bakebooleandefault: true v1.0 does not support this parameter. Bake textures onto the low-poly model. part\_namesstring\[\] v1.0 does not support this parameter. Names of parts to decimate (from segmentation). Examples -------- v2.0 SmartCopy { "input": "task_abc123", "model": "v2.0", "face_limit": 5000, "quad": false, "bake": true } v1.0 BasicCopy { "input": "task_abc123", "model": "v1.0", "face_limit": 3000 } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousMesh CompleteNextConvert Format --- # Convert Format — Tripo Developers Model Format Conversion ======================= CopyDownload PDF \# Model Format Conversion \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /models/convert\` Convert a 3D model to another format with optional mesh processing, texture baking, and export settings. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id or file\_token. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ### format - \*\*Type:\*\* string - \*\*Required:\*\* Required Target export format. - \`GLTF\` — web viewers, WebGL engines. - \`FBX\` — Unreal, Unity, DCC tools. - \`USDZ\` — Apple AR Quick Look. - \`OBJ\` — legacy exchange, no animation. - \`STL\` — 3D printing, geometry only. - \`3MF\` — 3D with single color. - \`GLTF\` — web viewers, WebGL engines (Three.js, Babylon.js). - \`FBX\` — Unreal, Unity, DCC tools (Maya, Blender). - \`USDZ\` — Apple AR Quick Look, RealityKit. - \`OBJ\` — legacy exchange, no animation. - \`STL\` / \`3MF\` — 3D printing, geometry only. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### force\_symmetry - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Force symmetry. Only valid when quad is true. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. If omitted, the original face count is preserved. ### flatten\_bottom - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Flatten the bottom of the model. ### flatten\_bottom\_threshold - \*\*Type:\*\* float - \*\*Required:\*\* Optional - \*\*Default:\*\* \`0.01\` Flattening depth threshold. ### texture\_size - \*\*Type:\*\* integer - \*\*Required:\*\* Optional - \*\*Default:\*\* \`4096\` Diffuse texture size in pixels. ### texture\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`JPEG\` Texture image format. - \`JPEG\` — default, smallest file size. - \`PNG\` — lossless, supports transparency. - \`WEBP\` — modern web format. - \`BMP\` / \`DPX\` / \`HDR\` / \`OPEN\_EXR\` / \`TARGA\` / \`TIFF\` — specialized use. ### bake - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Bake advanced materials into base textures. ### pack\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Pack all UVs into a unified layout. ### export\_vertex\_colors - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Include vertex colors. \*\*Only valid for \`OBJ\` and \`GLTF\`.\*\* ### pivot\_to\_center\_bottom - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Move the pivot to the bottom center. ### scale\_factor - \*\*Type:\*\* float - \*\*Required:\*\* Optional - \*\*Default:\*\* \`1\` Scale factor for the exported model. ### with\_animation - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Include skeleton and animation data. ### animate\_in\_place - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` In-place animation (no root displacement). ### part\_names - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Optional Names of parts to export, from mesh/segment data. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. ### fbx\_preset - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`blender\` FBX compatibility preset. - \`blender\` — optimized for Blender import. - \`3dsmax\` — optimized for 3ds Max import. - \`mixamo\` — compatible with Mixamo rigging. - \`bake\_scale\` — bakes the scale transform into the geometry on FBX export instead of leaving it on the node transform. ## Request Example ### To FBX \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/convert \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "format": "FBX", "texture\_size": 2048, "texture\_format": "PNG", "pivot\_to\_center\_bottom": true, "fbx\_preset": "blender" }' \`\`\` ### To GLTF \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/convert \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "format": "GLTF", "texture\_size": 4096, "bake": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id or file\_token. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** formatstringRequired Target export format. * `GLTF` — web viewers, WebGL engines. * `FBX` — Unreal, Unity, DCC tools. * `USDZ` — Apple AR Quick Look. * `OBJ` — legacy exchange, no animation. * `STL` — 3D printing, geometry only. * `3MF` — 3D with single color. Notes * `GLTF` — web viewers, WebGL engines (Three.js, Babylon.js). * `FBX` — Unreal, Unity, DCC tools (Maya, Blender). * `USDZ` — Apple AR Quick Look, RealityKit. * `OBJ` — legacy exchange, no animation. * `STL` / `3MF` — 3D printing, geometry only. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. force\_symmetrybooleandefault: false Force symmetry. Only valid when quad is true. face\_limitinteger Maximum polycount for the output mesh. If omitted, the original face count is preserved. flatten\_bottombooleandefault: false Flatten the bottom of the model. flatten\_bottom\_thresholdfloatdefault: 0.01 Flattening depth threshold. texture\_sizeintegerdefault: 4096 Diffuse texture size in pixels. texture\_formatstringdefault: JPEG Texture image format. * `JPEG` — default, smallest file size. * `PNG` — lossless, supports transparency. * `WEBP` — modern web format. * `BMP` / `DPX` / `HDR` / `OPEN_EXR` / `TARGA` / `TIFF` — specialized use. bakebooleandefault: true Bake advanced materials into base textures. pack\_uvbooleandefault: false Pack all UVs into a unified layout. export\_vertex\_colorsbooleandefault: false Include vertex colors. **Only valid for `OBJ` and `GLTF`.** pivot\_to\_center\_bottombooleandefault: false Move the pivot to the bottom center. scale\_factorfloatdefault: 1 Scale factor for the exported model. with\_animationbooleandefault: true Include skeleton and animation data. animate\_in\_placebooleandefault: false In-place animation (no root displacement). part\_namesstring\[\] Names of parts to export, from mesh/segment data. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. fbx\_presetstringdefault: blender FBX compatibility preset. * `blender` — optimized for Blender import. * `3dsmax` — optimized for 3ds Max import. * `mixamo` — compatible with Mixamo rigging. * `bake_scale` — bakes the scale transform into the geometry on FBX export instead of leaving it on the node transform. Examples -------- To FBXCopy { "input": "task_abc123", "format": "FBX", "texture_size": 2048, "texture_format": "PNG", "pivot_to_center_bottom": true, "fbx_preset": "blender"} To GLTFCopy { "input": "task_abc123", "format": "GLTF", "texture_size": 4096, "bake": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousRetopologyNextRig Check --- # Rig Check — Tripo Developers Riggability Check ================= CopyDownload PDF \# Riggability Check \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /animations/rig-check\` Check whether a model can be rigged and return the recommended rig type. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\` - Max file size: \*\*150 MB\*\* ## Response Fields ### riggable - \*\*Type:\*\* boolean - \*\*Required:\*\* Required Whether the model is riggable. ### rig\_type - \*\*Type:\*\* string - \*\*Required:\*\* Required Recommended rig type. - \`biped\` — humanoid, two legs. - \`quadruped\` — four-legged animal. - \`hexapod\` — six-legged creature. - \`octopod\` — eight-legged creature. - \`avian\` — bird / winged. - \`serpentine\` — snake-like. - \`aquatic\` — fish / aquatic. ## Request Example ### Check \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/animations/rig-check \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_def456", "status": "success", "output": { "riggable": true, "rig\_type": "biped" }, "credits\_consumed": 0.00 } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id, file\_token, or URL. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB` * Max file size: **150 MB** Response -------- riggablebooleanRequired Whether the model is riggable. rig\_typestringRequired Recommended rig type. * `biped` — humanoid, two legs. * `quadruped` — four-legged animal. * `hexapod` — six-legged creature. * `octopod` — eight-legged creature. * `avian` — bird / winged. * `serpentine` — snake-like. * `aquatic` — fish / aquatic. Examples -------- CheckCopy { "input": "task_abc123"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_def456", "status": "success", "output": { "riggable": true, "rig_type": "biped"}, "credits_consumed": 0.00 } } PreviousConvert FormatNextAuto Rig --- # Animation Retarget — Tripo Developers Animation Retargeting ===================== CopyDownload PDF \# Animation Retargeting \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /animations/retarget\` Apply a preset animation to a rigged 3D model. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required task\_id of the rigged model, starting with \`task\_\`. ### animation - \*\*Type:\*\* string - \*\*Required:\*\* Conditional Single preset animation identifier.\*\*Mutually exclusive with \`animations\` — provide only one.\*\* Rig v2.5-20260210 — All rig types - Biped: \`preset:idle\`, \`preset:walk\`, \`preset:run\`, \`preset:dive\`, \`preset:climb\`, \`preset:jump\`, \`preset:slash\`, \`preset:shoot\`, \`preset:hurt\`, \`preset:fall\`, \`preset:turn\` - Quadruped: \`preset:quadruped:walk\` - Others: \`preset:hexapod:walk\`, \`preset:octopod:walk\`, \`preset:serpentine:march\`, \`preset:aquatic:march\` Rig v1.0-20240301 — Biped only (90+ presets, click to expand)\`preset:biped:afraid\`\`preset:biped:agree\`\`preset:biped:angry\_01\`\`preset:biped:angry\_02\`\`preset:biped:angry\_03\`\`preset:biped:basketball\_shot\`\`preset:biped:bow\`\`preset:biped:box\_01\`\`preset:biped:box\_02\`\`preset:biped:box\_03\`\`preset:biped:cast\_a\_spell\`\`preset:biped:cheer\`\`preset:biped:chop\`\`preset:biped:clap\`\`preset:biped:climb\`\`preset:biped:complain\_01\`\`preset:biped:complain\_02\`\`preset:biped:cross\_body\_crunch\`\`preset:biped:crossover\_dribble\`\`preset:biped:cry\`\`preset:biped:dance\_01\`\`preset:biped:dance\_02\`\`preset:biped:dance\_03\`\`preset:biped:dance\_04\`\`preset:biped:dance\_05\`\`preset:biped:dance\_06\`\`preset:biped:defeat\_02\`\`preset:biped:defeat\_03\`\`preset:biped:depressed\`\`preset:biped:dig\`\`preset:biped:dive\`\`preset:biped:dribble\`\`preset:biped:fall\`\`preset:biped:fire\`\`preset:biped:flee\_01\`\`preset:biped:flee\_02\`\`preset:biped:flip\`\`preset:biped:fold\_arms\`\`preset:biped:football\_catch\`\`preset:biped:football\_save\`\`preset:biped:football\_pass\`\`preset:biped:freaky\`\`preset:biped:frightened\`\`preset:biped:front\_kick\_01\`\`preset:biped:front\_kick\_02\`\`preset:biped:frustrated\_01\`\`preset:biped:frustrated\_02\`\`preset:biped:golf\`\`preset:biped:greet\_01\`\`preset:biped:greet\_02\`\`preset:biped:greet\_03\`\`preset:biped:greet\_04\`\`preset:biped:heart\_pose\`\`preset:biped:hit\_to\_body\_01\`\`preset:biped:hit\_to\_body\_02\`\`preset:biped:hit\_to\_head\`\`preset:biped:hit\_to\_side\`\`preset:biped:hit\_to\_stomach\`\`preset:biped:hug\`\`preset:biped:hurt\`\`preset:biped:idle\`\`preset:biped:jump\_down\`\`preset:biped:jump\`\`preset:biped:jump\_rope\_01\`\`preset:biped:jump\_rope\_02\`\`preset:biped:laugh\_01\`\`preset:biped:laugh\_02\`\`preset:biped:lift\_heavy\`\`preset:biped:look\_around\`\`preset:biped:make\_a\_call\_01\`\`preset:biped:make\_a\_call\_02\`\`preset:biped:pitch\_baseball\`\`preset:biped:play\_mobile\_game\`\`preset:biped:play\_video\_game\`\`preset:biped:press-up\`\`preset:biped:run\_upstairs\`\`preset:biped:run\`\`preset:biped:scared\_01\`\`preset:biped:scared\_02\`\`preset:biped:scratch\`\`preset:biped:shoot\`\`preset:biped:shovel\`\`preset:biped:sing\_01\`\`preset:biped:sing\_02\`\`preset:biped:sing\_03\`\`preset:biped:sing\_04\`\`preset:biped:sit\`\`preset:biped:slash\`\`preset:biped:sob\`\`preset:biped:standing\_relax\`\`preset:biped:surf\`\`preset:biped:swagger\`\`preset:biped:swim\`\`preset:biped:turn\`\`preset:biped:victory\_celebration\`\`preset:biped:volleyball\`\`preset:biped:wait\`\`preset:biped:walk\`\`preset:biped:warm\_up\`\`preset:biped:wave\_goodbye\_01\`\`preset:biped:wave\_goodbye\_02\` ### animations - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Conditional List of multiple preset animation identifiers.\*\*Mutually exclusive with \`animation\` — provide only one.\*\* ### out\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`glb\` Output format. - \`glb\` — binary glTF, web-ready. - \`fbx\` — FBX for DCC tools and game engines. ### bake\_animation - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Bake animation into the model. Only effective for \`glb\` output. ### export\_with\_geometry - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Export with geometry included. ### animate\_in\_place - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Play animation in place without displacement. ## Request Example ### Single \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/animations/retarget \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "animation": "preset:walk", "out\_format": "glb", "bake\_animation": true }' \`\`\` ### Batch \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/animations/retarget \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "animations": \[ "preset:idle", "preset:walk", "preset:run" \], "out\_format": "fbx" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_def456", "status": "success", "output": { "model\_url": "https://cdn.tripo3d.ai/output/animated.glb" }, "credits\_consumed": 20.00 } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired task\_id of the rigged model, starting with `task_`. animationstringConditional Single preset animation identifier. **Mutually exclusive with `animations` — provide only one.** Notes Rig v2.5-20260210 — All rig types * Biped: `preset:idle`, `preset:walk`, `preset:run`, `preset:dive`, `preset:climb`, `preset:jump`, `preset:slash`, `preset:shoot`, `preset:hurt`, `preset:fall`, `preset:turn` * Quadruped: `preset:quadruped:walk` * Others: `preset:hexapod:walk`, `preset:octopod:walk`, `preset:serpentine:march`, `preset:aquatic:march` Rig v1.0-20240301 — Biped only (90+ presets, click to expand) `preset:biped:afraid``preset:biped:agree``preset:biped:angry_01``preset:biped:angry_02``preset:biped:angry_03``preset:biped:basketball_shot``preset:biped:bow``preset:biped:box_01``preset:biped:box_02``preset:biped:box_03``preset:biped:cast_a_spell``preset:biped:cheer``preset:biped:chop``preset:biped:clap``preset:biped:climb``preset:biped:complain_01``preset:biped:complain_02``preset:biped:cross_body_crunch``preset:biped:crossover_dribble``preset:biped:cry``preset:biped:dance_01``preset:biped:dance_02``preset:biped:dance_03``preset:biped:dance_04``preset:biped:dance_05``preset:biped:dance_06``preset:biped:defeat_02``preset:biped:defeat_03``preset:biped:depressed``preset:biped:dig``preset:biped:dive``preset:biped:dribble``preset:biped:fall``preset:biped:fire``preset:biped:flee_01``preset:biped:flee_02``preset:biped:flip``preset:biped:fold_arms``preset:biped:football_catch``preset:biped:football_save``preset:biped:football_pass``preset:biped:freaky``preset:biped:frightened``preset:biped:front_kick_01``preset:biped:front_kick_02``preset:biped:frustrated_01``preset:biped:frustrated_02``preset:biped:golf``preset:biped:greet_01``preset:biped:greet_02``preset:biped:greet_03``preset:biped:greet_04``preset:biped:heart_pose``preset:biped:hit_to_body_01``preset:biped:hit_to_body_02``preset:biped:hit_to_head``preset:biped:hit_to_side``preset:biped:hit_to_stomach``preset:biped:hug``preset:biped:hurt``preset:biped:idle``preset:biped:jump_down``preset:biped:jump``preset:biped:jump_rope_01``preset:biped:jump_rope_02``preset:biped:laugh_01``preset:biped:laugh_02``preset:biped:lift_heavy``preset:biped:look_around``preset:biped:make_a_call_01``preset:biped:make_a_call_02``preset:biped:pitch_baseball``preset:biped:play_mobile_game``preset:biped:play_video_game``preset:biped:press-up``preset:biped:run_upstairs``preset:biped:run``preset:biped:scared_01``preset:biped:scared_02``preset:biped:scratch``preset:biped:shoot``preset:biped:shovel``preset:biped:sing_01``preset:biped:sing_02``preset:biped:sing_03``preset:biped:sing_04``preset:biped:sit``preset:biped:slash``preset:biped:sob``preset:biped:standing_relax``preset:biped:surf``preset:biped:swagger``preset:biped:swim``preset:biped:turn``preset:biped:victory_celebration``preset:biped:volleyball``preset:biped:wait``preset:biped:walk``preset:biped:warm_up``preset:biped:wave_goodbye_01``preset:biped:wave_goodbye_02` animationsstring\[\]Conditional List of multiple preset animation identifiers. **Mutually exclusive with `animation` — provide only one.** out\_formatstringdefault: glb Output format. * `glb` — binary glTF, web-ready. * `fbx` — FBX for DCC tools and game engines. bake\_animationbooleandefault: true Bake animation into the model. Only effective for `glb` output. export\_with\_geometrybooleandefault: true Export with geometry included. animate\_in\_placebooleandefault: false Play animation in place without displacement. Examples -------- SingleCopy { "input": "task_abc123", "animation": "preset:walk", "out_format": "glb", "bake_animation": true } BatchCopy { "input": "task_abc123", "animations": [\ "preset:idle",\ "preset:walk",\ "preset:run"], "out_format": "fbx"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_def456", "status": "success", "output": { "model_url": "https://cdn.tripo3d.ai/output/animated.glb"}, "credits_consumed": 20.00 } } PreviousAuto RigNextTask Query --- # Auto Rig — Tripo Developers Auto Rigging ============ CopyDownload PDF \# Auto Rigging \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /animations/rig\` Automatically add a skeleton rig to a 3D model. Run rig-check first to verify compatibility. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model source. Accepts task\_id or file\_token. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - task\_id — The task ID returned by a previous 3D generation task (\`text\_to\_model\`, \`image\_to\_model\`, or \`multiview\_to\_model\`). The system automatically uses the 3D model output from that task. Example: \`task\_abc123\` - file\_token — Upload a 3D model file via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to a 3D model file. Example: \`https://example.com/model.glb\` - Supported formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ### model - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`v1.0-20240301\` Rigging model version. - \`v1.0-20240301\` — biped (humanoid) only. Recommended for humanoid characters. Supports 90+ animation presets. - \`v2.5-20260210\` — non-humanoid creatures (quadruped, hexapod, octopod, serpentine, aquatic, avian). ### rig\_type - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`biped\` Rig type. Recommend calling \`rig-check\` first. - \`biped\` — humanoid, two legs. - \`quadruped\` — four-legged animal. - \`hexapod\` — six-legged creature. - \`octopod\` — eight-legged creature. - \`avian\` — bird / winged. - \`serpentine\` — snake-like. - \`aquatic\` — fish / aquatic. ### spec - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`tripo\` Rigging specification. - \`tripo\` — Tripo native bone naming. - \`mixamo\` — Mixamo-compatible bone naming. ### out\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`glb\` Output format. - \`glb\` — binary glTF, web-ready. - \`fbx\` — FBX for DCC tools and game engines. ## Request Example ### Auto rig \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/animations/rig \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "task\_abc123", "model": "v2.5-20260210", "rig\_type": "biped", "spec": "mixamo", "out\_format": "glb" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_def456", "status": "success", "output": { "model\_url": "https://cdn.tripo3d.ai/output/rigged.glb" }, "credits\_consumed": 30.00 } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model source. Accepts task\_id or file\_token. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * task\_id — The task ID returned by a previous 3D generation task (`text_to_model`, `image_to_model`, or `multiview_to_model`). The system automatically uses the 3D model output from that task. Example: `task_abc123` * file\_token — Upload a 3D model file via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to a 3D model file. Example: `https://example.com/model.glb` Notes * Supported formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** modelstringdefault: v1.0-20240301 Rigging model version. * `v1.0-20240301` — biped (humanoid) only. Recommended for humanoid characters. Supports 90+ animation presets. * `v2.5-20260210` — non-humanoid creatures (quadruped, hexapod, octopod, serpentine, aquatic, avian). rig\_typestringdefault: biped Rig type. Recommend calling `rig-check` first. * `biped` — humanoid, two legs. * `quadruped` — four-legged animal. * `hexapod` — six-legged creature. * `octopod` — eight-legged creature. * `avian` — bird / winged. * `serpentine` — snake-like. * `aquatic` — fish / aquatic. specstringdefault: tripo Rigging specification. * `tripo` — Tripo native bone naming. * `mixamo` — Mixamo-compatible bone naming. out\_formatstringdefault: glb Output format. * `glb` — binary glTF, web-ready. * `fbx` — FBX for DCC tools and game engines. Examples -------- Auto rigCopy { "input": "task_abc123", "model": "v2.5-20260210", "rig_type": "biped", "spec": "mixamo", "out_format": "glb"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_def456", "status": "success", "output": { "model_url": "https://cdn.tripo3d.ai/output/rigged.glb"}, "credits_consumed": 30.00 } } PreviousRig CheckNextAnimation Retarget --- # Batch Task Query — Tripo Developers Batch Task Query ================ CopyDownload PDF \# Batch Task Query \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /tasks/list\` Query the status and output of multiple async tasks in a single request. Returns a map of task details keyed by task\_id, plus a list of any task IDs that were not found. ## Request Parameters ### task\_ids - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Required An array of task IDs to query. Maximum \*\*100\*\* items per request. Example: \`\["task\_abc123", "task\_def456"\]\` ## Response Fields ### tasks - \*\*Type:\*\* object - \*\*Required:\*\* Required A map of task details keyed by task\_id. Each value has the same structure as the single task query response. ### missed - \*\*Type:\*\* string\[\] - \*\*Required:\*\* Required List of task IDs that were not found (invalid ID, wrong API key, or expired). ## Request Example ### Batch query \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/tasks/list \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "task\_ids": \[ "task\_abc123", "task\_def456" \] }' \`\`\` ## Response Example ### Batch result \`\`\`json { "code": 0, "data": { "tasks": { "task\_abc123": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "credits\_consumed": 100.00 }, "task\_def456": { "task\_id": "task\_def456", "type": "image\_to\_model", "status": "running", "progress": 60 } }, "missed": \[\] } } \`\`\` Request Parameters ------------------ ### Request Body task\_idsstring\[\]Required An array of task IDs to query. Maximum **100** items per request. Example: `["task_abc123", "task_def456"]` Response -------- tasksobjectRequired A map of task details keyed by task\_id. Each value has the same structure as the single task query response. missedstring\[\]Required List of task IDs that were not found (invalid ID, wrong API key, or expired). Examples -------- Batch queryCopy { "task_ids": [\ "task_abc123",\ "task_def456"] } Batch resultCopy { "code": 0, "data": { "tasks": { "task_abc123": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "credits_consumed": 100.00 }, "task_def456": { "task_id": "task_def456", "type": "image_to_model", "status": "running", "progress": 60 } }, "missed": [] } } PreviousTask QueryNextFile Upload --- # Rate Limits — Tripo Developers Rate Limits & Concurrency ========================= CopyDownload PDF \# Rate Limits & Concurrency The Tripo API applies rate limits and concurrency limits to ensure service stability and fair usage. ## Rate Limits Rate limits restrict the number of API requests you can make within a time window. ### Limit Rules - Rate limits are calculated at the \*\*API Key\*\* level - Limits vary by endpoint. Generation endpoints, such as \`/v3/generation/\*\`, have lower limits, while query endpoints, such as \`/v3/tasks/\*\`, have higher limits - When a limit is exceeded, the API returns HTTP \`429 Too Many Requests\` with error code \`1007\` ### Response Headers Every API response includes rate-limit-related response headers: | Response Header | Description | | :-: | :-: | | \`X-RateLimit-Limit\` | Maximum number of requests allowed in the current time window | | \`X-RateLimit-Remaining\` | Number of remaining requests available in the current time window | | \`X-RateLimit-Reset\` | Unix timestamp, in seconds, when the rate limit window resets | ### Response When Rate Limited \`\`\`json { "code": 1007, "message": "Rate limit exceeded, you've generated too many requests in a short amount of time", "suggestion": "Please wait for a while and try again" } \`\`\` --- ## Concurrency Limits Concurrency limits restrict the number of tasks that can run \*\*simultaneously\*\* under your account. This is different from rate limits — rate limits cap request frequency, while concurrency limits cap parallel running tasks. ### How It Works - Concurrency is calculated at the \*\*account\*\* level (not per API Key) - Limits are applied \*\*per task category\*\* — each category has its own independent concurrency pool - When a category's concurrency is full, new task creation for that category returns HTTP \`429\` with error code \`2000\` - Tasks in other categories are \*\*not affected\*\* — you can still create tasks in categories that have available slots ### Default Limits All users start with a default concurrency of \*\*10\*\* per category; some categories have different limits (see the table below). | Category | Included Task Types | Default Concurrency | | :-: | :-: | :-: | | 3D Generation — H Series | text-to-model (H), image-to-model (H), multiview-to-model (H) | 10 | | 3D Generation — P Series | text-to-model (P), image-to-model (P), multiview-to-model (P) | 5 | | Image Generation | text-to-image, image-to-image, image-to-multiview, edit-multiview | 1 | | Animation | auto-rig, rig-check, animation-retarget | 10 | | Model Processing | texture, format-convert, refine | 5 | | Mesh Operations | segmentation, completion, retopology | 10 | > \*\*Note:\*\* Tasks within the same category share the concurrency pool. For example, if you have 10 H-series text-to-model tasks running, you cannot start an H-series image-to-model task until one completes. However, you can still start P-series or image generation tasks. ### Response When Concurrency Exceeded \`\`\`json { "code": 2000, "message": "You have exceeded the limit of generation", "suggestion": "Try again later. You can also check \`Retry-After\` header." } \`\`\` The response includes a \`Retry-After\` header indicating how many seconds to wait before retrying. ### Increasing Concurrency To request higher concurrency limits, please contact our team via the support channel. Custom concurrency can be configured per category based on your usage needs. --- ## Handling 429 Responses ### Python \`\`\`python import time import requests def request\_with\_backoff(method, url, headers, json=None, max\_retries=5): for attempt in range(max\_retries): response = requests.request(method, url, headers=headers, json=json) if response.status\_code != 429: return response retry\_after = response.headers.get("Retry-After") reset\_at = response.headers.get("X-RateLimit-Reset") if retry\_after: wait = int(retry\_after) elif reset\_at: wait = max(int(reset\_at) - int(time.time()), 1) else: wait = 2 \*\* attempt print(f"429 triggered. Waiting {wait} seconds (attempt {attempt + 1})...") time.sleep(wait) raise Exception("Maximum retry attempts exhausted") \`\`\` ### JavaScript \`\`\`javascript async function requestWithBackoff(url, options, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.status !== 429) { return response; } const retryAfter = response.headers.get("Retry-After"); const resetAt = response.headers.get("X-RateLimit-Reset"); const wait = retryAfter ? Number(retryAfter) : resetAt ? Math.max(Number(resetAt) - Math.floor(Date.now() / 1000), 1) : 2 \*\* attempt; console.log(\`429 triggered. Waiting ${wait} seconds (attempt ${attempt + 1})...\`); await new Promise(resolve => setTimeout(resolve, wait \* 1000)); } throw new Error("Maximum retry attempts exhausted"); } \`\`\` ## Best Practices - \*\*Implement exponential backoff retries\*\*: Wait 1 second initially, double the wait each time, and cap the maximum wait at 32 seconds - \*\*Prefer \`Retry-After\` and \`X-RateLimit-Reset\` headers\*\*: Wait precisely until the limit window resets - \*\*Design for category-level concurrency\*\*: Distribute workloads across categories when possible — image generation and 3D generation have separate pools - \*\*Use batch APIs\*\*: Use \`POST /v3/tasks/list\` instead of multiple \`GET /v3/tasks/{task\_id}\` requests - \*\*Poll wisely\*\*: When waiting for task completion, poll at reasonable intervals (every 1–2 seconds) rather than flooding the query endpoint Rate Limits & Concurrency ========================= The Tripo API applies rate limits and concurrency limits to ensure service stability and fair usage. Rate Limits ----------- Rate limits restrict the number of API requests you can make within a time window. ### Limit Rules * Rate limits are calculated at the **API Key** level * Limits vary by endpoint. Generation endpoints, such as `/v3/generation/*`, have lower limits, while query endpoints, such as `/v3/tasks/*`, have higher limits * When a limit is exceeded, the API returns HTTP `429 Too Many Requests` with error code `1007` ### Response Headers Every API response includes rate-limit-related response headers: | Response Header | Description | | --- | --- | | `X-RateLimit-Limit` | Maximum number of requests allowed in the current time window | | `X-RateLimit-Remaining` | Number of remaining requests available in the current time window | | `X-RateLimit-Reset` | Unix timestamp, in seconds, when the rate limit window resets | ### Response When Rate Limited JSONCopy { "code": 1007, "message": "Rate limit exceeded, you've generated too many requests in a short amount of time", "suggestion": "Please wait for a while and try again" } * * * Concurrency Limits ------------------ Concurrency limits restrict the number of tasks that can run **simultaneously** under your account. This is different from rate limits — rate limits cap request frequency, while concurrency limits cap parallel running tasks. ### How It Works * Concurrency is calculated at the **account** level (not per API Key) * Limits are applied **per task category** — each category has its own independent concurrency pool * When a category’s concurrency is full, new task creation for that category returns HTTP `429` with error code `2000` * Tasks in other categories are **not affected** — you can still create tasks in categories that have available slots ### Default Limits All users start with a default concurrency of **10** per category; some categories have different limits (see the table below). | Category | Included Task Types | Default Concurrency | | --- | --- | --- | | 3D Generation — H Series | text-to-model (H), image-to-model (H), multiview-to-model (H) | 10 | | 3D Generation — P Series | text-to-model (P), image-to-model (P), multiview-to-model (P) | 5 | | Image Generation | text-to-image, image-to-image, image-to-multiview, edit-multiview | 1 | | Animation | auto-rig, rig-check, animation-retarget | 10 | | Model Processing | texture, format-convert, refine | 5 | | Mesh Operations | segmentation, completion, retopology | 10 | > **Note:** Tasks within the same category share the concurrency pool. For example, if you have 10 H-series text-to-model tasks running, you cannot start an H-series image-to-model task until one completes. However, you can still start P-series or image generation tasks. ### Response When Concurrency Exceeded JSONCopy { "code": 2000, "message": "You have exceeded the limit of generation", "suggestion": "Try again later. You can also check `Retry-After` header." } The response includes a `Retry-After` header indicating how many seconds to wait before retrying. ### Increasing Concurrency To request higher concurrency limits, please contact our team via the support channel. Custom concurrency can be configured per category based on your usage needs. * * * Handling 429 Responses ---------------------- PythonJavaScript Copy import time import requests def request_with_backoff(method, url, headers, json=None, max_retries=5): for attempt in range(max_retries): response = requests.request(method, url, headers=headers, json=json) if response.status_code != 429: return response retry_after = response.headers.get("Retry-After") reset_at = response.headers.get("X-RateLimit-Reset") if retry_after: wait = int(retry_after) elif reset_at: wait = max(int(reset_at) - int(time.time()), 1) else: wait = 2 ** attempt print(f"429 triggered. Waiting {wait} seconds (attempt {attempt + 1})...") time.sleep(wait) raise Exception("Maximum retry attempts exhausted") async function requestWithBackoff(url, options, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.status !== 429) { return response; } const retryAfter = response.headers.get("Retry-After"); const resetAt = response.headers.get("X-RateLimit-Reset"); const wait = retryAfter ? Number(retryAfter) : resetAt ? Math.max(Number(resetAt) - Math.floor(Date.now() / 1000), 1) : 2 ** attempt; console.log(`429 triggered. Waiting ${wait} seconds (attempt ${attempt + 1})...`); await new Promise(resolve => setTimeout(resolve, wait * 1000)); } throw new Error("Maximum retry attempts exhausted"); } Best Practices -------------- * **Implement exponential backoff retries**: Wait 1 second initially, double the wait each time, and cap the maximum wait at 32 seconds * **Prefer `Retry-After` and `X-RateLimit-Reset` headers**: Wait precisely until the limit window resets * **Design for category-level concurrency**: Distribute workloads across categories when possible — image generation and 3D generation have separate pools * **Use batch APIs**: Use `POST /v3/tasks/list` instead of multiple `GET /v3/tasks/{task_id}` requests * **Poll wisely**: When waiting for task completion, poll at reasonable intervals (every 1–2 seconds) rather than flooding the query endpoint PreviousError HandlingNextWebhooks On this page --- # Error Handling — Tripo Developers Error Handling ============== CopyDownload PDF \# Error Handling ## Unified Error Response Format All API errors return a unified JSON format: \`\`\`json { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account at https://platform.tripo3d.ai", "request\_id": "req\_abc123" } \`\`\` | Field | Type | Description | | :-: | :-: | :-: | | code | integer | Error code | | message | string | Error description | | suggestion | string | Suggested fix | | request\_id | string | Unique request identifier for troubleshooting | ## HTTP Status Codes | Status Code | Meaning | Description | | :-: | :-: | :-: | | 200 | Success | The request was processed successfully | | 400 | Invalid parameters | Required parameters are missing or malformed | | 401 | Unauthenticated | The API Key is missing or invalid | | 403 | Insufficient permissions | You do not have permission to access the resource, or your credits are insufficient | | 404 | Resource not found | The requested task or resource does not exist | | 429 | Too many requests | Rate limit exceeded. Reduce your request frequency | | 500 | Service error | Internal server error. Try again later | ## Error Code Reference | Error Code | Meaning | Recommended Handling | | :-: | :-: | :-: | | 1000 | Invalid API Key | Check whether the API Key is correct or has been deleted | | 1001 | Unauthorized | Check whether the request header includes \`Authorization\` | | 2000 | Rate limit exceeded | Reduce request frequency and implement retries with exponential backoff | | 2002 | Unsupported request parameter | Check whether request body field names and values match the documentation | | 2003 | Empty input file | Confirm that the uploaded file is not empty and uses a valid format | | 2004 | Unsupported file type | Check whether the file format is in the supported list | | 2008 | Content policy violation | Modify the input content to avoid prohibited words or images | | 2010 | Insufficient credits | Top up credits in the console | | 2015 | Version deprecated | Upgrade to the latest API version | | 2018 | Model too complex | Reduce the complexity or polycount of the input model | ## Error Handling Examples ### Python \`\`\`python import time import requests def call\_api\_with\_retry(url, headers, payload=None, max\_retries=3): for attempt in range(max\_retries): if payload: response = requests.post(url, headers=headers, json=payload) else: response = requests.get(url, headers=headers) if response.status\_code == 200: return response.json() if response.status\_code == 429: wait = 2 \*\* attempt print(f"Rate limit triggered. Retrying in {wait} seconds...") time.sleep(wait) continue error = response.json() raise Exception( f"API error \[{error\['code'\]}\]: {error\['message'\]} " f"(suggestion: {error.get('suggestion', 'none')})" ) raise Exception("Maximum retry attempts exhausted") \`\`\` ### JavaScript \`\`\`javascript async function callApiWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.ok) { return await response.json(); } if (response.status === 429) { const wait = 2 \*\* attempt \* 1000; console.log(\`Rate limit triggered. Retrying in ${wait / 1000} seconds...\`); await new Promise(resolve => setTimeout(resolve, wait)); continue; } const error = await response.json(); throw new Error( \`API error \[${error.code}\]: ${error.message} (suggestion: ${error.suggestion || "none"})\` ); } throw new Error("Maximum retry attempts exhausted"); } \`\`\` ## Retry Strategy Recommendations For retryable errors, such as 429 rate limits and 500 service errors, use an exponential backoff strategy: 1. First retry: wait 1 second 2. Second retry: wait 2 seconds 3. Third retry: wait 4 seconds 4. Keep the maximum retry count at 5 or fewer For non-retryable errors, such as 400, 401, and 403, throw an exception directly and fix the underlying issue. Error Handling ============== Unified Error Response Format ----------------------------- All API errors return a unified JSON format: JSONCopy { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account at https://platform.tripo3d.ai", "request_id": "req_abc123" } | Field | Type | Description | | --- | --- | --- | | code | integer | Error code | | message | string | Error description | | suggestion | string | Suggested fix | | request\_id | string | Unique request identifier for troubleshooting | HTTP Status Codes ----------------- | Status Code | Meaning | Description | | --- | --- | --- | | 200 | Success | The request was processed successfully | | 400 | Invalid parameters | Required parameters are missing or malformed | | 401 | Unauthenticated | The API Key is missing or invalid | | 403 | Insufficient permissions | You do not have permission to access the resource, or your credits are insufficient | | 404 | Resource not found | The requested task or resource does not exist | | 429 | Too many requests | Rate limit exceeded. Reduce your request frequency | | 500 | Service error | Internal server error. Try again later | Error Code Reference -------------------- | Error Code | Meaning | Recommended Handling | | --- | --- | --- | | 1000 | Invalid API Key | Check whether the API Key is correct or has been deleted | | 1001 | Unauthorized | Check whether the request header includes `Authorization` | | 2000 | Rate limit exceeded | Reduce request frequency and implement retries with exponential backoff | | 2002 | Unsupported request parameter | Check whether request body field names and values match the documentation | | 2003 | Empty input file | Confirm that the uploaded file is not empty and uses a valid format | | 2004 | Unsupported file type | Check whether the file format is in the supported list | | 2008 | Content policy violation | Modify the input content to avoid prohibited words or images | | 2010 | Insufficient credits | Top up credits in the console | | 2015 | Version deprecated | Upgrade to the latest API version | | 2018 | Model too complex | Reduce the complexity or polycount of the input model | Error Handling Examples ----------------------- PythonJavaScript Copy import time import requests def call_api_with_retry(url, headers, payload=None, max_retries=3): for attempt in range(max_retries): if payload: response = requests.post(url, headers=headers, json=payload) else: response = requests.get(url, headers=headers) if response.status_code == 200: return response.json() if response.status_code == 429: wait = 2 ** attempt print(f"Rate limit triggered. Retrying in {wait} seconds...") time.sleep(wait) continue error = response.json() raise Exception( f"API error [{error['code']}]: {error['message']} " f"(suggestion: {error.get('suggestion', 'none')})" ) raise Exception("Maximum retry attempts exhausted") async function callApiWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.ok) { return await response.json(); } if (response.status === 429) { const wait = 2 ** attempt * 1000; console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`); await new Promise(resolve => setTimeout(resolve, wait)); continue; } const error = await response.json(); throw new Error( `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})` ); } throw new Error("Maximum retry attempts exhausted"); } Retry Strategy Recommendations ------------------------------ For retryable errors, such as 429 rate limits and 500 service errors, use an exponential backoff strategy: 1. First retry: wait 1 second 2. Second retry: wait 2 seconds 3. Third retry: wait 4 seconds 4. Keep the maximum retry count at 5 or fewer For non-retryable errors, such as 400, 401, and 403, throw an exception directly and fix the underlying issue. PreviousAccountNextRate Limits On this page --- # Webhooks — Tripo Developers Webhooks ======== CopyDownload PDF \# Webhooks \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST https://\` Tripo posts JSON to your HTTPS URL when a task completes or fails, or when credits fall below your alert threshold—so you do not need to poll \`GET /v3/tasks/{task\_id}\`.Setup - Open \*\*Settings → Webhooks\*\* and click \*\*Add Endpoint\*\*. - Enter your HTTPS URL (e.g. \`https://api.yourapp.com/tripo-webhook\`). - Select the event types to subscribe to. - Click \*\*Save Endpoint\*\*. - Copy the \*\*Signing Secret\*\* (\`whsec\_…\`) — shown only once; store it like an API key. Event types - \`task.completed\` — task finished successfully. - \`task.failed\` — task failed or was cancelled. - \`balance.low\` — balance dropped below the threshold in \*\*Billing → Credit alert\*\* (alerts do not by themselves fail tasks). RetriesIf your endpoint returns non-2xx or times out, Tripo retries automatically. Inspect failures under Settings → Webhooks → Recent deliveries. Best practices - Verify every payload with the signing secret before acting on it. - Return \`2xx\` within ~5s; do heavy work asynchronously. - Deduplicate using \`Tripo-Webhook-Delivery\`. - Enable \`balance.low\` alerts in Billing for early warning. ## Request Parameters ### id - \*\*Type:\*\* string - \*\*Required:\*\* Required Composite event identifier (e.g. task\_id + event type). ### type - \*\*Type:\*\* string - \*\*Required:\*\* Required One of \`task.completed\`, \`task.failed\`, \`balance.low\`. ### created\_at - \*\*Type:\*\* string - \*\*Required:\*\* Required ISO 8601 timestamp when the event was created. ### data - \*\*Type:\*\* object - \*\*Required:\*\* Required Event-specific payload. For task events it mirrors task output fields from the Task Query API; for balance.low it includes balance-related fields. - Task events: expect \`task\_id\`, \`type\`, \`status\`, and \`output\` (when successful). - \`balance.low\`: configure the threshold under Billing → Credit alert. ### Tripo-Webhook-Id - \*\*Type:\*\* header · string - \*\*Required:\*\* Required Webhook endpoint id on Tripo. ### Tripo-Webhook-Delivery - \*\*Type:\*\* header · string - \*\*Required:\*\* Required Unique delivery id — use for idempotency if the same logical event is delivered more than once. ### Tripo-Webhook-Event - \*\*Type:\*\* header · string - \*\*Required:\*\* Required Same as body \`type\` (e.g. task.completed). ### Tripo-Webhook-Signature - \*\*Type:\*\* header · string - \*\*Required:\*\* Required HMAC-SHA256 over \`{timestamp}.{raw\_body}\` using your signing secret. Format: \`t=,v1=\`. - Parse \`t\` and \`v1\` from the header. - Compute HMAC-SHA256(secret, \`t + "." + rawBody\`) as lowercase hex. - Compare with \`v1\` using a constant-time compare. - Optional: reject if \`t\` is older than ~5 minutes (replay protection). ### Content-Type - \*\*Type:\*\* header · string - \*\*Required:\*\* Required - \*\*Default:\*\* \`application/json\` Always application/json. ## Response Fields ### HTTP - \*\*Type:\*\* status - \*\*Required:\*\* Required Respond with 2xx quickly (within a few seconds). Return before heavy processing finishes. ## Request Example ### task.completed \`\`\` { "id": "task\_abc123:task.completed", "type": "task.completed", "created\_at": "2026-05-06T12:00:00Z", "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb" } } } \`\`\` ### balance.low \`\`\` { "id": "evt\_balance\_low:balance.low", "type": "balance.low", "created\_at": "2026-05-06T12:00:00Z", "data": { "balance": 1200, "threshold": 5000 } } \`\`\` ### Verify · Python \`\`\` import hmac import hashlib import time def verify\_webhook(payload: bytes, signature\_header: str, secret: str) -> bool: parts = dict(p.split("=", 1) for p in signature\_header.split(",")) timestamp = parts.get("t", "") expected\_sig = parts.get("v1", "") if abs(time.time() - int(timestamp)) > 300: return False computed = hmac.new( secret.encode("utf-8"), f"{timestamp}.{payload.decode('utf-8')}".encode("utf-8"), hashlib.sha256 ).hexdigest() return hmac.compare\_digest(computed, expected\_sig) \`\`\` ### Verify · JavaScript \`\`\` const crypto = require("crypto"); function verifyWebhook(payload, signatureHeader, secret) { const parts = Object.fromEntries( signatureHeader.split(",").map(p => p.split("=", 2)) ); const timestamp = parts.t; const expectedSig = parts.v1; if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) { return false; } const computed = crypto .createHmac("sha256", secret) .update(\`${timestamp}.${payload}\`) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(computed), Buffer.from(expectedSig) ); } \`\`\` ## Response Example ### Tripo-Webhook-Signature \`\`\`json Tripo-Webhook-Signature: t=1714992000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9 \`\`\` ### task.failed \`\`\`json { "id": "task\_abc123:task.failed", "type": "task.failed", "created\_at": "2026-05-06T12:00:05Z", "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "failed", "error": { "code": "task\_failed", "message": "Generation failed" } } } \`\`\` Request Parameters ------------------ ### Request Body idstringRequired Composite event identifier (e.g. task\_id + event type). typestringRequired One of `task.completed`, `task.failed`, `balance.low`. created\_atstringRequired ISO 8601 timestamp when the event was created. dataobjectRequired Event-specific payload. For task events it mirrors task output fields from the Task Query API; for balance.low it includes balance-related fields. Notes * Task events: expect `task_id`, `type`, `status`, and `output` (when successful). * `balance.low`: configure the threshold under [Billing → Credit alert](https://developers.tripo3d.ai/en/billing) . Tripo-Webhook-Idheader · stringRequired Webhook endpoint id on Tripo. Tripo-Webhook-Deliveryheader · stringRequired Unique delivery id — use for idempotency if the same logical event is delivered more than once. Tripo-Webhook-Eventheader · stringRequired Same as body \`type\` (e.g. task.completed). Tripo-Webhook-Signatureheader · stringRequired HMAC-SHA256 over `{timestamp}.{raw_body}` using your signing secret. Format: `t=,v1=`. Notes 1. Parse `t` and `v1` from the header. 2. Compute HMAC-SHA256(secret, `t + "." + rawBody`) as lowercase hex. 3. Compare with `v1` using a constant-time compare. 4. Optional: reject if `t` is older than ~5 minutes (replay protection). Content-Typeheader · stringRequireddefault: application/json Always application/json. Response -------- HTTPstatusRequired Respond with 2xx quickly (within a few seconds). Return before heavy processing finishes. Examples -------- task.completedCopy { "id": "task_abc123:task.completed", "type": "task.completed", "created_at": "2026-05-06T12:00:00Z", "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb"} } } balance.lowCopy { "id": "evt_balance_low:balance.low", "type": "balance.low", "created_at": "2026-05-06T12:00:00Z", "data": { "balance": 1200, "threshold": 5000 } } Verify · PythonCopy import hmac import hashlib import time def verify_webhook(payload: bytes, signature_header: str, secret: str) -> bool: parts = dict(p.split("=", 1) for p in signature_header.split(",")) timestamp = parts.get("t", "") expected_sig = parts.get("v1", "") if abs(time.time() - int(timestamp)) > 300: return False computed = hmac.new( secret.encode("utf-8"), f"{timestamp}.{payload.decode('utf-8')}".encode("utf-8"), hashlib.sha256 ).hexdigest() return hmac.compare_digest(computed, expected_sig) Verify · JavaScriptCopy const crypto = require("crypto"); function verifyWebhook(payload, signatureHeader, secret) { const parts = Object.fromEntries( signatureHeader.split(",").map(p => p.split("=", 2)) ); const timestamp = parts.t; const expectedSig = parts.v1; if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) { return false; } const computed = crypto .createHmac("sha256", secret) .update(`${timestamp}.${payload}`) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(computed), Buffer.from(expectedSig) ); } Tripo-Webhook-SignatureCopy Tripo-Webhook-Signature: t=1714992000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9 task.failedCopy { "id": "task_abc123:task.failed", "type": "task.failed", "created_at": "2026-05-06T12:00:05Z", "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "failed", "error": { "code": "task_failed", "message": "Generation failed"} } } PreviousRate LimitsNextv2 to v3 Migration --- # Account — Tripo Developers Account Management ================== CopyDownload PDF \# Account Management \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`GET /account/balance\` Query account balance and usage details. Balance returns available and frozen credits; Usage returns per-task consumption history. ## Response Fields ### balance - \*\*Type:\*\* number - \*\*Required:\*\* Required Available credit balance. Decimal number with up to two decimal places (e.g. 41465.00). ### frozen - \*\*Type:\*\* number - \*\*Required:\*\* Required Frozen credits reserved for in-progress tasks. Decimal number with up to two decimal places (e.g. 0.00). ## Request Example ### Balance \`\`\` curl -s \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ https://openapi.tripo3d.ai/v3/account/balance \`\`\` ### Usage \`\`\` curl -s \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ https://openapi.tripo3d.ai/v3/account/usage \`\`\` ## Response Example ### Balance \`\`\`json { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } \`\`\` ### Usage \`\`\`json { "code": 0, "data": \[ { "task\_id": "task\_abc123", "type": "text\_to\_model", "credits\_consumed": 100.00, "created\_at": "2025-01-01T00:00:00Z" } \] } \`\`\` Response -------- balancenumberRequired Available credit balance. Decimal number with up to two decimal places (e.g. 41465.00). frozennumberRequired Frozen credits reserved for in-progress tasks. Decimal number with up to two decimal places (e.g. 0.00). Examples -------- BalanceCopy curl -s \ -H "Authorization: Bearer YOUR_API_KEY" \ https://openapi.tripo3d.ai/v3/account/balance UsageCopy curl -s \ -H "Authorization: Bearer YOUR_API_KEY" \ https://openapi.tripo3d.ai/v3/account/usage BalanceCopy { "code": 0, "data": { "balance": 10000.00, "frozen": 200.00 } } UsageCopy { "code": 0, "data": [\ {\ "task_id": "task_abc123",\ "type": "text_to_model",\ "credits_consumed": 100.00,\ "created_at": "2025-01-01T00:00:00Z"}\ ] } PreviousFile Upload (Large Files)NextError Handling --- # Task Query — Tripo Developers Task Query ========== CopyDownload PDF \# Task Query \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`GET /tasks/{task\_id}\` Query the status and output of a single async task by its task ID. All generation and processing endpoints return a task\_id that can be used here. ## Request Parameters ### task\_id - \*\*Type:\*\* string - \*\*Required:\*\* Required The unique task identifier, passed as a path parameter. Starts with task\_. ## Response Fields ### task\_id - \*\*Type:\*\* string - \*\*Required:\*\* Required Unique task identifier. ### type - \*\*Type:\*\* string - \*\*Required:\*\* Required Task type (e.g., text\_to\_model, rig, convert). ### status - \*\*Type:\*\* string - \*\*Required:\*\* Required Task status. - \`queued\` — waiting in queue. - \`running\` — processing in progress. - \`success\` — completed successfully. - \`failed\` — failed with error. - \`cancelled\` — cancelled by user. ### progress - \*\*Type:\*\* integer - \*\*Required:\*\* Required 0–100. ### error\_code - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Present when status=failed. Standardized error code indicating the failure reason. ### error\_message - \*\*Type:\*\* string - \*\*Required:\*\* Optional Present when status=failed and error\_code is available. Human-readable description of the error. ### output - \*\*Type:\*\* object - \*\*Required:\*\* Optional Only populated when \`status=success\`. Contains \`model\_url\`, \`rendered\_image\_url\`, etc. ### credits\_consumed - \*\*Type:\*\* number - \*\*Required:\*\* Optional Credits consumed. Decimal number with up to two decimal places (e.g. 48.00). ### created\_at - \*\*Type:\*\* string - \*\*Required:\*\* Required ISO 8601 creation time. ### completed\_at - \*\*Type:\*\* string - \*\*Required:\*\* Optional ISO 8601 completion time. ## Request Example ### Query task \`\`\` curl -s \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ https://openapi.tripo3d.ai/v3/tasks/task\_abc123 \`\`\` ## Response Example ### Task detail \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body task\_idstringRequired The unique task identifier, passed as a path parameter. Starts with task\_. Response -------- task\_idstringRequired Unique task identifier. typestringRequired Task type (e.g., text\_to\_model, rig, convert). statusstringRequired Task status. * `queued` — waiting in queue. * `running` — processing in progress. * `success` — completed successfully. * `failed` — failed with error. * `cancelled` — cancelled by user. progressintegerRequired 0–100. error\_codeinteger Present when status=failed. Standardized error code indicating the failure reason. error\_messagestring Present when status=failed and error\_code is available. Human-readable description of the error. outputobject Only populated when `status=success`. Contains `model_url`, `rendered_image_url`, etc. credits\_consumednumber Credits consumed. Decimal number with up to two decimal places (e.g. 48.00). created\_atstringRequired ISO 8601 creation time. completed\_atstring ISO 8601 completion time. Examples -------- Query taskCopy curl -s \ -H "Authorization: Bearer YOUR_API_KEY" \ https://openapi.tripo3d.ai/v3/tasks/task_abc123 Task detailCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } PreviousAnimation RetargetNextBatch Task Query --- # File Upload — Tripo Developers File Management =============== CopyDownload PDF \# File Management \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /files\` Upload a file and get a file\_token for subsequent API calls. ## Request Parameters ### file - \*\*Type:\*\* binary - \*\*Required:\*\* Required File data. Use \`multipart/form-data\` encoding. - Images: \`JPEG\`, \`PNG\`. Max \*\*20 MB\*\*. - Models: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\`. Max \*\*150 MB\*\*. - For files larger than 60 MB, consider using File Upload (Large Files) for better performance. ## Response Fields ### file\_token - \*\*Type:\*\* string - \*\*Required:\*\* Required File reference token (e.g., \`file\_abc123\`). Use in the \`input\` field of other API calls. ## Request Example ### Upload \`\`\` curl -s \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ -F "file=@product-photo.png" \\ https://openapi.tripo3d.ai/v3/files \`\`\` ## Response Example ### Upload \`\`\`json { "code": 0, "data": { "file\_token": "file\_abc123" } } \`\`\` Request Parameters ------------------ ### Request Body filebinaryRequired File data. Use `multipart/form-data` encoding. Notes * Images: `JPEG`, `PNG`. Max **20 MB**. * Models: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL`. Max **150 MB**. * For files larger than 60 MB, consider using [File Upload (Large Files)](https://developers.tripo3d.ai/en/docs/files-presign) for better performance. Response -------- file\_tokenstringRequired File reference token (e.g., `file_abc123`). Use in the `input` field of other API calls. Examples -------- UploadCopy curl -s \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@product-photo.png" \ https://openapi.tripo3d.ai/v3/files UploadCopy { "code": 0, "data": { "file_token": "file_abc123"} } PreviousBatch Task QueryNextFile Upload (Large Files) --- # Import Model — Tripo Developers Import Model ============ CopyDownload PDF \# Import Model \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /models/import\` Import an external 3D model file into the Tripo platform for downstream processing. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Model file source. Accepts \`file\_token\` (prefix \`file\_\`) or a URL. - Formats: \`GLB\`, \`GLTF\`, \`FBX\`, \`OBJ\`, \`STL\` - Max file size: \*\*150 MB\*\* ## Request Example ### From file \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/import \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "file\_abc123" }' \`\`\` ### From URL \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/models/import \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/my-model.glb" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Model file source. Accepts `file_token` (prefix `file_`) or a URL. Notes * Formats: `GLB`, `GLTF`, `FBX`, `OBJ`, `STL` * Max file size: **150 MB** Examples -------- From fileCopy { "input": "file_abc123"} From URLCopy { "input": "https://example.com/my-model.glb"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } Previousv2 to v3 Migration --- # v2 to v3 Migration — Tripo Developers v2 to v3 Migration Guide ======================== CopyDownload PDF \# v2 to v3 Migration Guide This document helps you migrate existing code from Tripo API v2 to v3. ## Move from V2 to V3 with the Skill You do not need to understand every API difference first. Download this Skill, place it in the project directory you want to migrate, and ask your AI coding tool to use it. It will help find V2 calls in your project and migrate them to V3 step by step. ### Step 1: Download the Skill Download You will get a file named \`SKILL.md\`. Keep the filename unchanged. ### Step 2: Place the Skill in your project and use it Place the downloaded \`SKILL.md\` in the project directory you want to migrate. Then open the project and tell your AI to use this Skill. ### Step 3: Copy this prompt to start Open the project you want to migrate. Copy the full prompt below and send it to your AI coding tool: \`\`\`text Use the \`SKILL.md\` file in this project directory to move this project's Tripo API integration from V2 to V3. First show me what needs to change. Wait for my confirmation, then make the changes. Finally, use the checklist in the file to make sure nothing was missed. \`\`\` The tool will first find the V2 calls and show you a plan, so you do not need to search every file yourself. ## Major Changes ### 1. Base URL Change \`\`\` # v2 https://api.tripo3d.ai/v2/openapi/ # v3 https://openapi.tripo3d.ai/v3/ \`\`\` ### 2. Universal Endpoint Split into Dedicated Endpoints v2 uses a single \`POST /v2/openapi/task\` endpoint and a \`type\` field to distinguish task types. v3 provides a dedicated endpoint for each capability, so the \`type\` field is no longer required. \`\`\`json // v2 POST /v2/openapi/task { "type": "text\_to\_model", "prompt": "a cat" } // v3 POST /v3/generation/text-to-model { "prompt": "a cat" } \`\`\` ### 3. File Inputs Unified as the \`input\` Field In v2, different field names are used depending on the input source, such as \`file\`, \`file\_token\`, \`url\`, and \`object\`. In v3, they are unified under the \`input\` field, and the system automatically infers the input type. \`\`\`json // v2 - different field names are required { "type": "refine\_model", "draft\_model\_task\_id": "task\_abc123" } { "type": "convert\_model", "original\_model\_task\_id": "task\_abc123" } // v3 - use input consistently { "input": "task\_abc123" } { "input": "https://example.com/model.glb" } { "input": "file\_token\_abc123" } \`\`\` ### 4. Standardized Field Names | v2 Field | v3 Field | | :-: | :-: | | \`create\_time\` | \`created\_at\` | | \`consumed\_credit\` | \`credits\_consumed\` | ### 5. Text-to-Image and Image-to-Image Split In v2, text-to-image and image-to-image share the same API. In v3, they are split into dedicated endpoints: - \`POST /v3/generation/text-to-image\` - Generate an image from text-only input - \`POST /v3/generation/image-to-image\` - Generate or edit an image based on a reference image ## Endpoint Mapping ### Generation | v2 type Value | v3 Endpoint | | :-: | :-: | | \`text\_to\_model\` | \`POST /v3/generation/text-to-model\` | | \`image\_to\_model\` | \`POST /v3/generation/image-to-model\` | | \`multiview\_to\_model\` | \`POST /v3/generation/multiview-to-model\` | | \`text\_to\_image\` | \`POST /v3/generation/text-to-image\` | | \`generate\_image\` | \`POST /v3/generation/image-to-image\` | | \`generate\_multiview\_image\` | \`POST /v3/generation/image-to-multiview\` | | \`edit\_multiview\_image\` | \`POST /v3/generation/edit-multiview\` | ### Model Processing | v2 type Value | v3 Endpoint | | :-: | :-: | | \`refine\_model\` | \`POST /v3/models/refine\` | | \`convert\_model\` | \`POST /v3/models/convert\` | | \`import\_model\` | \`POST /v3/models/import\` | | \`stylize\_model\` | \`POST /v3/models/stylize\` | | \`texture\_model\` | \`POST /v3/models/texture\` | ### Animation | v2 type Value | v3 Endpoint | | :-: | :-: | | \`animate\_prerigcheck\` | \`POST /v3/animations/rig-check\` | | \`animate\_rig\` | \`POST /v3/animations/rig\` | | \`animate\_retarget\` | \`POST /v3/animations/retarget\` | ### Mesh Editing | v2 type Value | v3 Endpoint | | :-: | :-: | | \`mesh\_segmentation\` | \`POST /v3/mesh/segment\` | | \`mesh\_completion\` | \`POST /v3/mesh/complete\` | | \`highpoly\_to\_lowpoly\` | \`POST /v3/mesh/decimate\` | ### Tasks and Files | v2 Endpoint | v3 Endpoint | | :-: | :-: | | \`GET /v2/openapi/task/{task\_id}\` | \`GET /v3/tasks/{task\_id}\` | | \`POST /v2/openapi/upload\` | \`POST /v3/files\` | ## Migration Steps ### Step 1: Update the Base URL \`\`\`python # v2 BASE\_URL = "https://api.tripo3d.ai/v2/openapi" # v3 BASE\_URL = "https://openapi.tripo3d.ai/v3" \`\`\` ### Step 2: Replace Endpoints Using the Mapping Table \`\`\`python # v2 response = requests.post(f"{BASE\_URL}/task", json={ "type": "text\_to\_model", "prompt": "a cat" }) # v3 response = requests.post(f"{BASE\_URL}/generation/text-to-model", json={ "prompt": "a cat" }) \`\`\` ### Step 3: Remove the \`type\` Field In v3, the endpoint path already implies the task type, so the request body no longer needs the \`type\` field. ### Step 4: Replace Input Fields with \`input\` \`\`\`python # v2 - different task types use different field names payload = {"type": "refine\_model", "draft\_model\_task\_id": "task\_abc123"} payload = {"type": "convert\_model", "original\_model\_task\_id": "task\_abc123"} # v3 - use input consistently payload = {"input": "task\_abc123"} \`\`\` ### Step 5: Update Response Field Names \`\`\`python # v2 created = task\["create\_time"\] cost = task\["consumed\_credit"\] # v3 created = task\["created\_at"\] cost = task\["credits\_consumed"\] \`\`\` ### Step 6: Test and Validate 1. Replace and test each endpoint one at a time 2. Verify that task creation and polling work correctly 3. Confirm that download links are available 4. Check that credit deduction and balance queries work correctly ## Notes - v2 and v3 can run in parallel. We recommend migrating gradually instead of switching all at once - API Keys are shared between v2 and v3. You do not need to create new keys - The task ID format remains unchanged. Tasks created in v2 can be queried in v3 v2 to v3 Migration Guide ======================== This document helps you migrate existing code from Tripo API v2 to v3. Move from V2 to V3 with the Skill --------------------------------- You do not need to understand every API difference first. Download this Skill, place it in the project directory you want to migrate, and ask your AI coding tool to use it. It will help find V2 calls in your project and migrate them to V3 step by step. ### Step 1: Download the Skill [Download](https://developers.tripo3d.ai/assets/developer/tripo-v2-to-v3-migration/SKILL.md) You will get a file named `SKILL.md`. Keep the filename unchanged. ### Step 2: Place the Skill in your project and use it Place the downloaded `SKILL.md` in the project directory you want to migrate. Then open the project and tell your AI to use this Skill. ### Step 3: Copy this prompt to start Open the project you want to migrate. Copy the full prompt below and send it to your AI coding tool: Copy Use the `SKILL.md` file in this project directory to move this project's Tripo API integration from V2 to V3. First show me what needs to change. Wait for my confirmation, then make the changes. Finally, use the checklist in the file to make sure nothing was missed. The tool will first find the V2 calls and show you a plan, so you do not need to search every file yourself. Major Changes ------------- ### 1\. Base URL Change Copy # v2 https://api.tripo3d.ai/v2/openapi/ # v3 https://openapi.tripo3d.ai/v3/ ### 2\. Universal Endpoint Split into Dedicated Endpoints v2 uses a single `POST /v2/openapi/task` endpoint and a `type` field to distinguish task types. v3 provides a dedicated endpoint for each capability, so the `type` field is no longer required. JSONCopy // v2 POST /v2/openapi/task { "type": "text_to_model", "prompt": "a cat" } // v3 POST /v3/generation/text-to-model { "prompt": "a cat" } ### 3\. File Inputs Unified as the `input` Field In v2, different field names are used depending on the input source, such as `file`, `file_token`, `url`, and `object`. In v3, they are unified under the `input` field, and the system automatically infers the input type. JSONCopy // v2 - different field names are required { "type": "refine_model", "draft_model_task_id": "task_abc123" } { "type": "convert_model", "original_model_task_id": "task_abc123" } // v3 - use input consistently { "input": "task_abc123" } { "input": "https://example.com/model.glb" } { "input": "file_token_abc123" } ### 4\. Standardized Field Names | v2 Field | v3 Field | | --- | --- | | `create_time` | `created_at` | | `consumed_credit` | `credits_consumed` | ### 5\. Text-to-Image and Image-to-Image Split In v2, text-to-image and image-to-image share the same API. In v3, they are split into dedicated endpoints: * `POST /v3/generation/text-to-image` - Generate an image from text-only input * `POST /v3/generation/image-to-image` - Generate or edit an image based on a reference image Endpoint Mapping ---------------- ### Generation | v2 type Value | v3 Endpoint | | --- | --- | | `text_to_model` | `POST /v3/generation/text-to-model` | | `image_to_model` | `POST /v3/generation/image-to-model` | | `multiview_to_model` | `POST /v3/generation/multiview-to-model` | | `text_to_image` | `POST /v3/generation/text-to-image` | | `generate_image` | `POST /v3/generation/image-to-image` | | `generate_multiview_image` | `POST /v3/generation/image-to-multiview` | | `edit_multiview_image` | `POST /v3/generation/edit-multiview` | ### Model Processing | v2 type Value | v3 Endpoint | | --- | --- | | `refine_model` | `POST /v3/models/refine` | | `convert_model` | `POST /v3/models/convert` | | `import_model` | `POST /v3/models/import` | | `stylize_model` | `POST /v3/models/stylize` | | `texture_model` | `POST /v3/models/texture` | ### Animation | v2 type Value | v3 Endpoint | | --- | --- | | `animate_prerigcheck` | `POST /v3/animations/rig-check` | | `animate_rig` | `POST /v3/animations/rig` | | `animate_retarget` | `POST /v3/animations/retarget` | ### Mesh Editing | v2 type Value | v3 Endpoint | | --- | --- | | `mesh_segmentation` | `POST /v3/mesh/segment` | | `mesh_completion` | `POST /v3/mesh/complete` | | `highpoly_to_lowpoly` | `POST /v3/mesh/decimate` | ### Tasks and Files | v2 Endpoint | v3 Endpoint | | --- | --- | | `GET /v2/openapi/task/{task_id}` | `GET /v3/tasks/{task_id}` | | `POST /v2/openapi/upload` | `POST /v3/files` | Migration Steps --------------- ### Step 1: Update the Base URL PythonCopy # v2 BASE_URL = "https://api.tripo3d.ai/v2/openapi" # v3 BASE_URL = "https://openapi.tripo3d.ai/v3" ### Step 2: Replace Endpoints Using the Mapping Table PythonCopy # v2 response = requests.post(f"{BASE_URL}/task", json={ "type": "text_to_model", "prompt": "a cat" }) # v3 response = requests.post(f"{BASE_URL}/generation/text-to-model", json={ "prompt": "a cat" }) ### Step 3: Remove the `type` Field In v3, the endpoint path already implies the task type, so the request body no longer needs the `type` field. ### Step 4: Replace Input Fields with `input` PythonCopy # v2 - different task types use different field names payload = {"type": "refine_model", "draft_model_task_id": "task_abc123"} payload = {"type": "convert_model", "original_model_task_id": "task_abc123"} # v3 - use input consistently payload = {"input": "task_abc123"} ### Step 5: Update Response Field Names PythonCopy # v2 created = task["create_time"] cost = task["consumed_credit"] # v3 created = task["created_at"] cost = task["credits_consumed"] ### Step 6: Test and Validate 1. Replace and test each endpoint one at a time 2. Verify that task creation and polling work correctly 3. Confirm that download links are available 4. Check that credit deduction and balance queries work correctly Notes ----- * v2 and v3 can run in parallel. We recommend migrating gradually instead of switching all at once * API Keys are shared between v2 and v3. You do not need to create new keys * The task ID format remains unchanged. Tasks created in v2 can be queried in v3 PreviousWebhooksNextImport Model On this page --- # File Upload (Large Files) — Tripo Developers File Upload (Large Files) ========================= CopyDownload PDF \# File Upload (Large Files) \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /files/presign\` Get a presigned upload URL for direct file upload to storage — \*\*faster performance\*\* for large files. No SDK required — use a standard HTTP PUT request. Recommended for files exceeding 60 MB; for smaller files you can also use File Upload (multipart, max 150 MB).Upload flow - Call \`POST /v3/files/presign\` with \`format\` to obtain \`presigned\_url\` and \`file\_token\`. - Upload the file with \*\*HTTP PUT\*\* to \`presigned\_url\` (direct to storage, no auth needed). - Use \`file\_token\` in the \`input\` field of subsequent API calls (e.g. Import Model, Retopology, Convert Model). ## Request Parameters ### format - \*\*Type:\*\* string - \*\*Required:\*\* Required File extension without leading dot (e.g. glb, fbx, png). - Images: \`jpeg\`, \`jpg\`, \`png\`, \`webp\`, \`bmp\`, \`tiff\`. - Models: \`glb\`, \`gltf\`, \`fbx\`, \`obj\`, \`stl\`, \`3mf\`, \`usdz\`. ## Response Fields ### presigned\_url - \*\*Type:\*\* string - \*\*Required:\*\* Required Presigned PUT URL valid for 30 minutes. Upload the file with HTTP PUT to this URL. ### file\_token - \*\*Type:\*\* string - \*\*Required:\*\* Required File reference token (e.g., \`file\_abc123\`). Use in the \`input\` field after upload completes. ### expires\_in - \*\*Type:\*\* integer - \*\*Required:\*\* Required Presigned URL validity in seconds. Fixed at 1800 (30 minutes). ## Request Example ### curl \`\`\` # Step 1: Get presigned URL curl -s -X POST \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ -H "Content-Type: application/json" \\ -d '{"format":"glb"}' \\ https://openapi.tripo3d.ai/v3/files/presign # Step 2: Upload file directly to storage (no Auth needed) curl -X PUT \\ -H "Content-Type: application/octet-stream" \\ -T model.glb \\ "" # Step 3: Create task using file\_token curl -s -X POST \\ -H "Authorization: Bearer YOUR\_API\_KEY" \\ -H "Content-Type: application/json" \\ -d '{"model":"default","input":""}' \\ https://openapi.tripo3d.ai/v3/models/import \`\`\` ### Python \`\`\` import requests API\_KEY = "YOUR\_API\_KEY" BASE = "https://openapi.tripo3d.ai" headers = {"Authorization": f"Bearer {API\_KEY}"} # 1. Get presigned URL resp = requests.post(f"{BASE}/v3/files/presign", json={"format": "glb"}, headers=headers) data = resp.json()\["data"\] presigned\_url = data\["presigned\_url"\] file\_token = data\["file\_token"\] # 2. Upload file directly to storage with open("model.glb", "rb") as f: put\_resp = requests.put(presigned\_url, data=f, headers={"Content-Type": "application/octet-stream"}) assert put\_resp.status\_code == 200 # 3. Create task with file\_token task\_resp = requests.post(f"{BASE}/v3/models/import", json={"model": "default", "input": file\_token}, headers=headers) print(task\_resp.json()) \`\`\` ### JavaScript \`\`\` import fs from 'fs'; const API\_KEY = 'YOUR\_API\_KEY'; const BASE = 'https://openapi.tripo3d.ai'; // 1. Get presigned URL const presignRes = await fetch(\`${BASE}/v3/files/presign\`, { method: 'POST', headers: { 'Authorization': \`Bearer ${API\_KEY}\`, 'Content-Type': 'application/json' }, body: JSON.stringify({ format: 'glb' }), }); const { data } = await presignRes.json(); const { presigned\_url, file\_token } = data; // 2. Upload file directly to storage const fileBuffer = fs.readFileSync('model.glb'); await fetch(presigned\_url, { method: 'PUT', headers: { 'Content-Type': 'application/octet-stream' }, body: fileBuffer, }); // 3. Create task with file\_token const taskRes = await fetch(\`${BASE}/v3/models/import\`, { method: 'POST', headers: { 'Authorization': \`Bearer ${API\_KEY}\`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'default', input: file\_token }), }); console.log(await taskRes.json()); \`\`\` ## Response Example ### Presign response \`\`\`json { "code": 0, "data": { "presigned\_url": "https://storage.example.com/bucket/path/input.glb?X-Amz-Signature=...", "file\_token": "file\_abc123", "expires\_in": 1800 } } \`\`\` Request Parameters ------------------ ### Request Body formatstringRequired File extension without leading dot (e.g. glb, fbx, png). Notes * Images: `jpeg`, `jpg`, `png`, `webp`, `bmp`, `tiff`. * Models: `glb`, `gltf`, `fbx`, `obj`, `stl`, `3mf`, `usdz`. Response -------- presigned\_urlstringRequired Presigned PUT URL valid for 30 minutes. Upload the file with HTTP PUT to this URL. file\_tokenstringRequired File reference token (e.g., `file_abc123`). Use in the `input` field after upload completes. expires\_inintegerRequired Presigned URL validity in seconds. Fixed at 1800 (30 minutes). Examples -------- curlCopy # Step 1: Get presigned URL curl -s -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"format":"glb"}' \ https://openapi.tripo3d.ai/v3/files/presign # Step 2: Upload file directly to storage (no Auth needed) curl -X PUT \ -H "Content-Type: application/octet-stream" \ -T model.glb \ "" # Step 3: Create task using file_token curl -s -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"default","input":""}' \ https://openapi.tripo3d.ai/v3/models/import PythonCopy import requests API_KEY = "YOUR_API_KEY" BASE = "https://openapi.tripo3d.ai" headers = {"Authorization": f"Bearer {API_KEY}"} # 1. Get presigned URL resp = requests.post(f"{BASE}/v3/files/presign", json={"format": "glb"}, headers=headers) data = resp.json()["data"] presigned_url = data["presigned_url"] file_token = data["file_token"] # 2. Upload file directly to storage with open("model.glb", "rb") as f: put_resp = requests.put(presigned_url, data=f, headers={"Content-Type": "application/octet-stream"}) assert put_resp.status_code == 200 # 3. Create task with file_token task_resp = requests.post(f"{BASE}/v3/models/import", json={"model": "default", "input": file_token}, headers=headers) print(task_resp.json()) JavaScriptCopy import fs from 'fs'; const API_KEY = 'YOUR_API_KEY'; const BASE = 'https://openapi.tripo3d.ai'; // 1. Get presigned URL const presignRes = await fetch(`${BASE}/v3/files/presign`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ format: 'glb' }), }); const { data } = await presignRes.json(); const { presigned_url, file_token } = data; // 2. Upload file directly to storage const fileBuffer = fs.readFileSync('model.glb'); await fetch(presigned_url, { method: 'PUT', headers: { 'Content-Type': 'application/octet-stream' }, body: fileBuffer, }); // 3. Create task with file_token const taskRes = await fetch(`${BASE}/v3/models/import`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'default', input: file_token }), }); console.log(await taskRes.json()); Presign responseCopy { "code": 0, "data": { "presigned_url": "https://storage.example.com/bucket/path/input.glb?X-Amz-Signature=...", "file_token": "file_abc123", "expires_in": 1800 } } PreviousFile UploadNextAccount --- # Tripo Developers — AI 3D Generation API OpenAI-Compatible Images API ============================ CopyDownload PDF \# OpenAI-Compatible Images API \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /openai/images/generations\` \*\*Fully compatible with the OpenAI Images API protocol.\*\* Point your existing client at \`https://openapi.tripo3d.ai/v3/openai\`, change the model name, and keep the rest of your integration unchanged.Endpoints - \`POST /v3/openai/images/generations\` — text to image - \`POST /v3/openai/images/edits\` — image to image (multipart or JSON) Two deliberate differences from OpenAI - \*\*The image is always returned as a signed URL\*\* in \`data\[0\].url\`, never as \`b64\_json\`. Passing \`response\_format="b64\_json"\` returns 400 rather than being silently ignored. - \*\*No \`usage\` block.\*\* Billing is in credits, not tokens. Use Account or Task Query for spend. Model namesModel ids use OpenAI's own spelling, so the string already in your code keeps working. These three are the only versions that exist — anything else, dated snapshot ids included, returns 404 \`model\_not\_found\` listing the three supported ids. - \`gpt-image-2\` - \`gpt-image-2.5-flare\` - \`gpt-image-2.5-sunburst\` Billing and timingIdentical to Text to Image and Image to Image — same credits, same content moderation, same concurrency limits. The request blocks until the image is ready (typically 20–80s). If it is still running after 240s you get a 400 with code \`generation\_in\_progress\`: the task has not failed and was charged once, so poll \`GET /v3/tasks/{task\_id}\` (the id is in \`X-Tripo-Task-Id\` and in \`tripo.task\_id\`) instead of resubmitting. ## Request Parameters ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required Model id, in OpenAI's spelling. Anything outside the three listed versions is rejected with 404 model\_not\_found. One of: gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst — these three only. Dated snapshot ids are not accepted, nor are the Tripo chat\_image\_\* ids. ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Required Text description of the desired image. ### image - \*\*Type:\*\* file | file\[\] - \*\*Required:\*\* Conditional Edits only, multipart form. Both 'image' and 'image\[\]' part names are accepted; send one part per input image. ### images - \*\*Type:\*\* object\[\] - \*\*Required:\*\* Conditional Edits only, JSON body. Each entry sets exactly one of image\_url (public https URL, or base64 data: URL up to 10 MiB) or file\_id (a Tripo file\_token from POST /v3/files). ### size - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`1024x1024\` Output resolution. 'auto' and an omitted value both resolve to 1024x1024 so the credit cost is known before the request runs. Same rules as the native endpoints: each edge must be a multiple of 16px. ### quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`low\` Rendering tier. 'auto' and an omitted value both mean the base tier. gpt-image-2: low, medium, high. gpt-image-2.5-\*: additionally xhigh and max. ### background - \*\*Type:\*\* string - \*\*Required:\*\* Optional auto, opaque or transparent. Only effective on gpt-image-2.5-\*; transparent requires output\_format=png. ### output\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`png\` png or jpeg. webp is rejected. ### n - \*\*Type:\*\* integer - \*\*Required:\*\* Optional - \*\*Default:\*\* \`1\` Must be 1 — one image per request. Any other value returns 400. ### response\_format - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`url\` Only 'url' is supported. 'b64\_json' returns 400 rather than being silently downgraded. ### stream - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional Not supported; must be false or omitted. Partial images are not available. ### mask - \*\*Type:\*\* file - \*\*Required:\*\* Optional Optional inpainting mask, applied to the first input image. Must be a PNG with an alpha channel, sent as a file part; its fully transparent pixels mark the region to redraw. Anything else returns 400. Same dimensions as the input image, and at most 20 MiB. The mask guides the model semantically rather than clipping pixels, so word the prompt to describe the region rather than an object that sits outside it. The input image itself is capped at 10 MiB, whether it is uploaded or sent as a data: URL. ## Response Fields ### created - \*\*Type:\*\* integer - \*\*Required:\*\* Required Unix timestamp in seconds. ### data\[\].url - \*\*Type:\*\* string - \*\*Required:\*\* Required Signed CDN URL of the generated image. This replaces b64\_json. ### size / quality / output\_format / background - \*\*Type:\*\* string - \*\*Required:\*\* Optional Echo of what was actually applied — useful to confirm how 'auto' was resolved. ### tripo.task\_id - \*\*Type:\*\* string - \*\*Required:\*\* Required Tripo extension. The same id is returned in the X-Tripo-Task-Id response header, including on errors, so a task can always be reconciled with GET /v3/tasks/{task\_id}. ## Request Example ### Text to image (official SDK) \`\`\` from openai import OpenAI client = OpenAI( api\_key="", base\_url="https://openapi.tripo3d.ai/v3/openai", ) result = client.images.generate( model="gpt-image-2.5-flare", prompt="a cute baby sea otter on a rock", n=1, size="auto", quality="auto", ) print(result.data\[0\].url) \`\`\` ### Image to image (official SDK) \`\`\` result = client.images.edit( model="gpt-image-2.5-flare", prompt="replace the background with pure white", image=open("input.png", "rb"), size="1024x1024", ) print(result.data\[0\].url) \`\`\` ### Image to image (JSON body) \`\`\` curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \\ -H 'Authorization: Bearer ' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "gpt-image-2.5-flare", "prompt": "replace the background with pure white", "images": \[{ "image\_url": "https://example.com/input.png" }\], "size": "1024x1024" }' \`\`\` ### Image to image (multipart, two images) \`\`\` curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \\ -H 'Authorization: Bearer ' \\ -F 'model=gpt-image-2.5-flare' \\ -F 'prompt=combine both objects into one product photo' \\ -F 'image\[\]=@a.png;type=image/png' \\ -F 'image\[\]=@b.png;type=image/png' \\ -F 'size=1024x1024' \`\`\` ## Response Example ### Success \`\`\`json { "created": 1789598400, "data": \[ { "url": "https://cdn.tripo3d.com/.../generated\_image.png?..." } \], "size": "1024x1024", "quality": "low", "output\_format": "png", "tripo": { "task\_id": "2f67cafc-c1aa-492f-85e8-93ec95fc6fd8" } } \`\`\` ### Error envelope \`\`\`json { "error": { "message": "model 'chat\_image\_2' is not supported here; use 'gpt-image-2' instead", "type": "invalid\_request\_error", "param": "model", "code": "model\_not\_found" } } \`\`\` ### Still generating after the wait limit \`\`\`json { "error": { "message": "the image is still being generated after 240s; it has not failed and you have been charged once — poll GET /v3/tasks/2f67cafc-... for the result instead of resubmitting", "type": "invalid\_request\_error", "code": "generation\_in\_progress" } } \`\`\` Request Parameters ------------------ ### Request Body modelstringRequired Model id, in OpenAI's spelling. Anything outside the three listed versions is rejected with 404 model\_not\_found. Notes One of: gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst — these three only. Dated snapshot ids are not accepted, nor are the Tripo chat\_image\_\* ids. promptstringRequired Text description of the desired image. imagefile | file\[\]Conditional Edits only, multipart form. Both 'image' and 'image\[\]' part names are accepted; send one part per input image. imagesobject\[\]Conditional Edits only, JSON body. Each entry sets exactly one of image\_url (public https URL, or base64 data: URL up to 10 MiB) or file\_id (a Tripo file\_token from POST /v3/files). sizestringdefault: 1024x1024 Output resolution. 'auto' and an omitted value both resolve to 1024x1024 so the credit cost is known before the request runs. Notes Same rules as the native endpoints: each edge must be a multiple of 16px. qualitystringdefault: low Rendering tier. 'auto' and an omitted value both mean the base tier. Notes gpt-image-2: low, medium, high. gpt-image-2.5-\*: additionally xhigh and max. backgroundstring auto, opaque or transparent. Only effective on gpt-image-2.5-\*; transparent requires output\_format=png. output\_formatstringdefault: png png or jpeg. webp is rejected. nintegerdefault: 1 Must be 1 — one image per request. Any other value returns 400. response\_formatstringdefault: url Only 'url' is supported. 'b64\_json' returns 400 rather than being silently downgraded. streamboolean Not supported; must be false or omitted. Partial images are not available. maskfile Optional inpainting mask, applied to the first input image. Must be a PNG with an alpha channel, sent as a file part; its fully transparent pixels mark the region to redraw. Anything else returns 400. Notes Same dimensions as the input image, and at most 20 MiB. The mask guides the model semantically rather than clipping pixels, so word the prompt to describe the region rather than an object that sits outside it. The input image itself is capped at 10 MiB, whether it is uploaded or sent as a data: URL. Response -------- createdintegerRequired Unix timestamp in seconds. data\[\].urlstringRequired Signed CDN URL of the generated image. This replaces b64\_json. size / quality / output\_format / backgroundstring Echo of what was actually applied — useful to confirm how 'auto' was resolved. tripo.task\_idstringRequired Tripo extension. The same id is returned in the X-Tripo-Task-Id response header, including on errors, so a task can always be reconciled with GET /v3/tasks/{task\_id}. Examples -------- Text to image (official SDK)Copy from openai import OpenAI client = OpenAI( api_key="", base_url="https://openapi.tripo3d.ai/v3/openai", ) result = client.images.generate( model="gpt-image-2.5-flare", prompt="a cute baby sea otter on a rock", n=1, size="auto", quality="auto", ) print(result.data[0].url) Image to image (official SDK)Copy result = client.images.edit( model="gpt-image-2.5-flare", prompt="replace the background with pure white", image=open("input.png", "rb"), size="1024x1024", ) print(result.data[0].url) Image to image (JSON body)Copy curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "replace the background with pure white", "images": [{ "image_url": "https://example.com/input.png" }], "size": "1024x1024" }' Image to image (multipart, two images)Copy curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \ -H 'Authorization: Bearer ' \ -F 'model=gpt-image-2.5-flare' \ -F 'prompt=combine both objects into one product photo' \ -F 'image[]=@a.png;type=image/png' \ -F 'image[]=@b.png;type=image/png' \ -F 'size=1024x1024' SuccessCopy { "created": 1789598400, "data": [\ {\ "url": "https://cdn.tripo3d.com/.../generated_image.png?..."}\ ], "size": "1024x1024", "quality": "low", "output_format": "png", "tripo": { "task_id": "2f67cafc-c1aa-492f-85e8-93ec95fc6fd8"} } Error envelopeCopy { "error": { "message": "model 'chat_image_2' is not supported here; use 'gpt-image-2' instead", "type": "invalid_request_error", "param": "model", "code": "model_not_found"} } Still generating after the wait limitCopy { "error": { "message": "the image is still being generated after 240s; it has not failed and you have been charged once — poll GET /v3/tasks/2f67cafc-... for the result instead of resubmitting", "type": "invalid_request_error", "code": "generation_in_progress"} } NextIntroduction --- # Documentation — Tripo Developers Introduction to the Tripo API ============================= CopyDownload PDF \# Introduction to the Tripo API Tripo3D is an AI-powered 3D generation platform that provides text-to-3D, image-to-3D, rigging, mesh editing, and other capabilities. With the Tripo API, developers can integrate high-quality 3D content generation into their own products. > If you are accessing from China, please visit the China site: \[developers.tripo3d.com\](https://developers.tripo3d.com) ## Base URL \`\`\`baseurl https://openapi.tripo3d.ai/v3 \`\`\` ## Authentication All API requests must include an API Key in the request header: \`\`\`apikey Authorization: Bearer {api\_key} \`\`\` You can create and manage API Keys in the \[Tripo Console\](/en/keys). ## Unified Response Format ### Success Response \`\`\`json { "code": 0, "data": { ... } } \`\`\` ### Error Response \`\`\`json { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account" } \`\`\` ### Common Fields | Parameter | Type | Description | | :-: | :-: | :-: | | code | integer | Status code. \`0\` indicates success, and any non-\`0\` value indicates an error | | data | object | Business data, returned only on success | | message | string | Error description, returned only on failure | | suggestion | string | Suggested fix, returned only on failure | ## Asynchronous Task Pattern Most generation APIs use an asynchronous task pattern: 1. \*\*Create a task\*\* - Send a POST request to create a task and receive a \`task\_id\` 2. \*\*Poll for results\*\* - Use \`GET /v3/tasks/{task\_id}\` to query the task status and result \`\`\` POST /v3/generation/text-to-model -> {"code": 0, "data": {"task\_id": "task\_abc123"}} | v GET /v3/tasks/task\_abc123 -> {"code": 0, "data": {"status": "running", "progress": 50}} | v GET /v3/tasks/task\_abc123 -> {"code": 0, "data": {"status": "success", "output": {...}}} \`\`\` ### Task Statuses | Status | Description | | :-: | :-: | | \`queued\` | Queued | | \`running\` | Running | | \`success\` | Succeeded | | \`failed\` | Failed | | \`cancelled\` | Cancelled | ## API Version Current version: \*\*v3\*\* ## Endpoint Overview ### 3D Model Generation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/generation/text-to-model\`\](/en/docs/generation-text-to-model) | Generate a 3D model from text | | \[\`POST /v3/generation/image-to-model\`\](/en/docs/generation-image-to-model) | Generate a 3D model from an image | | \[\`POST /v3/generation/multiview-to-model\`\](/en/docs/generation-multiview-to-model) | Generate a 3D model from multiview images | ### Image Generation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/generation/text-to-image\`\](/en/docs/generation-text-to-image) | Generate an image from text | | \[\`POST /v3/generation/image-to-image\`\](/en/docs/generation-image-to-image) | Transform an image style | | \[\`POST /v3/generation/image-to-multiview\`\](/en/docs/generation-image-to-multiview) | Generate multiview images | | \[\`POST /v3/generation/edit-multiview\`\](/en/docs/generation-edit-multiview) | Edit multiview images | ### Model Processing | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/models/texture\`\](/en/docs/models-texture) | Texture a model | | \[\`POST /v3/models/convert\`\](/en/docs/models-convert) | Convert model format | | \[\`POST /v3/mesh/segment\`\](/en/docs/mesh-segment) | Semantic segmentation | | \[\`POST /v3/mesh/complete\`\](/en/docs/mesh-complete) | Mesh completion | | \[\`POST /v3/mesh/decimate\`\](/en/docs/mesh-decimate) | Retopology | ### Animation | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/animations/rig-check\`\](/en/docs/animations-rig-check) | Check rigging compatibility | | \[\`POST /v3/animations/rig\`\](/en/docs/animations-rig) | Rig a model | | \[\`POST /v3/animations/retarget\`\](/en/docs/animations-retarget) | Retarget an animation | ### Task Management | Endpoint | Description | | :-: | :-: | | \[\`GET /v3/tasks/{task\_id}\`\](/en/docs/task-query) | Query a task | | \[\`POST /v3/tasks/list\`\](/en/docs/task-batch-query) | Query tasks in batch | ### File Management | Endpoint | Description | | :-: | :-: | | \[\`POST /v3/files\`\](/en/docs/files) | Upload a file | ### Account | Endpoint | Description | | :-: | :-: | | \[\`GET /v3/account/balance\`\](/en/docs/account) | Query account balance | Introduction to the Tripo API ============================= Tripo3D is an AI-powered 3D generation platform that provides text-to-3D, image-to-3D, rigging, mesh editing, and other capabilities. With the Tripo API, developers can integrate high-quality 3D content generation into their own products. > If you are accessing from China, please visit the China site: [developers.tripo3d.com](https://developers.tripo3d.com/) Base URL -------- `https://openapi.tripo3d.ai/v3` Authentication -------------- All API requests must include an API Key in the request header: `Authorization: Bearer {api_key}` You can create and manage API Keys in the [Tripo Console](https://developers.tripo3d.ai/en/keys) . Unified Response Format ----------------------- ### Success Response JSONCopy { "code": 0, "data": { ... } } ### Error Response JSONCopy { "code": 2010, "message": "Insufficient credits", "suggestion": "Please top up your account" } ### Common Fields | Parameter | Type | Description | | --- | --- | --- | | code | integer | Status code. `0` indicates success, and any non-`0` value indicates an error | | data | object | Business data, returned only on success | | message | string | Error description, returned only on failure | | suggestion | string | Suggested fix, returned only on failure | Asynchronous Task Pattern ------------------------- Most generation APIs use an asynchronous task pattern: 1. **Create a task** - Send a POST request to create a task and receive a `task_id` 2. **Poll for results** - Use `GET /v3/tasks/{task_id}` to query the task status and result Copy POST /v3/generation/text-to-model -> {"code": 0, "data": {"task_id": "task_abc123"}} | v GET /v3/tasks/task_abc123 -> {"code": 0, "data": {"status": "running", "progress": 50}} | v GET /v3/tasks/task_abc123 -> {"code": 0, "data": {"status": "success", "output": {...}}} ### Task Statuses | Status | Description | | --- | --- | | `queued` | Queued | | `running` | Running | | `success` | Succeeded | | `failed` | Failed | | `cancelled` | Cancelled | API Version ----------- Current version: **v3** Endpoint Overview ----------------- ### 3D Model Generation | Endpoint | Description | | --- | --- | | [`POST /v3/generation/text-to-model`](https://developers.tripo3d.ai/en/docs/generation-text-to-model) | Generate a 3D model from text | | [`POST /v3/generation/image-to-model`](https://developers.tripo3d.ai/en/docs/generation-image-to-model) | Generate a 3D model from an image | | [`POST /v3/generation/multiview-to-model`](https://developers.tripo3d.ai/en/docs/generation-multiview-to-model) | Generate a 3D model from multiview images | ### Image Generation | Endpoint | Description | | --- | --- | | [`POST /v3/generation/text-to-image`](https://developers.tripo3d.ai/en/docs/generation-text-to-image) | Generate an image from text | | [`POST /v3/generation/image-to-image`](https://developers.tripo3d.ai/en/docs/generation-image-to-image) | Transform an image style | | [`POST /v3/generation/image-to-multiview`](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) | Generate multiview images | | [`POST /v3/generation/edit-multiview`](https://developers.tripo3d.ai/en/docs/generation-edit-multiview) | Edit multiview images | ### Model Processing | Endpoint | Description | | --- | --- | | [`POST /v3/models/texture`](https://developers.tripo3d.ai/en/docs/models-texture) | Texture a model | | [`POST /v3/models/convert`](https://developers.tripo3d.ai/en/docs/models-convert) | Convert model format | | [`POST /v3/mesh/segment`](https://developers.tripo3d.ai/en/docs/mesh-segment) | Semantic segmentation | | [`POST /v3/mesh/complete`](https://developers.tripo3d.ai/en/docs/mesh-complete) | Mesh completion | | [`POST /v3/mesh/decimate`](https://developers.tripo3d.ai/en/docs/mesh-decimate) | Retopology | ### Animation | Endpoint | Description | | --- | --- | | [`POST /v3/animations/rig-check`](https://developers.tripo3d.ai/en/docs/animations-rig-check) | Check rigging compatibility | | [`POST /v3/animations/rig`](https://developers.tripo3d.ai/en/docs/animations-rig) | Rig a model | | [`POST /v3/animations/retarget`](https://developers.tripo3d.ai/en/docs/animations-retarget) | Retarget an animation | ### Task Management | Endpoint | Description | | --- | --- | | [`GET /v3/tasks/{task_id}`](https://developers.tripo3d.ai/en/docs/task-query) | Query a task | | [`POST /v3/tasks/list`](https://developers.tripo3d.ai/en/docs/task-batch-query) | Query tasks in batch | ### File Management | Endpoint | Description | | --- | --- | | [`POST /v3/files`](https://developers.tripo3d.ai/en/docs/files) | Upload a file | ### Account | Endpoint | Description | | --- | --- | | [`GET /v3/account/balance`](https://developers.tripo3d.ai/en/docs/account) | Query account balance | NextQuick Start --- # Text to 3D Model — Tripo Developers Text to 3D Model — H Series =========================== CopyDownload PDF \# Text to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/text-to-model\` Generate a 3D model from a text prompt. Produces geometry, optional textures, and optional PBR material maps. ## Request Parameters ### prompt - \*\*Type:\*\* string - \*\*Required:\*\* Required Text prompt, up to 1024 characters. Describe shape, material, style, and scale. - Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." - Bad: "A box." - Include material and style hints for better PBR results. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### negative\_prompt - \*\*Type:\*\* string - \*\*Required:\*\* Optional Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### image\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### Basic \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A cat wearing a spacesuit", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### Advanced \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/text-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "prompt": "A futuristic sci-fi helmet with glowing blue visor.", "model": "v3.1-20260211", "face\_limit": 80000, "geometry\_quality": "detailed", "auto\_size": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body promptstringRequired Text prompt, up to 1024 characters. Describe shape, material, style, and scale. Notes * Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock." * Bad: "A box." * Include material and style hints for better PBR results. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. negative\_promptstring Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh". model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. image\_seedinteger Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- BasicCopy { "prompt": "A cat wearing a spacesuit", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} AdvancedCopy { "prompt": "A futuristic sci-fi helmet with glowing blue visor.", "model": "v3.1-20260211", "face_limit": 80000, "geometry_quality": "detailed", "auto_size": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } NextIntroduction --- # Multiview to 3D Model — Tripo Developers Multiview to 3D Model — H Series ================================ CopyDownload PDF \# Multiview to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/multiview-to-model\` Generate a 3D model from multiview images. Multiple angles improve geometry accuracy and texture coverage. ## Request Parameters ### inputs - \*\*Type:\*\* object\[\] | string\[\] - \*\*Required:\*\* Required \*\*Three formats — use exactly one, do not mix.\*\* - \*\*view-key (recommended)\*\* — Array of objects; each object has exactly one key among \`front\`, \`left\`, \`back\`, \`right\`. Values may be a URL, \`file\_token\`, or nested \`{url}\` / \`{file\_token}\` / \`{object:{bucket,key}}\`. Order does not matter; the server canonicalizes to \*\*\[front, left, back, right\]\*\*. - \*\*legacy positional\*\* — Exactly 4 strings in order \*\*\[front, left, back, right\]\*\*. Use an empty string \`""\` to skip a view. - \*\*task\_id\*\* — Pass the ID of a previous Image to Multiview or Edit Multiview task to reuse its 4-view output. Only \`\[{"task\_id":""}\]\` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be \`success\` with type \`generate\_multiview\_image\` or \`edit\_multiview\_image\`. For view-key and legacy positional, each image value accepts: - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/front.png\` - The front view \*\*cannot be omitted\*\*. You may omit other views, but at least 2 images are required. - All images should depict the same object under consistent lighting. - Formats: \`PNG\`, \`JPEG\`, \`WebP\` - Recommended resolution: at least \*\*256 × 256 px\*\*. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### View-key with URLs \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "https://example.com/front.png" }, { "back": "https://example.com/back.png" }, { "right": "https://example.com/right.png" } \], "model": "v3.1-20260211", "texture": false, "geometry\_quality": "detailed" }' \`\`\` ### View-key with file\_tokens \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "front": "3154b4b0-4647-4032-aa82-827441ae92ef" }, { "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d" }, { "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6" } \], "model": "v3.1-20260211", "texture": false, "geometry\_quality": "detailed" }' \`\`\` ### Legacy positional \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ "https://example.com/front.png", "", "https://example.com/back.png", "https://example.com/right.png" \], "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### From multiview task \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/multiview-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "inputs": \[ { "task\_id": "550e8400-e29b-41d4-a716-446655440000" } \], "model": "v3.1-20260211", "texture": true, "pbr": true }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputsobject\[\] | string\[\]Required **Three formats — use exactly one, do not mix.** * **view-key (recommended)** — Array of objects; each object has exactly one key among `front`, `left`, `back`, `right`. Values may be a URL, `file_token`, or nested `{url}` / `{file_token}` / `{object:{bucket,key}}`. Order does not matter; the server canonicalizes to **\[front, left, back, right\]**. * **legacy positional** — Exactly 4 strings in order **\[front, left, back, right\]**. Use an empty string `""` to skip a view. * **task\_id** — Pass the ID of a previous [Image to Multiview](https://developers.tripo3d.ai/en/docs/generation-image-to-multiview) or Edit Multiview task to reuse its 4-view output. Only `[{"task_id":""}]` (single-element array) is accepted — do not mix with view-key or positional slots. The source task must be `success` with type `generate_multiview_image` or `edit_multiview_image`. For view-key and legacy positional, each image value accepts: * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/front.png` Notes * The front view **cannot be omitted**. You may omit other views, but at least 2 images are required. * All images should depict the same object under consistent lighting. * Formats: `PNG`, `JPEG`, `WebP` * Recommended resolution: at least **256 × 256 px**. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- View-key with URLsCopy { "inputs": [\ {\ "front": "https://example.com/front.png"},\ {\ "back": "https://example.com/back.png"},\ {\ "right": "https://example.com/right.png"}\ ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed"} View-key with file\_tokensCopy { "inputs": [\ {\ "front": "3154b4b0-4647-4032-aa82-827441ae92ef"},\ {\ "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},\ {\ "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}\ ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed"} Legacy positionalCopy { "inputs": [\ "https://example.com/front.png",\ "",\ "https://example.com/back.png",\ "https://example.com/right.png"], "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} From multiview taskCopy { "inputs": [\ {\ "task_id": "550e8400-e29b-41d4-a716-446655440000"}\ ], "model": "v3.1-20260211", "texture": true, "pbr": true } Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } NextIntroduction --- # Image to 3D Model — Tripo Developers Image to 3D Model — H Series ============================ CopyDownload PDF \# Image to 3D Model — H Series \*\*Base URL:\*\* \`https://openapi.tripo3d.ai/v3\` \*\*Endpoint:\*\* \`POST /generation/image-to-model\` Generate a 3D model from an image. The system infers geometry and texture from the input. ## Request Parameters ### input - \*\*Type:\*\* string - \*\*Required:\*\* Required Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types:\*\*Choose exactly one\*\* of the following — do not pass multiple types simultaneously. - file\_token — Upload an image via the File Upload API first, then pass the returned token. Example: \`file\_abc123\` - URL — A publicly accessible direct link to an image. Example: \`https://example.com/photo.png\` - task\_id — The task ID from a previous image generation task (\`text\_to\_image\` or \`image\_to\_image\`). The system automatically extracts the output image. Example: \`task\_abc123\` - Supported formats: \`PNG\`, \`JPEG\`, \`WebP\` - Max file size: \*\*20 MB\*\* - Recommended resolution: at least \*\*256 × 256 px\*\*. Subject should be clearly visible with a clean background and minimal occlusion. ### model - \*\*Type:\*\* string - \*\*Required:\*\* Required AI model version. - \`v3.1-20260211\` — latest, best quality. - \`v3.0-20250812\` — stable, advanced features. - \`v2.5-20250123\` — balanced. ### enable\_image\_autofix - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. ### texture\_alignment - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`original\_image\` Texture alignment priority. - \`original\_image\` — prioritize matching the input image colors. - \`geometry\` — prioritize matching the generated geometry. ### orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`default\` Model orientation. - \`default\` — automatic orientation. - \`align\_image\` — align the model to the input image viewpoint. Only effective when \`texture\` is \`true\`. Has no effect without texture enabled. ### face\_limit - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Maximum polycount for the output mesh. - If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | Triangle — v3.1 | \*\*1,500,000\*\* | \*\*2,000,000\*\* | | Triangle — v3.0 | \*\*1,000,000\*\* | \*\*2,000,000\*\* | | Triangle — v2.5 | \*\*500,000\*\* | / | | Quad (\`quad: true\`) | \*\*150,000\*\* | - Game-ready assets: \*\*50,000 – 100,000\*\*. Web/mobile: \*\*10,000 – 50,000\*\*. - When \`smart\_low\_poly: true\`, face limits are fixed regardless of model version: Triangle \*\*500 – 20,000\*\*, Quad \*\*500 – 10,000\*\*. ### texture - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. ### pbr - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Enable PBR material maps (\`base\_color\`, \`metallic\`, \`roughness\`, \`normal\`).When \`pbr\` is set to \`true\`, \`texture\` will be automatically forced to \`true\`. ### texture\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. ### texture\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Texture quality level. - \`fast\` — the fastest generation, trading texture detail for speed. Output texture size is identical to \`standard\`. Requires texture \`v3.5-20260815\`; costs the same as \`standard\`. - \`standard\` — balanced quality and speed. - \`detailed\` — higher fidelity, slower generation. - \`extreme\` — 8K textures, highest fidelity. Costs additional credits compared to detailed. \`fast\` is only available on texture \`v3.5-20260815\`. On the generation endpoints that means \`texture\_version\` must be set to it; on \`/v3/models/texture\` it means \`model\`. Any other texture version returns \`1004\` rather than silently falling back to \`standard\`. ### texture\_version - \*\*Type:\*\* string - \*\*Required:\*\* Optional Pins the texture model independently of the geometry \`model\`. - \`v3.5-20260815\` — newest texture model. Required for \`texture\_quality=fast\` and \`delight\`. - \`v3.0-20250812\` — default for \`v3.x\` and P-series geometry. - \`v2.5-20250123\` — default for \`v2.5-20250123\` geometry. If omitted, it is derived from the geometry \`model\` as listed above. ### delight - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Removes baked-in lighting from the reference image before texturing. Set \`false\` to keep the original shading. Only the \`v3.5-20260815\` texture model reads this; older texture versions ignore it. ### geometry\_quality - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`standard\` Geometry quality level. - \`standard\` — balanced quality and speed. - \`detailed\` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. ### auto\_size - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. ### quad - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to output a quad mesh (four-sided polygons) instead of triangles. If \`face\_limit\` is not set, the default face count will be 10,000.Enabling \`quad\` will force the output format to \`FBX\`. ### smart\_low\_poly - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. ### generate\_parts - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`false\` Generate editable segmented parts.Not compatible with \`texture\`, \`pbr\`, \`quad\`, or \`smart\_low\_poly\`: - \`texture=true\` or \`pbr=true\` — including omitting \`texture\`, which defaults to \`true\` — the request is rejected with error code \`1004\`. - \`quad=true\` — quad is ignored; the returned parts are triangle meshes. - \`smart\_low\_poly=true\` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set \`texture=false\` and \`pbr=false\`, and do not send \`quad\` or \`smart\_low\_poly\`. ### compress - \*\*Type:\*\* string - \*\*Required:\*\* Optional Compression type. - \`geometry\` — meshopt compression for reduced file size. - The following parameters are only valid when \`model ≥ v3.0-20250812\`: \`texture\_quality\`, \`geometry\_quality\`, \`auto\_size\`, \`quad\`, \`smart\_low\_poly\`, \`generate\_parts\`, \`compress\`. ### export\_orientation - \*\*Type:\*\* string - \*\*Required:\*\* Optional - \*\*Default:\*\* \`+x\` Export orientation (forward axis). - \`+x\` — default, X-forward. - \`-x\` — negative X-forward. - \`-y\` — negative Y-forward. - \`+y\` — Y-forward. - Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended \*\*not\*\* to set this parameter. - When set, post-processing the model may produce a wrongly-oriented result while the task still reports \`status: success\` — no error is raised. Use with caution. - If you plan to post-process the model, leave this unset and convert the orientation in the last step via \`/v3/models/convert\`. ### model\_seed - \*\*Type:\*\* integer - \*\*Required:\*\* Optional Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. ### export\_uv - \*\*Type:\*\* boolean - \*\*Required:\*\* Optional - \*\*Default:\*\* \`true\` Controls UV unwrapping during generation. Set \`false\` for faster generation and smaller file size. UV unwrapping will be handled during texturing. ## Request Example ### From URL \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "https://example.com/image.png", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture\_quality": "detailed" }' \`\`\` ### With autofix \`\`\`bash curl --request POST \\ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \\ --header 'Authorization: Bearer ' \\ --header 'Content-Type: application/json' \\ --data '{ "input": "file\_abc123", "model": "v3.1-20260211", "enable\_image\_autofix": true, "orientation": "align\_image" }' \`\`\` ## Response Example ### Create task \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123" } } \`\`\` ### Task result \`\`\`json { "code": 0, "data": { "task\_id": "task\_abc123", "type": "text\_to\_model", "status": "success", "progress": 100, "output": { "model\_url": "https://cdn.tripo3d.ai/output/model\_pbr.glb", "rendered\_image\_url": "https://cdn.tripo3d.ai/output/preview.png" }, "credits\_consumed": 100.00, "created\_at": "2026-04-28T12:00:00Z", "completed\_at": "2026-04-28T12:01:30Z" } } \`\`\` Request Parameters ------------------ ### Request Body inputstringRequired Image source. The subject should be clearly visible with minimal occlusion. Accepts the following input types: **Choose exactly one** of the following — do not pass multiple types simultaneously. * file\_token — Upload an image via the [File Upload API](https://developers.tripo3d.ai/en/docs/files) first, then pass the returned token. Example: `file_abc123` * URL — A publicly accessible direct link to an image. Example: `https://example.com/photo.png` * task\_id — The task ID from a previous image generation task (`text_to_image` or `image_to_image`). The system automatically extracts the output image. Example: `task_abc123` Notes * Supported formats: `PNG`, `JPEG`, `WebP` * Max file size: **20 MB** * Recommended resolution: at least **256 × 256 px**. Subject should be clearly visible with a clean background and minimal occlusion. modelstringRequired AI model version. * `v3.1-20260211` — latest, best quality. * `v3.0-20250812` — stable, advanced features. * `v2.5-20250123` — balanced. enable\_image\_autofixbooleandefault: false Whether to automatically optimize the input image before generation. Used for AI completion and 3D quality enhancement. When enabled, the system will enhance low-resolution or low-quality images to improve 3D generation results. Default is false. texture\_alignmentstringdefault: original\_image Texture alignment priority. * `original_image` — prioritize matching the input image colors. * `geometry` — prioritize matching the generated geometry. orientationstringdefault: default Model orientation. * `default` — automatic orientation. * `align_image` — align the model to the input image viewpoint. Only effective when `texture` is `true`. Has no effect without texture enabled. face\_limitinteger Maximum polycount for the output mesh. Notes * If omitted, the model uses adaptive topology. Upper limits by mode | Mode | Standard | Ultra | | --- | --- | --- | | Triangle — v3.1 | **1,500,000** | **2,000,000** | | Triangle — v3.0 | **1,000,000** | **2,000,000** | | Triangle — v2.5 | **500,000** | / | | Quad (`quad: true`) | **150,000** | | * Game-ready assets: **50,000 – 100,000**. Web/mobile: **10,000 – 50,000**. * When `smart_low_poly: true`, face limits are fixed regardless of model version: Triangle **500 – 20,000**, Quad **500 – 10,000**. texturebooleandefault: true Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true. pbrbooleandefault: true Enable PBR material maps (`base_color`, `metallic`, `roughness`, `normal`). When `pbr` is set to `true`, `texture` will be automatically forced to `true`. texture\_seedinteger Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model\_seed unchanged and vary texture\_seed. texture\_qualitystringdefault: standard Texture quality level. * `fast` — the fastest generation, trading texture detail for speed. Output texture size is identical to `standard`. Requires texture `v3.5-20260815`; costs the same as `standard`. * `standard` — balanced quality and speed. * `detailed` — higher fidelity, slower generation. * `extreme` — 8K textures, highest fidelity. Costs additional credits compared to detailed. Notes `fast` is only available on texture `v3.5-20260815`. On the generation endpoints that means `texture_version` must be set to it; on `/v3/models/texture` it means `model`. Any other texture version returns `1004` rather than silently falling back to `standard`. texture\_versionstring Pins the texture model independently of the geometry `model`. * `v3.5-20260815` — newest texture model. Required for `texture_quality=fast` and `delight`. * `v3.0-20250812` — default for `v3.x` and P-series geometry. * `v2.5-20250123` — default for `v2.5-20250123` geometry. If omitted, it is derived from the geometry `model` as listed above. delightbooleandefault: true Removes baked-in lighting from the reference image before texturing. Set `false` to keep the original shading. Only the `v3.5-20260815` texture model reads this; older texture versions ignore it. geometry\_qualitystringdefault: standard Geometry quality level. * `standard` — balanced quality and speed. * `detailed` — Ultra mode, finer geometry detail. Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5. auto\_sizebooleandefault: false Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false. quadbooleandefault: false Whether to output a quad mesh (four-sided polygons) instead of triangles. If `face_limit` is not set, the default face count will be 10,000. Enabling `quad` will force the output format to `FBX`. smart\_low\_polybooleandefault: false Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false. generate\_partsbooleandefault: false Generate editable segmented parts. Not compatible with `texture`, `pbr`, `quad`, or `smart_low_poly`: * `texture=true` or `pbr=true` — including omitting `texture`, which defaults to `true` — the request is rejected with error code `1004`. * `quad=true` — quad is ignored; the returned parts are triangle meshes. * `smart_low_poly=true` — smart\_low\_poly takes precedence and parts are NOT produced. To generate parts, set `texture=false` and `pbr=false`, and do not send `quad` or `smart_low_poly`. compressstring Compression type. * `geometry` — meshopt compression for reduced file size. Notes * The following parameters are only valid when `model ≥ v3.0-20250812`: `texture_quality`, `geometry_quality`, `auto_size`, `quad`, `smart_low_poly`, `generate_parts`, `compress`. export\_orientationstringdefault: +x Export orientation (forward axis). * `+x` — default, X-forward. * `-x` — negative X-forward. * `-y` — negative Y-forward. * `+y` — Y-forward. Notes * Applies to this generation only. If the model will be used in post-processing tasks (texture, rig, retarget, convert, ...), it is recommended **not** to set this parameter. * When set, post-processing the model may produce a wrongly-oriented result while the task still reports `status: success` — no error is raised. Use with caution. * If you plan to post-process the model, leave this unset and convert the orientation in the last step via `/v3/models/convert`. model\_seedinteger Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time. export\_uvbooleandefault: true Controls UV unwrapping during generation. Set `false` for faster generation and smaller file size. UV unwrapping will be handled during texturing. Examples -------- From URLCopy { "input": "https://example.com/image.png", "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed"} With autofixCopy { "input": "file_abc123", "model": "v3.1-20260211", "enable_image_autofix": true, "orientation": "align_image"} Create taskCopy { "code": 0, "data": { "task_id": "task_abc123"} } Task resultCopy { "code": 0, "data": { "task_id": "task_abc123", "type": "text_to_model", "status": "success", "progress": 100, "output": { "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb", "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"}, "credits_consumed": 100.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z"} } NextIntroduction ---