> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetoken.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Tripo H3.1 — 文生 3D

> 使用 Tripo H3.1 由文本提示词生成高精度、带 PBR 贴图的 3D 模型。

| | |
| - | - |
| **模型 ID** | `tripo/h3.1-text-to-3d` |
| **系列** | `tripo-h3.1` |
| **任务** | `text-to-3d` |
| **模态** | 3D |
| **上游** | Tripo H3.1（Tripo 官方 API） |

> [!NOTE]
>
> H3.1 默认返回带 PBR 材质的 GLB。HD 与 8K 贴图、超精细几何、四边面网格、
> 智能低模和部件拆分均需手动开启，每一项都会增加费用。

## 端点

```http theme={null}
POST https://vibetoken.cn/v1/3d/generations
```

异步 —— 返回 `{id, status: "pending"}`；轮询
`GET /v1/3d/generations/{id}` 直到 `success` 或 `failed`。大多数生成
会在 1–3 分钟内完成。幂等性、回调与错误见 [3D 生成参考](https://docs.vibetoken.cn/zh/api-reference/3d.md)。

## 参数

**prompt** `string` *required*

描述要生成的物体的文本。最长 1024 字符。

**negative\_prompt** `string`

不希望出现在模型中的内容。最长 255 字符。

**texture** `boolean` (default: true)

为模型生成贴图。将它与 `pbr` 都设为 `false` 可得到无贴图的白模，计费更低。

**pbr** `boolean` (default: true)

生成基于物理的（PBR）材质。`pbr: true` 会同时开启贴图，因此无贴图白模需要
把 `texture` 和 `pbr` 都设为 `false`。

**texture\_quality** `"fast" | "standard" | "detailed" | "extreme"` (default: "standard")

`detailed` 为 HD 贴图，`extreme` 为 8K 贴图。仅在生成贴图时生效；
`detailed` 与 `extreme` 会增加费用。
`fast` 以贴图细节换取速度，按标准价计费；它运行在贴图模型
`v3.5-20260815` 上，会自动使用。

**geometry\_quality** `"standard" | "detailed"` (default: "standard")

`detailed` 为超精细几何模式，表面细节更密、更精细。会增加费用。

**quad** `boolean` (default: false)

输出四边面网格而非三角面。此时模型文件为 `.fbx` 而不是 `.glb`。会增加费用。

**smart\_low\_poly** `boolean` (default: false)

生成拓扑干净、接近手工布线的低模网格。形状越简单效果越好。会增加费用。

**generate\_parts** `boolean` (default: false)

将模型拆分为可单独编辑的部件。需要同时设置 `texture: false` 与
`pbr: false`。会增加费用。

**face\_limit** `integer`

输出网格的最大面数，范围 500 到 2,000,000。不传则由模型根据物体自动选择
合适的面数。

**auto\_size** `boolean` (default: false)

按真实世界尺寸缩放模型，单位为米。

**model\_seed** `integer`

几何随机种子，`0` 到 `2147483647`。相同输入配合相同种子可复现同一网格。

**texture\_seed** `integer`

贴图随机种子，`0` 到 `2147483647`。固定 `model_seed` 后改变它，可在同一
几何上得到不同贴图。

**image\_seed** `integer`

提示词处理阶段的随机种子，`0` 到 `2147483647`。与 `model_seed`、
`texture_seed` 一起固定，可复现文生 3D 的结果。

**texture\_version** `"v3.5-20260815" | "v3.0-20250812"`

独立于几何模型指定贴图模型。不传时使用默认值（`v3.0-20250812`；
`texture_quality: "fast"` 时为 `v3.5-20260815`）。

**delight** `boolean` (default: true)

贴图前去除参考图中烘焙的光照。仅贴图模型 `v3.5-20260815` 读取此项。

**export\_uv** `boolean` (default: true)

生成时展开 UV。设为 `false` 生成更快、文件更小。

**export\_orientation** `"+x" | "-x" | "-y" | "+y"` (default: "+x")

导出模型的前向轴。

**compress** `"geometry"`

压缩网格（meshopt），得到更小的文件。

## 输出

`success` 时，`data` 按固定顺序包含生成的文件：

* `data[0].url` —— 3D 模型：内嵌材质的二进制 glTF（`.glb`）文件；`quad: true` 时为 `.fbx`。
* `data[1].url` —— 模型的 PNG 渲染预览图（Tripo 返回时提供）。

两个文件都托管在 VibeToken 媒体 CDN 上，每个 URL 都以文件的真实扩展名结尾，可据此选择
加载器。需要长期保留的文件请自行下载保存。

## 示例

```bash cURL theme={null}
curl https://vibetoken.cn/v1/3d/generations \
  -H "Authorization: Bearer $VIBETOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo/h3.1-text-to-3d",
    "prompt": "a weathered bronze dragon statue coiled around a stone pillar, intricate scales",
    "texture_quality": "detailed"
  }'
```

```python Python theme={null}
import os
import time

import requests

BASE_URL = "https://vibetoken.cn/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VIBETOKEN_API_KEY']}"}

job = requests.post(
    f"{BASE_URL}/3d/generations",
    headers=HEADERS,
    json={
        "model": "tripo/h3.1-text-to-3d",
        "prompt": "a weathered bronze dragon statue coiled around a stone pillar, intricate scales",
        "texture_quality": "detailed",
    },
    timeout=60,
).json()

for _ in range(120):  # 每 5 秒轮询一次，最多 10 分钟
    gen = requests.get(f"{BASE_URL}/3d/generations/{job['id']}", headers=HEADERS, timeout=30).json()
    if gen["status"] in ("success", "failed"):
        break
    time.sleep(5)

if gen["status"] != "success":
    raise RuntimeError(gen.get("error_message") or "3D generation did not finish")

model_url = gen["data"][0]["url"]  # 3D 模型（.glb；quad: true 时为 .fbx）
preview_url = gen["data"][1]["url"] if len(gen["data"]) > 1 else None  # PNG 预览图（返回时提供）
with open("model." + model_url.rsplit(".", 1)[-1], "wb") as out:
    out.write(requests.get(model_url, timeout=300).content)
```

```javascript JavaScript theme={null}
const BASE_URL = "https://vibetoken.cn/v1";
const headers = {
  Authorization: `Bearer ${process.env.VIBETOKEN_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch(`${BASE_URL}/3d/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "tripo/h3.1-text-to-3d",
    prompt: "a weathered bronze dragon statue coiled around a stone pillar, intricate scales",
    texture_quality: "detailed",
  }),
}).then((r) => r.json());

let gen;
for (let i = 0; i < 120; i++) { // 每 5 秒轮询一次，最多 10 分钟
  gen = await fetch(`${BASE_URL}/3d/generations/${job.id}`, { headers }).then((r) => r.json());
  if (gen.status === "success" || gen.status === "failed") break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}
if (gen.status !== "success") throw new Error(gen.error_message ?? "3D generation did not finish");

console.log(gen.data[0].url);  // 3D 模型（.glb；quad: true 时为 .fbx）
console.log(gen.data[1]?.url); // PNG 预览图（返回时提供）
```

```json theme={null}
{
  "id": "5d1c3e0a-7b2f-4c4e-9a51-2f0f8a9b6c13",
  "object": "3d.generation",
  "status": "pending",
  "model": "tripo/h3.1-text-to-3d",
  "created": 1794182400
}
```

轮询直到终态：

```bash theme={null}
curl https://vibetoken.cn/v1/3d/generations/5d1c3e0a-7b2f-4c4e-9a51-2f0f8a9b6c13 \
  -H "Authorization: Bearer $VIBETOKEN_API_KEY"
```

```json theme={null}
{
  "id": "5d1c3e0a-7b2f-4c4e-9a51-2f0f8a9b6c13",
  "object": "3d.generation",
  "status": "success",
  "model": "tripo/h3.1-text-to-3d",
  "data": [
    { "url": "https://media.vibetoken.cn/media/<user>/<gen>/0.glb" },
    { "url": "https://media.vibetoken.cn/media/<user>/<gen>/1.png" }
  ],
  "created": 1794182400
}
```

## 编写提示词

* 描述单个物体而不是场景：形状、材质、颜色和风格，例如「一把竹柄陶瓷茶壶，哑光蓝釉」。
* 不想要的内容（底座、文字、多余部件）写进 `negative_prompt`，而不是写进提示词。
* 迭代时固定 `model_seed`、改变 `texture_seed`（或反过来），让几何与贴图分别变化。

## 定价

按次计费；开启的选项会改变价格，失败的生成不收费。影响价格的因素见
[Tripo H3.1 快速入门](https://docs.vibetoken.cn/zh/tripo-h3-1-api/quickstart.md)，当前费率见[定价页](https://vibetoken.cn/pricing)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.