3D
建立 3D 模型
建立 3D 模型生成任務
使用 GET /v1/models?recommended_for=3d 獲取目前的 3D 模型。
從文字或圖片生成 3D 模型。這是一個非同步 API。建立請求的回應會回傳任務識別碼。使用該識別碼輪詢 GET /v1/tasks/{id} 以獲取狀態。
操作類型為 text-to-3d 或 image-to-3d。您可以省略 operation:僅包含提示詞的請求會解析為 text-to-3d,而包含 image 或 image_url 的請求則會解析為 image-to-3d。如果您傳送了 operation,它必須與輸入相符:image-to-3d 需要圖片,而 text-to-3d 則不接受圖片。舊版的 3d-generation 值會回傳 400 unsupported_operation。每個模型僅支援部分操作類型;請查詢 GET /v1/models/{model}。
請求主體
在傳送選填欄位之前,請先查看 GET /v1/models/{model} 以了解該模型接受的參數。此範例僅使用 model 和 prompt。
tripo-h3.1要使用的模型,例如 tripo-h3.1 或 tripo-p1.0。在依賴特定輸入類型或輸出格式之前,請先查詢 GET /v1/models?recommended_for=3d。
text-to-3d 或 image-to-3d。選填;省略時將根據輸入內容推斷。
要生成的 3D 模型文字描述,最多 2000 個字元。模型可以設定更短的上限;請參閱其詳細資訊。針對目前的模型,圖生 3D 請求亦需要 prompt;若缺少此欄位,請求將回傳 400 prompt is required。
用於圖生 3D 生成的 Base64 編碼圖片。
用於圖生 3D 生成的公開圖片 URL。
輸出格式;支援情況與允許的值取決於所選的模型。
品質設定;支援情況與允許的值取決於所選的模型。
模型的風格預設值。
整數種子(seed),當所選模型支援時可用。
終端使用者的唯一識別碼。僅在所選模型接受時才傳送。
部分模型也列出了 n、negative_prompt 和 output_format(format 的別名)。請僅在模型的詳細資訊中列出這些參數時才發送它們。
回應
用於輪詢狀態的任務 ID。
由 adapter 回傳時的非同步任務識別碼別名。
此任務的狀態 URL。使用 id 輪詢 GET /v1/tasks/{id}。
任務狀態:pending、processing、completed 或 failed。
任務建立時的 Unix 時間戳記。
請求
curl -X POST "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 detailed medieval castle with towers"
}'回應
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "tripo-h3.1"
}授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json