跳轉到主要內容
3D 生成是異步的。 POST /v1/3d/generations 創建一個 TokenLab 任務；完成狀態響應返回可下載的模型資產，如 model_url，並在可用時返回格式特定的 URL。

​
選擇輸入類型

工作流程必需輸入可選字段備註
文本到 3Dmodel, promptformat, quality, style, seed最適合從描述生成新資產
圖像到 3Dmodel, prompt, image 或 image_urlformat, quality, style, seed只有在所選模型支持圖像輸入時使用
在決定要公開哪些選項之前，查詢模型目錄： 
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 任務

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}。 
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 以便後續對賬。

​
常見錯誤

症狀可能原因修復
創建響應沒有資產 URL3D 生成是異步的輪詢直到終端狀態
請求的格式缺失模型未返回該格式回退到 model_url 或選擇支持該格式的模型
圖像到 3D 被拒絕所選模型僅支持文本或圖像 URL 無法訪問檢查模型合約並驗證 URL
重複資產重試路徑在超時後重新創建了任務在重試之前存儲任務身份

​
API 參考

主題參考
創建 3D創建 3D
獲取 3D 狀態獲取 3D 狀態
獲取任務狀態獲取任務狀態
列出模型列出模型
計費與定價計費與定價