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

# 3D生成

> 创建文本到3D或图像到3D任务，轮询已完成的资产，并处理可下载的模型文件。

3D生成是异步的。 `POST /v1/3d/generations` 创建一个TokenLab任务；完成状态响应返回可下载的模型资产，如 `model_url`，并在可用时返回特定格式的URL。

## 选择输入类型

| 工作流   | 必需输入                                     | 可选字段                                 | 备注              |
| ----- | ---------------------------------------- | ------------------------------------ | --------------- |
| 文本到3D | `model`, `prompt`                        | `format`, `quality`, `style`, `seed` | 最适合从描述生成新资产     |
| 图像到3D | `model`, `prompt`, `image` 或 `image_url` | `format`, `quality`, `style`, `seed` | 仅在所选模型支持图像输入时使用 |

在决定要公开哪些选项之前，请查询模型目录：

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
```

不要假设每个3D模型都支持两种输入类型或每种输出格式。在发送 `image`, `image_url`, `format`, `quality`, `style` 或 `seed` 之前，请检查所选模型契约。

## 创建3D任务

```bash theme={null}
curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "一个风格化的低多边形机器人吉祥物，具有干净的拓扑结构",
    "format": "glb",
    "quality": "standard"
  }'
```

对于图像到3D，尽可能使用公共 `image_url`。仅在您的客户端故意发送私有媒体且您的后端准备好处理更大的请求体时，才使用内联/base64 `image`。

## 输出格式选择

* `glb` 通常是网页预览的最安全默认值。
* `fbx` 和 `obj` 在所选模型支持时对DCC管道很有用。
* `usdz` 在模型公开时对Apple AR工作流很有用。
* 较高的 `quality` 值可能会增加延迟和成本。将其作为明确的用户选择公开，而不是隐藏的默认值。
* `seed` 仅在模型尊重它时对可重复性有用。

## 轮询和存储资产

首先使用返回的 `poll_url`。如果您的客户端需要固定路由，请使用 `GET /v1/tasks/{id}`。

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

完成的任务返回 `model_url`，并可能包括 `glb_url`, `fbx_url`, `obj_url` 或 `usdz_url`。如果用户需要重复访问、版本历史或长期下载，请在您自己的产品中下载或缓存所选资产。

## 生产检查清单

* 持久化 `task_id`, `poll_url`, 模型，请求格式和您自己的资产记录ID。
* 在页面刷新后恢复轮询，而不是创建重复任务。
* 在创建任务之前验证源图像的大小和可达性。
* 除非用户有权限访问资产，否则请将生成的资产URL排除在公共页面之外。
* 记录 `billing_transaction_id`（如果存在）以便后续对账。

## 常见错误

| 症状          | 可能原因               | 修复                          |
| ----------- | ------------------ | --------------------------- |
| 创建响应没有资产URL | 3D生成是异步的           | 轮询直到终端状态                    |
| 请求的格式缺失     | 模型未返回该格式           | 回退到 `model_url` 或选择支持该格式的模型 |
| 图像到3D被拒绝    | 所选模型仅支持文本或图像URL不可达 | 检查模型契约并验证URL                |
| 重复资产        | 重试路径在超时后重新创建了任务    | 在重试之前存储任务身份                 |

## API参考

| 主题     | 参考                                                |
| ------ | ------------------------------------------------- |
| 创建3D   | [创建3D](/zh/api-reference/3d/create-3d)            |
| 获取3D状态 | [获取3D状态](/zh/api-reference/3d/get-3d-status)      |
| 获取任务状态 | [获取任务状态](/zh/api-reference/tasks/get-task-status) |
| 列出模型   | [列出模型](/zh/api-reference/models/list-models)      |
| 计费与定价  | [计费与定价](/zh/guides/billing)                       |