> ## 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-Hant/api-reference/3d/create-3d)           |
| 獲取 3D 狀態 | [獲取 3D 狀態](/zh-Hant/api-reference/3d/get-3d-status)    |
| 獲取任務狀態   | [獲取任務狀態](/zh-Hant/api-reference/tasks/get-task-status) |
| 列出模型     | [列出模型](/zh-Hant/api-reference/models/list-models)      |
| 計費與定價    | [計費與定價](/zh-Hant/guides/billing)                       |