跳轉到主要內容

快速開始

3D 生成是非同步操作,整個流程分為三步:
最簡範例

介面總覽

Base URL:https://aihubmix.com 認證方式:Bearer Token
與影片介面不同,3D 介面沒有 /content 下載端點和 DELETE 刪除端點:產物透過查詢回應 output[] 中的 content_url 直接下載。

支援的模型

生成類型(generate_type

API 詳細說明

請求標頭

建立 3D 生成任務

請求主體

參數驗證規則
  • promptinput_references 互斥(只能傳其一),僅 generate_type: "Sketch" 允許兩者同傳(草圖 + 文字描述)。
  • input_references 每項中 image_urlimage_base64 必須恰好傳一個
    • image_url 僅支援 http(s) 公開 URL,不支援 data URL(請改用 image_base64);
    • image_base64 解碼後不超過 6MB
  • hy-3d-3.1 不支援 LowPoly 生成類型。
  • 請求主體總大小不超過 10MB
extra_body 使用說明:上游原生參數(如 polygon_type)可放入 extra_body 頂層透傳。以下參數必須使用頂層欄位傳入,出現在 extra_body 中會回傳 400:modelpromptimage_urlimage_base64generate_typeenable_pbrface_countresult_formatmulti_view_images(多視角圖)暫不支援。

回應範例

狀態值說明

查詢任務狀態

輪詢此介面檢查任務是否完成。建議每 10~15 秒 查詢一次。查詢不計費。

回應範例(生成完成)

output[] 欄位說明
content_urlpreview_url臨時連結,會在一段時間後過期,請在任務完成後儘快下載並轉存到自己的儲存空間。任務 ID 自建立起 24 小時內可查詢(expires_at 欄位即查詢截止時刻),過期後查詢將回傳錯誤。臨時連結僅支援 GET 請求,HEAD 請求會回傳 403。

使用範例

完整呼叫範例

計費說明

  • 計費:價格由 模型 × generate_type × 是否啟用 PBR × 是否指定面數 × 是否指定格式 的組合決定,具體價格見模型廣場
  • 計費發生在任務建立成功時;查詢任務狀態與下載產物不計費。
  • 未設定價格的參數組合會在建立時直接回傳 400,不會產生扣費。

FAQ

3D 生成需要多長時間?

通常需要數分鐘,具體取決於模型、生成類型與面數設定。建議以 10~15 秒的間隔輪詢查詢介面。

產物連結和任務的有效期是多久?

  • 任務 ID 自建立起 24 小時內可查詢,回應中的 expires_at 欄位即查詢截止時刻。
  • content_url / preview_url 為上游臨時連結,會在一段時間後過期,請在任務完成後儘快下載轉存

可以同時傳 prompt 和參考圖嗎?

不可以,兩者互斥——唯一例外是 generate_type: "Sketch"(草圖生 3D),允許同時傳入草圖圖片與文字描述。

generate_type 各類型有什麼區別?

任務失敗怎麼處理?

statusfailed 時,回應中的 error 欄位會包含錯誤資訊:
常見失敗原因包括:內容違規、圖片格式不支援、參考圖無法存取等。請根據錯誤資訊調整後重試。
更新時間:2026-07-17