TokenLab

3D

建立 3D 模型

建立 3D 模型生成任務

POST
/v1/3d/generations

使用 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。

modelstring預設值: tripo-h3.1

要使用的模型,例如 tripo-h3.1 或 tripo-p1.0。在依賴特定輸入類型或輸出格式之前,請先查詢 GET /v1/models?recommended_for=3d。

operationstring

text-to-3d 或 image-to-3d。選填;省略時將根據輸入內容推斷。

promptstring必填

要生成的 3D 模型文字描述,最多 2000 個字元。模型可以設定更短的上限;請參閱其詳細資訊。針對目前的模型,圖生 3D 請求亦需要 prompt;若缺少此欄位,請求將回傳 400 prompt is required。

imagestring

用於圖生 3D 生成的 Base64 編碼圖片。

image_urlstring

用於圖生 3D 生成的公開圖片 URL。

formatstring

輸出格式;支援情況與允許的值取決於所選的模型。

qualitystring

品質設定;支援情況與允許的值取決於所選的模型。

stylestring

模型的風格預設值。

seedinteger

整數種子(seed),當所選模型支援時可用。

userstring

終端使用者的唯一識別碼。僅在所選模型接受時才傳送。

部分模型也列出了 n、negative_prompt 和 output_format(format 的別名)。請僅在模型的詳細資訊中列出這些參數時才發送它們。

回應

idstring

用於輪詢狀態的任務 ID。

task_idstring

由 adapter 回傳時的非同步任務識別碼別名。

poll_urlstring

此任務的狀態 URL。使用 id 輪詢 GET /v1/tasks/{id}。

statusstring

任務狀態:pending、processing、completed 或 failed。

createdinteger

任務建立時的 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"
  }'

回應

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "tripo-h3.1"
}

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。

長度1 <= length <= 255

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json

application/json