TokenLab

媒體指南

3D 生成

從文字或圖片建立可下載的 3D 模型

3D 生成是異步(asynchronous)的。POST /v1/3d/generations 會建立一個 TokenLab 任務;當狀態顯示為已完成時,回應會包含可下載的模型資源,例如 model_url,若適用,還會包含特定格式的 URL。

可下載的 3D 模型檔案會自動保留 30 天的副本,其 URL 為 TokenLab 媒體結果 URL。任務記錄與個別儲存的資源遵循各自的生命週期。請參閱 資料保留。

選擇輸入類型

輸入必填選填欄位備註
文字轉 3D (Text-to-3D)model, promptformat, quality, style, seed最適合根據描述生成新資源
圖片轉 3D (Image-to-3D)model, image_url 或 image;若模型列出則需 promptformat, quality, style, seed僅在所選模型支援圖片輸入時使用

operation 為選填,可設為 text-to-3d 或 image-to-3d。若不填寫,當您傳送 image 或 image_url 時,TokenLab 會使用 image-to-3d,否則使用 text-to-3d。若您傳送此參數,則必須與輸入內容相符。支援 text-to-3d 的模型接受提示詞(prompt);支援 image-to-3d 的模型接受圖片輸入。

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": "tripo-h3.1",
    "prompt": "A stylized low-poly robot mascot with clean topology"
  }'

對於圖片轉 3D,當來源可從網際網路取得時,請使用 https URL。僅在模型詳細資訊列出 image 時才使用內嵌 base64 image;部分模型僅接受 image_url。

輸出格式

  • glb 適用於網頁預覽。
  • fbx 和 obj 在所選模型支援的情況下,適用於 DCC 工作流程。
  • usdz 在模型提供時,適用於 Apple AR 工作流程。
  • 較高的 quality 數值可能會增加等待時間與成本。請向使用者顯示此選項。
  • seed 僅在支援的模型上影響可重複性。

取得完成的模型

使用回傳的 id 或 task_id 呼叫 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。
  • 在頁面重新整理後恢復輪詢(polling),而非建立重複任務。
  • 在建立任務前驗證來源圖片的大小與可存取性。
  • 除非使用者擁有存取權限,否則請勿將生成的資源 URL 放在公開頁面上。
  • 若有 billing_transaction_id,請記錄下來以供後續對帳使用。

常見錯誤

徵狀可能原因修正方式
建立回應中沒有資源 URL3D 生成是異步的持續輪詢直到狀態終止
缺少請求的格式模型未回傳該格式回退至 model_url 或選擇支援該格式的模型
圖片轉 3D 被拒絕所選模型僅支援文字或圖片 URL 無法存取檢查模型詳細資訊並驗證 URL
資源重複重試路徑在逾時後重新建立了任務在重試前儲存任務識別碼

API 參考

主題參考
建立 3D建立 3D
取得 3D 狀態取得 3D 狀態
取得任務狀態取得任務狀態
列出模型列出模型
帳務與定價帳務與定價

本頁內容