Quick Start

# Quick Start Get started with the Tripo API in 15 minutes and generate your first 3D model from scratch. `model` is required for text-to-model, image-to-model and multiview-to-model. Choose [H Series](/en/docs/generation-text-to-model/standard) or [P Series](/en/docs/generation-text-to-model/p). The task ID below is illustrative; use the `task_id` returned by the API in subsequent requests. ## 1. Get an API Key Go to the [Tripo Console](https://developers.tripo3d.ai/en/keys), 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": "v3.1-20260211" }' ``` Success response: ```json { "code": 0, "data": { "task_id": "123e4567-e89b-42d3-a456-426614174000" } } ``` ## 3. Query the Task Result 3D generation runs as an asynchronous task. Use the returned `task_id` to poll the task status: ```bash # Replace with the task_id returned by the create request TASK_ID="<task_id>" curl -X GET "https://openapi.tripo3d.ai/v3/tasks/$TASK_ID" \ -H "Authorization: Bearer {api_key}" ``` When `status` is `success`, the task is complete: ```json { "code": 0, "data": { "task_id": "123e4567-e89b-42d3-a456-426614174000", "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": "v3.1-20260211" } ) task_id = response.json()["data"]["task_id"] print(f"Task created: {task_id}") # 2. Poll until the task is complete for _ in range(300): response = requests.get( f"{BASE_URL}/tasks/{task_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30 ) 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", "expired"): raise RuntimeError(f"Task failed: {status}") time.sleep(2) else: raise TimeoutError("Task polling timed out") # 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: "v3.1-20260211" }) }); const { data: { task_id } } = await createResponse.json(); console.log(`Task created: ${task_id}`); // 2. Poll until the task is complete for (let attempt = 0; attempt < 300; attempt++) { const pollResponse = await fetch(`${BASE_URL}/tasks/${task_id}`, { headers: { "Authorization": `Bearer ${API_KEY}` }, signal: AbortSignal.timeout(30000) }); 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", "expired"].includes(status)) { throw new Error(`Task failed: ${status}`); } await new Promise(resolve => setTimeout(resolve, 2000)); } throw new Error("Task polling timed out"); } generateModel().catch(console.error); ```

curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "prompt": "a cute cat",
    "model": "v3.1-20260211"
  }'

{
  "code": 0,
  "data": {
    "task_id": "123e4567-e89b-42d3-a456-426614174000"
  }
}

# Set TASK_ID to the task_id returned by the create request
curl -X GET "https://openapi.tripo3d.ai/v3/tasks/$TASK_ID" \
  -H "Authorization: Bearer <token>"

{
  "code": 0,
  "data": {
    "task_id": "123e4567-e89b-42d3-a456-426614174000",
    "type": "text_to_model",
    "status": "success",
    "progress": 100,
    "output": {
      "model_url": "https://...",
      "rendered_image_url": "https://..."
    }
  }
}

import requests, time

HEADERS = {"Authorization": "Bearer <token>", "Content-Type": "application/json"}

def poll(task_id):
    for _ in range(300):
        r = requests.get(f"https://openapi.tripo3d.ai/v3/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if r["data"]["status"] == "success": return r["data"]
        if r["data"]["status"] in ("failed", "cancelled", "banned", "expired"): raise RuntimeError(r["data"])
        time.sleep(2)
    raise TimeoutError("Task polling timed out")

# Step 1 — Generate model
task_id = requests.post("https://openapi.tripo3d.ai/v3/generation/image-to-model",
    headers=HEADERS, json={"input":"<file_token>","model":"P2-20260801","face_limit":5000}
).json()["data"]["task_id"]
poll(task_id)

# Step 2 — Rig check
check_id = requests.post("https://openapi.tripo3d.ai/v3/animations/rig-check",
    headers=HEADERS, json={"input":task_id}).json()["data"]["task_id"]
check = poll(check_id)["output"]
if not check.get("riggable"):
    raise RuntimeError("Model is not riggable")
if check.get("rig_type") != "biped":
    raise RuntimeError("This character workflow requires a biped model")
rig_type = check["rig_type"]

# Step 3 — Rig
rig_id = requests.post("https://openapi.tripo3d.ai/v3/animations/rig",
    headers=HEADERS, json={"input":task_id,"model":"v3.0-20260909","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,"animation":"preset:walk"}
).json()["data"]["task_id"]
result = poll(anim_id)
print("Animated model:", result["output"]["model_url"])