# Tripo API 介绍

Tripo3D 是一个 AI 3D 生成平台，提供文生 3D、图生 3D、动画绑骨、网格编辑等能力。通过 Tripo API，开发者可以将高质量 3D 内容生成集成到自有产品中。

> 如果您在中国大陆访问，请前往国内站：[developers.tripo3d.com](https://developers.tripo3d.com)

## Base URL

```baseurl
https://openapi.tripo3d.ai/v3
```

## 认证方式

所有 API 请求需要在请求头中携带 API Key：

```apikey
Authorization: Bearer {api_key}
```

API Key 可在 [Tripo 控制台](/zh/keys) 创建和管理。

## 统一响应格式

### 成功响应

```json
{
  "code": 0,
  "data": {
    ...
  }
}
```

### 错误响应

```json
{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account"
}
```

### 公共字段

| 参数 | 类型 | 说明 |
| :-: | :-: | :-: |
| code | integer | 状态码，`0` 表示成功，非 `0` 表示错误 |
| data | object | 业务数据（仅成功时返回） |
| message | string | 错误描述（仅失败时返回） |
| suggestion | string | 修复建议（仅失败时返回） |

## 异步任务模式

大部分生成类接口采用异步任务模式：

1. **创建任务**：POST 请求创建任务，返回 `task_id`
2. **轮询结果**：使用 `GET /v3/tasks/{task_id}` 查询任务状态和结果

```
POST /v3/generation/text-to-model  →  {"code": 0, "data": {"task_id": "task_abc123"}}
                                              ↓
GET  /v3/tasks/task_abc123          →  {"code": 0, "data": {"status": "running", "progress": 50}}
                                              ↓
GET  /v3/tasks/task_abc123          →  {"code": 0, "data": {"status": "success", "output": {...}}}
```

### 任务状态

| 状态 | 说明 |
| :-: | :-: |
| `queued` | 排队中 |
| `running` | 运行中 |
| `success` | 成功 |
| `failed` | 失败 |
| `cancelled` | 已取消 |

## API 版本

当前版本：**v3**

## 端点总览

### 3D 模型生成

| 端点 | 说明 |
| :-: | :-: |
| [`POST /v3/generation/text-to-model`](/zh/docs/generation-text-to-model) | 文本生成 3D 模型 |
| [`POST /v3/generation/image-to-model`](/zh/docs/generation-image-to-model) | 图片生成 3D 模型 |
| [`POST /v3/generation/multiview-to-model`](/zh/docs/generation-multiview-to-model) | 多视角生成 3D 模型 |

### 图像生成

| 端点 | 说明 |
| :-: | :-: |
| [`POST /v3/generation/text-to-image`](/zh/docs/generation-text-to-image) | 文本生成图片 |
| [`POST /v3/generation/image-to-image`](/zh/docs/generation-image-to-image) | 图片风格转换 |
| [`POST /v3/generation/image-to-multiview`](/zh/docs/generation-image-to-multiview) | 图片生成多视角 |
| [`POST /v3/generation/edit-multiview`](/zh/docs/generation-edit-multiview) | 多视角编辑 |

### 模型后处理

| 端点 | 说明 |
| :-: | :-: |
| [`POST /v3/models/texture`](/zh/docs/models-texture) | 贴图 |
| [`POST /v3/models/convert`](/zh/docs/models-convert) | 格式转换 |
| [`POST /v3/mesh/segment`](/zh/docs/mesh-segment) | 语义分割 |
| [`POST /v3/mesh/complete`](/zh/docs/mesh-complete) | 网格补全 |
| [`POST /v3/mesh/decimate`](/zh/docs/mesh-decimate) | 重拓扑 |

### 动画

| 端点 | 说明 |
| :-: | :-: |
| [`POST /v3/animations/rig-check`](/zh/docs/animations-rig-check) | 骨骼绑定检查 |
| [`POST /v3/animations/rig`](/zh/docs/animations-rig) | 骨骼绑定 |
| [`POST /v3/animations/retarget`](/zh/docs/animations-retarget) | 动画重定向 |

### 任务管理

| 端点 | 说明 |
| :-: | :-: |
| [`GET /v3/tasks/{task_id}`](/zh/docs/task-query) | 查询任务 |
| [`POST /v3/tasks/list`](/zh/docs/task-batch-query) | 批量查询任务 |

### 文件管理

| 端点 | 说明 |
| :-: | :-: |
| [`POST /v3/files`](/zh/docs/files) | 上传文件 |

### 账户

| 端点 | 说明 |
| :-: | :-: |
| [`GET /v3/account/balance`](/zh/docs/account) | 查询余额 |