媒體指南
3D 生成
從文字或圖片建立可下載的 3D 模型
3D 生成是異步(asynchronous)的。POST /v1/3d/generations 會建立一個 TokenLab 任務;當狀態顯示為已完成時,回應會包含可下載的模型資源,例如 model_url,若適用,還會包含特定格式的 URL。
可下載的 3D 模型檔案會自動保留 30 天的副本,其 URL 為 TokenLab 媒體結果 URL。任務記錄與個別儲存的資源遵循各自的生命週期。請參閱 資料保留。
選擇輸入類型
| 輸入 | 必填 | 選填欄位 | 備註 |
|---|---|---|---|
| 文字轉 3D (Text-to-3D) | model, prompt | format, quality, style, seed | 最適合根據描述生成新資源 |
| 圖片轉 3D (Image-to-3D) | model, image_url 或 image;若模型列出則需 prompt | format, 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,請記錄下來以供後續對帳使用。
常見錯誤
| 徵狀 | 可能原因 | 修正方式 |
|---|---|---|
| 建立回應中沒有資源 URL | 3D 生成是異步的 | 持續輪詢直到狀態終止 |
| 缺少請求的格式 | 模型未回傳該格式 | 回退至 model_url 或選擇支援該格式的模型 |
| 圖片轉 3D 被拒絕 | 所選模型僅支援文字或圖片 URL 無法存取 | 檢查模型詳細資訊並驗證 URL |
| 資源重複 | 重試路徑在逾時後重新建立了任務 | 在重試前儲存任務識別碼 |