> ## 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.

# 3D 生成

> 基于 Tripo 的异步 3D 模型生成。提交任务后，通过 id 轮询（或提供 callback_url）。

## 端点

```
POST https://vibetoken.cn/v1/3d/generations
GET  https://vibetoken.cn/v1/3d/generations/{id}
GET  https://vibetoken.cn/v1/3d/generations?client_request_id=...
```

3D 生成是**异步的**。`POST` 会立即返回一个 `id` 以及 `status: "pending"`。可通过轮询 `GET /v1/3d/generations/{id}` 或设置 `callback_url` 来获取结果。大多数生成会在 1–3 分钟内完成。

## 模型

| 模型 ID | 系列 | 任务 |
| - | - | - |
| `tripo/h3.1-text-to-3d` | [Tripo H3.1](https://docs.vibetoken.cn/zh/tripo-h3-1-api/quickstart.md) | `text-to-3d` |
| `tripo/h3.1-image-to-3d` | [Tripo H3.1](https://docs.vibetoken.cn/zh/tripo-h3-1-api/quickstart.md) | `image-to-3d` |
| `tripo/p2-text-to-3d` | [Tripo P2](https://docs.vibetoken.cn/zh/tripo-p2-api/quickstart.md) | `text-to-3d` |
| `tripo/p2-image-to-3d` | [Tripo P2](https://docs.vibetoken.cn/zh/tripo-p2-api/quickstart.md) | `image-to-3d` |
| `tripo/p1-text-to-3d` | [Tripo P1](https://docs.vibetoken.cn/zh/tripo-p1-api/quickstart.md) | `text-to-3d` |
| `tripo/p1-image-to-3d` | [Tripo P1](https://docs.vibetoken.cn/zh/tripo-p1-api/quickstart.md) | `image-to-3d` |

H3.1 是 Tripo 的高精度模型。P2 与 P1 生成面向实时渲染的低模网格，其中 P2 支持原生四边面拓扑、面数更高。

## 请求头

| Header | Value |
| - | - |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type` | `application/json` |
| `Idempotency-Key` | 可选。让重试变得安全，见[幂等性](#幂等性)。 |

支持个人 API Key 和组织 API Key。使用组织 API Key 时从组织钱包扣费，见[组织 API Key](https://docs.vibetoken.cn/zh/essentials/organizations.md)。

## 请求体（POST）

**model** `string` *required*

上表中的 3D 模型 ID。传入其他模态的模型会返回 `400`。

**prompt** `string`

仅文生 3D，且为必填。描述要生成的物体，最长 1024 字符。

**negative\_prompt** `string`

仅文生 3D。不希望出现在模型中的内容，最长 255 字符。

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

仅图生 3D，且为必填。仅含一个元素的数组，为参考图：公开的 HTTPS URL，**也可以**是内联的 base64 `data:` URI（例如 `data:image/png;base64,...`），提交任务前会先替你托管。支持 JPEG、PNG、WebP。无法访问的 URL 会在预留任何费用之前返回 `400`。

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

生成贴图。将它与 `pbr` 都设为 `false` 可得到无贴图白模。

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

生成 PBR 材质。`pbr: true` 会同时开启贴图。

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

`detailed` 为 HD 贴图，`extreme` 为 8K 贴图。`fast` 以贴图细节换取速度，按标准价计费；它运行在贴图模型 `v3.5-20260815` 上，未传 `texture_version` 时会自动使用该版本。

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

仅 H3.1。`detailed` 为超精细几何模式。

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

H3.1 与 P2。输出四边面网格；此时模型文件为 `.fbx` 而不是 `.glb`。

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

仅 H3.1。生成拓扑干净、接近手工布线的低模网格。

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

仅 H3.1。将模型拆分为可单独编辑的部件。需要同时设置 `texture: false` 与 `pbr: false`。

**face\_limit** `integer`

输出网格的最大面数。范围取决于模型系列（见下文）。不传则由模型自行决定。

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

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

**model\_seed** `integer`

几何随机种子，`0` 到 `2147483647`。

**texture\_seed** `integer`

贴图随机种子，`0` 到 `2147483647`。

**image\_seed** `integer`

仅文生 3D。提示词处理阶段的随机种子，`0` 到 `2147483647`。

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

仅图生 3D。让 Tripo 在生成前先优化输入图片。

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

仅图生 3D。让贴图忠实于原图，或对齐生成的网格。

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

仅图生 3D。`align_image` 会旋转模型，使其与图中物体的朝向一致。

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

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

**client\_request\_id** `string`

可选的幂等 id，等同于请求头 `Idempotency-Key` 的请求体写法。见[幂等性](#幂等性)。

**callback\_url** `string`

可选。任务完成时，VibeToken 会将最终结果 `POST` 到此 URL。见[回调](#回调)。

### 各系列支持的选项

| 字段 | H3.1 | P2 | P1 |
| - | - | - | - |
| `texture`、`pbr`、`texture_quality`、`auto_size`、`model_seed`、`texture_seed` | 支持 | 支持 | 支持 |
| `texture_version`、`delight`、`export_uv`、`export_orientation` | 支持 | 支持 | 支持 |
| `face_limit` 范围 | 500–2,000,000 | 48–50,000 | 50–20,000 |
| `quad` | 支持 | 支持 | 不支持 |
| `geometry_quality`、`smart_low_poly`、`generate_parts`、`compress` | 支持 | 不支持 | 不支持 |

文生 3D 模型接收 `prompt`（以及 `negative_prompt` 和 `image_seed`）；图生 3D 模型接收
`image_urls`（以及 `enable_image_autofix`、`texture_alignment` 和 `orientation`），不接收提示词。
某个系列未列出的选项请不要传入。未传入的选项取上文所示的默认值，价格也按默认值计算。
各系列的选项详见其文档页。

## 提交任务

```bash cURL theme={null}
curl -X POST https://vibetoken.cn/v1/3d/generations \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo/h3.1-text-to-3d",
    "prompt": "a ceramic teapot with a bamboo handle, matte blue glaze"
  }'
```

```python Python theme={null}
import requests

r = requests.post(
    "https://vibetoken.cn/v1/3d/generations",
    headers={"Authorization": "Bearer sk-rb-xxxxxxxxxxxx"},
    json={
        "model": "tripo/h3.1-text-to-3d",
        "prompt": "a ceramic teapot with a bamboo handle, matte blue glaze",
    },
)
print(r.json()["id"])
```

```javascript JavaScript theme={null}
const r = await fetch("https://vibetoken.cn/v1/3d/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-rb-xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tripo/h3.1-text-to-3d",
    prompt: "a ceramic teapot with a bamboo handle, matte blue glaze",
  }),
});
console.log((await r.json()).id);
```

图生 3D 请改为发送 `image_urls`，不传 `prompt`：

```json theme={null}
{
  "model": "tripo/p1-image-to-3d",
  "image_urls": ["https://example.com/potion-bottle.png"]
}
```

### 响应（POST）

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

## 轮询状态（GET）

```
GET /v1/3d/generations/{id}
```

每 5 秒左右轮询一次，直到 `status` 为 `success` 或 `failed`。

```python Python theme={null}
import time, requests

def wait_for_model(gen_id, api_key, interval=5, timeout=900):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://vibetoken.cn/v1/3d/generations/{gen_id}"
    elapsed = 0
    while elapsed < timeout:
        s = requests.get(url, headers=headers).json()
        if s["status"] == "success":
            return [item["url"] for item in s["data"]]  # [模型文件, 预览图]
        if s["status"] == "failed":
            raise RuntimeError(s.get("error_message") or "Generation failed")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Generation timed out")
```

```javascript JavaScript theme={null}
async function waitForModel(genId, apiKey, { interval = 5000, timeout = 900000 } = {}) {
  const url = `https://vibetoken.cn/v1/3d/generations/${genId}`;
  const start = Date.now();
  while (Date.now() - start < timeout) {
    const r = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
    const s = await r.json();
    if (s.status === "success") return s.data.map((item) => item.url); // [模型文件, 预览图]
    if (s.status === "failed") throw new Error(s.error_message || "Generation failed");
    await new Promise((resolve) => setTimeout(resolve, interval));
  }
  throw new Error("Generation timed out");
}
```

### 响应（GET）

运行中：

```json theme={null}
{
  "id": "5d1c3e0a-...",
  "object": "3d.generation",
  "status": "pending",
  "model": "tripo/h3.1-text-to-3d",
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": null },
  "created": 1794182400
}
```

完成后：

```json theme={null}
{
  "id": "5d1c3e0a-...",
  "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" }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": ... },
  "created": 1794182400
}
```

失败时：

```json theme={null}
{
  "id": "5d1c3e0a-...",
  "object": "3d.generation",
  "status": "failed",
  "model": "tripo/h3.1-text-to-3d",
  "error_message": "...",
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": 0 },
  "created": 1794182400
}
```

## 3d.generation 对象

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 生成 id，用于轮询。 |
| `object` | string | 固定为 `3d.generation`。 |
| `status` | string | `pending`、`success` 或 `failed`。 |
| `model` | string | 模型 id。 |
| `data` | array | `success` 时出现。`data[0].url` 为 3D 模型文件，`data[1].url` 为 PNG 预览图（返回时提供）。 |
| `error_message` | string | `failed` 时出现：生成失败的原因。 |
| `usage` | object | 该生成的费用：扣费最终确定之前 `usage.cost` 为 `null`，之后为实际扣费金额（`failed` 时为 `0`）。见 [费用与用量](https://docs.vibetoken.cn/zh/essentials/async-tasks.md#费用与用量)。 |
| `created` | integer | Unix 时间戳，单位为秒。 |

| `status` | 含义 |
| - | - |
| `pending` | 任务已排队或正在生成 |
| `success` | 生成完成；`data[].url` 已填充 |
| `failed` | 生成失败；见 `error_message`。不收费。 |

### 输出文件

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

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

## 幂等性

发送 `Idempotency-Key` 请求头（或在请求体中加入 `client_request_id` 字段）即可安全重试：重复的 id
会返回已有的生成任务，而不是新建并再次扣费。如果在拿到 `id` 之前连接就断开了，可以用该 id 查询任务：

```bash theme={null}
curl "https://vibetoken.cn/v1/3d/generations?client_request_id=0b8f6a2e-4d1c-4f3a-9e57-1c2d3e4f5a6b" \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx"
```

`200` 返回生成对象；`404` 表示请求从未到达，请用同一个 id 重试 POST。完整规则见
[幂等性](https://docs.vibetoken.cn/zh/essentials/idempotency.md)。

## 回调

设置 `callback_url` 后，任务结束时 VibeToken 会把结果 `POST` 到该 URL。`result_urls` 与 `data`
顺序相同：先是模型文件，然后是预览图。

```json theme={null}
{
  "task_id": "5d1c3e0a-7b2f-4c4e-9a51-2f0f8a9b6c13",
  "status": "success",
  "result_urls": [
    "https://media.vibetoken.cn/media/<user>/<gen>/0.glb",
    "https://media.vibetoken.cn/media/<user>/<gen>/1.png"
  ],
  "error_message": null,
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": ... }
}
```

失败的任务会发送 `"status": "fail"`、空的 `result_urls` 以及 `error_message`。`usage` 与轮询返回的对象相同：`usage.cost` 为实际扣费金额，失败时为 `0`。该 URL 必须是公开的
HTTP(S) URL；内部及私有网络地址会返回 `400`。投递细节见
[异步任务 → 回调](https://docs.vibetoken.cn/zh/essentials/async-tasks.md#方案-2-—-回调-url)。

## 错误

| HTTP | 何时出现 |
| - | - |
| `400` | 模型不是 3D 模型；`image_urls` 中的地址无法访问；`callback_url` 不是公开的 HTTP(S) URL；`Idempotency-Key` / `client_request_id` 格式不正确。 |
| `401` | API Key 缺失或无效。 |
| `402` | 余额或该 Key 的额度上限不足以支付所请求的选项。不会生成任何内容。 |
| `404` | 未知的模型 id，或你的账户下没有该 `id` / `client_request_id` 对应的生成任务。 |
| `409` | 该 `Idempotency-Key` / `client_request_id` 已被另一个账户使用。 |
| `422` | 缺少必填字段（文生 3D 的 `prompt`、图生 3D 的 `image_urls`）；取值无效，例如未知的枚举值、超出该模型范围的 `face_limit`；或传入了该模型不支持的选项（见上方选项表），例如对 P1 传 `generate_parts`。 |
| `429` | 触发限流。 |

被受理但之后失败的生成，会在 GET 中返回 `status: "failed"` 及 `error_message`，且不收费。错误响应体见
[错误码](https://docs.vibetoken.cn/zh/essentials/errors.md)。

## 计费

按次计费。价格取决于模型版本、任务类型、是否生成贴图，以及你开启的附加选项（HD 或 8K 贴图、超精细几何、
四边面网格、智能低模、部件拆分）。提交时会按你发送的选项从余额中预留相应金额；成功后按该次生成的实际消耗
扣费，且不会超过预留金额。失败的生成不收费，预留金额会被释放。当前费率请见[定价页](https://vibetoken.cn/pricing)。


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