Image to 3D API

影象生成 3D API 是一項功能，讓您能夠將 Meshy 的影象生成 3D 能力整合到您自己的應用程式中。在本節中，您將能找到開始使用此 API 所需的全部資訊。

POST/openapi/v1/image-to-3d

Create an Image to 3D Task

此 endpoint 允許您建立一個新的 Image to 3D 任務。請參閱 The Image to 3D Task Object 以了解 Image to 3D 任務物件包含哪些屬性。

該任務在背景執行。有關通常所需的時間，請參閱 Processing Times。

參數

input_task_id 或 image_url 中只需提供一個，這是必需的。如果兩者都提供，則 input_task_id 具有更高優先順序。

Name
input_task_id
Type
string
必選
Description
一個已完成的影像生成任務的 ID，其輸出將被用作輸入影像。該任務必須屬於以下任務之一：文字生成影像或影像生成影像。此外，它必須是透過 API 執行的，狀態為 SUCCEEDED，並且只生成一張影像。

Name
image_url
Type
string
必選
Description
提供一張影像供 Meshy 用於模型建立。我們目前支援 .jpg、.jpeg、.png 和 .webp 格式。
最大檔案大小：20 MB。
有兩種方式可以提供影像：
- 公開可存取的 URL：一個可從公共網際網路存取的 URL。
- Data URI：影像的 base64 編碼資料 URI。資料 URI 範例：data:image/jpeg;base64,<your base64-encoded image data>。

Name
model_type
Type
string
預設值 standard
Description
指定 3D 網格生成的類型。
可用值：
- standard：常規高精度 3D 網格生成。
- smart-topology：透過 ai_model（meshy-t2）選擇 Smart Topology 模型。
- lowpoly（已 deprecated，將於 2026 年 10 月 30 日 下線）：產生經過最佳化、多邊形更簡潔的 low-poly 網格。我們建議改用 Meshy T2：即配合 meshy-t2 使用的 smart-topology。
選擇 smart-topology 時，topology、should_remesh 和 save_pre_remeshed_model 將被忽略。
lowpoly 將於 2026 年 10 月 30 日 下線。此日期之後，使用 model_type: "lowpoly" 的請求將返回錯誤。我們建議切換到 Meshy T2（model_type: "smart-topology" 配合 ai_model: "meshy-t2"）。選擇 lowpoly 時，ai_model、topology、target_polycount、should_remesh 和 save_pre_remeshed_model 將被忽略。
Name
ai_model
Type
string
預設值 latest
Description
要使用的模型 ID。可用的值取決於 model_type。
標準生成（model_type: standard）：
- meshy-6-lite、meshy-6、meshy-7.1、latest（Meshy 7.1）
- meshy-7（已 deprecated）：請改用 meshy-7.1。
Smart Topology 生成（model_type: smart-topology）：
- meshy-t2（預設）：Smart Topology 模型 —— 更乾淨的 topology、原生分離的部件、三角形輸出，以及可透過 target_polycount 設定的面數。
Name
geometry_resolution
Type
string
預設值 standard
Description
geometry 生成通道。2k 以 2048³ 執行 Ultra 通道；4k 以 4096³ 執行，以獲得最精細的表面細節。
可用值：standard、2k、4k
需要 meshy-7.1 或 latest。
Name
ultra_mode
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 geometry_resolution。ultra_mode: true 等同於 geometry_resolution: "2k"。
Name
should_texture
Type
boolean
預設值 true
Description
決定是否生成 texture。設定為 false 會跳過 texture 階段，提供不帶 texture 的 mesh。

僅當 should_texture = true

Name
enable_pbr
Type
boolean
預設值 false
Description
在基礎顏色之外生成 PBR 貼圖（metallic、roughness、normal）。當 ai_model 為 meshy-6 時還會包含 emission 貼圖，但在 texture_resolution: 8k 時除外。meshy-6-lite、meshy-7.1 和 latest 不會生成 emission 貼圖。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎顏色 texture 的解析度。可選 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。解析度越高，捕捉到的表面細節越多。
ai_model 為 meshy-6-lite 時不支援 4k 和 8k。在 8k 時，不會生成 emission 貼圖。
Name
hd_texture
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 texture_resolution —— 等同於 texture_resolution: "4k"。當兩者都設定時，texture_resolution 優先。
Name
texture_prompt
Type
string
Description
提供一個文字 prompt 來指導 texture 處理過程。最多 800 個字元。
Name
texture_image_url
Type
string
Description
提供一張 2D 影像來指導 texture 處理過程。我們目前支援 .jpg、.jpeg、.png 和 .webp 格式。
最大檔案大小：20 MB。
有兩種方式可以提供影像：
- 公開可存取的 URL：一個可從公共網際網路存取的 URL
- Data URI：影像的 base64 編碼資料 URI。資料 URI 範例：data:image/jpeg;base64,<your base64-encoded image data>
如果原始 asset 與上傳的影像之間存在較大的 geometry 差異，影像紋理處理可能無法達到最佳效果。在指導 texture 處理過程時，texture_image_url 和 texture_prompt 只能使用其中一個。如果兩個參數都提供了，則預設使用 texture_prompt 為模型生成 texture。無論透過文字還是影像進行 texture 處理，每個任務都將花費 10 credits。

Name
should_remesh
Type
boolean
預設值 false (Meshy 6 and Meshy 7 models), true (others)
Description
控制是否啟用 remesh 階段。為獲得最高品質的模型，我們建議將 should_remesh 設定為 false。

僅當 should_remesh = true

Name
topology
Type
string
預設值 triangle
Description
指定生成模型的 topology。
可用值：
- quad：生成以四邊形為主的 mesh。
- triangle：生成經過精簡的三角形 mesh。
Name
decimation_mode
Type
integer
Description
透過設定 polycount 等級來啟用自適應精簡。設定後，target_polycount 將被忽略。
可用值：
- 1：自適應 —— 超高 polycount。
- 2：自適應 —— 高 polycount。
- 3：自適應 —— 中等 polycount。
- 4：自適應 —— 低 polycount。
Name
save_pre_remeshed_model
Type
boolean
預設值 false
Description
設定為 true 時，Meshy 還會在 remesh 階段完成前儲存一個額外的 GLB 檔案。

Name
target_polycount
Type
integer
Description
輸出結果中目標多邊形（面）的數量。實際數量可能會因 geometry 而與目標值有所偏差。
target_polycount 在兩種獨立情況下生效：
- Remesh —— 在 standard 模型上設定 should_remesh: true。mesh 將被 remesh（精簡）到大約這個數量。範圍為 100 到 300,000，預設值為 30,000。如果設定了 decimation_mode，則其優先順序更高，target_polycount 將被忽略。
- Smart Topology —— 配合 model_type: smart-topology 和 ai_model: meshy-t2。模型將直接以該面數生成；不會執行 remesh，也不需要 should_remesh。範圍為 100 到 15,000，預設值為 4,000。

Name
symmetry_mode
Type
string
⚠ 已棄用
預設值 auto
Description
已 deprecated。此參數不再影響輸出。
symmetry_mode 欄位控制模型生成過程中的 symmetry 行為。
有效值為：
- off：停用 symmetry。
- auto：根據輸入的 geometry 自動判定並套用 symmetry。
- on：在生成過程中強制使用 symmetry。
Name
pose_mode
Type
string
預設值 ""
Description
指定生成模型的姿勢 mode。
可用值：
- a-pose：以 A 字形姿勢生成模型。
- t-pose：以 T 字形姿勢生成模型。
- ""（空字串）：不套用特定姿勢。
Name
is_a_t_pose
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 pose_mode。是否以 A/T 字形姿勢生成模型。
Name
surface_mode
Type
string
⚠ 已棄用
Description
不再影響輸出。它曾用於選擇一種現已下線的模型生成方式；請改用 ai_model。
可接受的值為 organic 和 hard；任何其他值將返回 400。
Name
image_enhancement
Type
boolean
預設值 true
Description
最佳化輸入影像以獲得更好的結果。設定為 false 可在不進行任何風格處理的情況下保留輸入影像的原始外觀。
僅當 ai_model 為 meshy-6、meshy-7.1 或 latest 時支援。
Name
remove_lighting
Type
boolean
預設值 true
Description
從基礎顏色 texture 中移除高光和陰影，產生更乾淨的效果，在自訂燈光設定下表現更佳。
僅當 ai_model 為 meshy-6 時支援。
Name
moderation
Type
boolean
預設值 false
Description
設定為 true 時，系統會自動對輸入內容進行潛在有害內容的審查。如果偵測到有害內容，該任務將不會進入生成階段。
將對來自 image_url、texture_image_url 和 texture_prompt 輸入的內容進行審查。
Name
target_formats
Type
string[]
Description
指定輸出中應包含哪些 3D 檔案格式。只會生成並返回所請求的格式，這可以縮短任務完成時間。如果省略，則包含所有支援的格式。
可用值：glb、obj、fbx、stl、usdz、3mf
如果省略，將生成除 3mf 以外的所有格式。只有在明確指定時才會包含 3mf。
Name
auto_size
Type
boolean
預設值 false
Description
設定為 true 時，該服務將使用 AI 視覺自動估算物體的真實世界高度，並相應地調整模型尺寸。除非明確設定了 origin_at，否則 origin 預設為 bottom。
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
設定為 true 時，該任務還會額外算繪一個透明背景（RGBA）版本的預覽圖，並在 GET 回應中以 alpha_thumbnail_url 的形式返回。現有的 thumbnail_url 欄位保持不變。
Name
multi_view_thumbnails
Type
boolean
預設值 false
Description
設定為 true 時，該任務還會額外算繪四個基本視角的縮圖（正面、右側、背面、左側），並在 GET 回應中以 thumbnail_urls 的形式返回。現有的 thumbnail_url 欄位保持不變，仍指向正面視圖，因此不會影響現有客戶端。
會使任務延遲增加約 3 秒。

僅當 auto_size = true

Name
origin_at
Type
string
預設值 bottom
Description
啟用 auto_size 時 origin 的位置。
可用值：bottom、center。

返回值

回應的 result 屬性包含新建立的 Image to 3D 任務的 id。

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：必須提供 image_url 或 input_task_id 其中之一。
- 輸入任務無效：input_task_id 必須指向一個狀態為 SUCCEEDED 且只生成一張影像的文字生成影像或影像生成影像任務。
- 影像格式無效：提供的 image_url 格式不受支援（.jpg、.jpeg、.png、.webp）。
- URL 無法存取：無法下載 image_url（404 或 timeout）。
- 影像過大：image_url 或 texture_image_url 的影像超過 20 MB。
- Data URI 無效：base64 字串格式錯誤。
- 參數組合無效：enable_pbr 僅在 should_texture 為 true 時支援。
- 不支援 low poly 的模型：ai_model: "meshy-6-lite" 不支援 model_type: "lowpoly"。
- 不支援 Ultra 的模型：geometry_resolution 需要 meshy-7.1 或 latest。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查您的 API key。
Name
402 - Payment Required
Description
執行此任務所需的 credits 不足。
Name
429 - Too Many Requests
Description
您已超出速率限制。

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-3d/:id

檢索 Image to 3D 任務

此 endpoint 允許你根據有效的任務 id 檢索 Image to 3D 任務。請參閱 The Image to 3D Task Object 查看 Image to 3D 任務物件中包含哪些屬性。

參數

Name
id
Type
path
Description
要檢索的 Image to 3D 任務的唯一標識符。

回傳值

回應中包含 Image to 3D 任務物件。詳情請查看 The Image to 3D Task Object 部分。

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

刪除 Image to 3D 任務

此端點會永久刪除一個 Image to 3D 任務，包括所有相關的模型與資料。此操作無法復原。

路徑參數

Name
id
Type
path
Description
要刪除的 Image to 3D 任務的 ID。

任務狀態

仍處於 PENDING 狀態的任務會被刪除，並且建立時消耗的積分會被退還。

已經處於 IN_PROGRESS 狀態的任務無法刪除：該請求會被拒絕，並回傳 409 Conflict，任務會繼續執行。工作節點已經開始處理的任務所消耗的積分不可退還，因此在執行過程中刪除它會讓你同時損失積分和結果。請等待其變為 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務將被刪除，且不會退還積分。

回傳值

成功時回傳 200 OK，當任務處於 IN_PROGRESS 狀態時回傳 409 Conflict。

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/image-to-3d

列出 Image to 3D 任務

此 endpoint 允許您檢索 Image to 3D 任務列表。

參數

可選屬性

Name
page_num
Type
integer
Description
用於分頁的頁碼。起始值及預設值為 1。
Name
page_size
Type
integer
Description
每頁數量限制。預設值為 10 項。最大允許值為 100 項。
Name
sort_by
Type
string
Description
排序所依據的欄位。可選值：
- +created_at：依建立時間升冪排序。
- -created_at：依建立時間降冪排序。

回傳值

回傳一個分頁列表，包含 Image to 3D 任務物件。

Request

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

流式取得 Image to 3D 任務

此端點使用 Server-Sent Events（SSE）為 Image to 3D 任務流式推送即時更新。

參數

Name
id
Type
path
Description
要進行流式傳輸的 Image to 3D 任務的唯一識別碼。

回傳值

以 Server-Sent Events 的形式回傳 Image to 3D 任務物件的資料流。

對於 PENDING 或 IN_PROGRESS 狀態的任務，回應流中只會包含必要的 progress 和 status 欄位。

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

影象生成 3D 任務物件

影象生成 3D 任務物件是 Meshy 用於追蹤從圖像輸入生成 3D 模型的工作單元。該物件具有以下屬性：

屬性

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節中使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
影象生成 3D 任務的類型。該值為 image-to-3d。
Name
model_urls
Type
object
Description
Meshy 生成的帶紋理 3D 模型檔案的可下載 URL。如果某個格式未生成，該格式對應的屬性將被省略，而不是回傳空字串。
- Name
  glb
  Type
  string
  Description
  GLB 檔案的可下載 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 檔案的可下載 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 檔案的可下載 URL。
- Name
  usdz
  Type
  string
  Description
  USDZ 檔案的可下載 URL。
- Name
  mtl
  Type
  string
  Description
  MTL 檔案的可下載 URL，當存在 texture 時會隨 OBJ 匯出一起回傳。
- Name
  stl
  Type
  string
  Description
  STL 檔案的可下載 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 檔案的可下載 URL。僅當透過 target_formats 請求了 3mf 時才會出現。
- Name
  pre_remeshed_glb
  Type
  string
  Description
  remesh 之前原始 GLB 輸出的可下載 URL。
  僅當任務建立時同時設定了 should_remesh: true 和 save_pre_remeshed_model: true 時才可用。
Name
thumbnail_url
Type
string
Description
模型檔案縮圖的可下載 URL。存在時等同於 thumbnail_urls.front，保留此欄位是為了向後相容。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景（RGBA）版本的可下載 URL。僅當任務建立時設定了 alpha_thumbnail: true 且透明預覽成功渲染時才會出現；否則該欄位將被省略。
Name
thumbnail_urls
Type
object
Description
所生成 3D 模型的四個基本視角 thumbnail 的可下載 URL。每個值都是一個指向 512×512 PNG 圖像的簽名 URL，該圖像使用與 thumbnail_url 相同的材質和光照渲染。適用於在批次處理流程中從多個角度預覽模型，而無需下載 GLB。
僅當任務建立時設定了 multi_view_thumbnails: true 且已達到 SUCCEEDED 狀態時才會出現。較舊的任務以及未啟用該選項建立的任務不會包含此欄位。
- Name
  front
  Type
  string
  Description
  正視圖，繞垂直軸旋轉 0°（與 thumbnail_url 一致）。
- Name
  right
  Type
  string
  Description
  右視圖，旋轉 90°。
- Name
  back
  Type
  string
  Description
  後視圖，旋轉 180°。
- Name
  left
  Type
  string
  Description
  左視圖，旋轉 270°。
Name
texture_prompt
Type
string
Description
用於指導 texture 處理過程的文字 prompt。
Name
texture_image_url
Type
string
Description
用於指導 texture 處理過程的 texture 圖像的可下載 URL。
Name
ultra_mode
Type
boolean
⚠ 已棄用
Description
已 deprecated；請改為讀取 geometry_resolution。
Name
geometry_resolution
Type
string
Description
任務執行所使用的 Ultra 檔位（2k 或 4k）；standard 時省略。
Name
progress
Type
integer
Description
任務的 progress。如果任務尚未開始，此屬性為 0。任務成功後，此值將變為 100。
Name
started_at
Type
timestamp
Description
任務開始時的 timestamp，以毫秒為單位。如果任務尚未開始，此屬性為 0。
timestamp 表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日星期五格林威治標準時間中午 12:00:00 表示為 1693569600000。這適用於 Meshy API 中的所有 timestamp。
Name
created_at
Type
timestamp
Description
任務建立時的 timestamp，以毫秒為單位。
Name
expires_at
Type
timestamp
Description
任務結果過期時的 timestamp，以毫秒為單位。
Name
finished_at
Type
timestamp
Description
任務完成時的 timestamp，以毫秒為單位。如果任務尚未完成，此屬性為 0。
Name
status
Type
string
Description
任務的狀態。可能的值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
texture_urls
Type
array
Description
任務生成的 texture URL 物件陣列。通常只包含一個 texture URL 物件。每個 texture URL 具有以下屬性：
- Name
  base_color
  Type
  string
  Description
  基礎顏色貼圖圖像的可下載 URL。
- Name
  metallic
  Type
  string
  Description
  金屬度貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  normal
  Type
  string
  Description
  法線貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  roughness
  Type
  string
  Description
  粗糙度貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  emission
  Type
  string
  Description
  自發光貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，或 ai_model 為 meshy-6-lite、meshy-7.1 或 latest，此屬性將被省略。
Name
preceding_tasks
Type
integer
Description
排在前面的任務數量。
該欄位的值僅在任務狀態為 PENDING 時才有意義。
Name
task_error
Type
object
Description
失敗任務的錯誤詳情。完整的 task_error 物件參考請參見錯誤。
Name
consumed_credits
Type
integer
Description
此任務消耗的 credits 數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現該欄位。對於 FAILED 任務回傳 0（失敗時 credits 會被退回）。

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}