> ## 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 P2 — 图生 3D

> 使用 Tripo P2 将单张参考图转换为游戏级低模 3D 模型，可选四边面网格。

| | |
| - | - |
| **模型 ID** | `tripo/p2-image-to-3d` |
| **系列** | `tripo-p2` |
| **任务** | `image-to-3d` |
| **模态** | 3D |
| **上游** | Tripo P2（Tripo 官方 API） |

> [!NOTE]
>
> P2 将图中物体重建为最多 50,000 个三角面的游戏级低模网格。设置
> `quad: true` 可得到最多 25,000 个四边面的四边面网格，以 FBX 交付。

## 端点

```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)。

## 参数

**image\_urls** `string[]` *required*

仅含一个元素的数组，为参考图：公开的 HTTPS URL，或 base64 `data:` URI
（提交任务前会先替你托管）。支持 JPEG、PNG、WebP。无法访问的 URL 会在
预留任何费用之前以 `400` 拒绝。

**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` 上，会自动使用。

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

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

**face\_limit** `integer`

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

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

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

**enable\_image\_autofix** `boolean` (default: false)

让 Tripo 在生成前先优化输入图片，以便从不够理想的照片中获得更好的结果。

**texture\_alignment** `"original_image" | "geometry"` (default: "original\_image")

`original_image` 让贴图忠实于原图；`geometry` 让贴图对齐生成的网格，
更注重结构准确。

**orientation** `"default" | "align_image"` (default: "default")

`align_image` 会旋转模型，使其与图中物体的朝向一致；`default` 保持标准朝向。

**model\_seed** `integer`

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

**texture\_seed** `integer`

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

**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")

导出模型的前向轴。

## 输出

`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/p2-image-to-3d",
    "image_urls": ["https://example.com/character-concept.png"],
    "quad": true
  }'
```

```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/p2-image-to-3d",
        "image_urls": ["https://example.com/character-concept.png"],
        "quad": True,
    },
    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/p2-image-to-3d",
    image_urls: ["https://example.com/character-concept.png"],
    quad: true,
  }),
}).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/p2-image-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/p2-image-to-3d",
  "data": [
    { "url": "https://media.vibetoken.cn/media/<user>/<gen>/0.fbx" },
    { "url": "https://media.vibetoken.cn/media/<user>/<gen>/1.png" }
  ],
  "created": 1794182400
}
```

## 选择输入图片

* 使用单个物体，完整入画，背景为纯色或透明。裁掉其他内容。
* 清晰的四分之三视角能展示最多的形体；图中看不到的侧面由模型推断。
* 均匀、没有强烈阴影的光照能得到更干净的贴图。照片不够理想时，可尝试
  `enable_image_autofix: true`。

## 定价

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


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