# 快速入门

15 分钟上手 Tripo API，从零开始生成你的第一个 3D 模型。

## 1. 获取 API Key

前往 [Tripo 控制台](https://platform.tripo3d.ai) 注册账号，进入「API 密钥」页面创建一个 API Key。

## 2. 发送第一个请求

使用文本描述生成一个 3D 模型：

### 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"
  }'
```

成功响应：

```json
{
  "code": 0,
  "data": {
    "task_id": "task_abc123"
  }
}
```

## 3. 查询任务结果

3D 生成是异步任务，使用返回的 `task_id` 轮询任务状态：

```bash
curl -X GET https://openapi.tripo3d.ai/v3/tasks/task_abc123 \
  -H "Authorization: Bearer {api_key}"
```

当 `status` 为 `success` 时，任务完成：

```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. 下载模型

从响应中的 `output.model_url` 下载 GLB 格式的 3D 模型文件，可直接在 Blender、Unity、Three.js 等工具中使用。

## 完整示例

### 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. 创建文生 3D 任务
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_id}")

# 2. 轮询等待任务完成
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}, 进度: {progress}%")

    if status == "success":
        model_url = task["output"]["model_url"]
        print(f"模型下载地址: {model_url}")
        break
    elif status in ("failed", "cancelled", "banned"):
        print(f"任务失败: {status}")
        break

    time.sleep(2)

# 3. 下载模型文件
if status == "success":
    model_data = requests.get(model_url)
    with open("model.glb", "wb") as f:
        f.write(model_data.content)
    print("模型已保存为 model.glb")
```

### JavaScript

```javascript
const API_KEY = "your_api_key_here";
const BASE_URL = "https://openapi.tripo3d.ai/v3";

async function generateModel() {
  // 1. 创建文生 3D 任务
  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_id}`);

  // 2. 轮询等待任务完成
  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}, 进度: ${progress}%`);

    if (status === "success") {
      console.log(`模型下载地址: ${task.output.model_url}`);
      return task.output;
    }
    if (["failed", "cancelled", "banned"].includes(status)) {
      throw new Error(`任务失败: ${status}`);
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

generateModel().catch(console.error);
```