lowpoly 將於 2026年10月30日 下線。 請在這些日期前切換模型，以免請求出錯。 查看所有棄用資訊

Convert API

將 3D 模型從 Meshy 任務或模型檔案格式轉換為其他檔案格式。

POST/openapi/v1/convert

創建 Convert 任務

創建一個 Convert 任務。該任務在背景執行。關於任務通常需要多長時間，請參閱處理時間。

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

參數

  • Name
    input_task_id
    Type
    string
    必選
    Description

    除非發送 model_url，否則此項為必填。該參數是生成了 3D 模型的任務的 ID，例如 Text to 3D、Image to 3D、Remesh、尺寸調整或 Retexture 任務。該任務必須來自 API，且狀態為 SUCCEEDED。

  • Name
    model_url
    Type
    string
    必選
    Description

    除非發送 input_task_id，否則此項為必填。要轉換的模型，以公開 URL 或 Data URI 的形式提供。如果兩者都發送，Meshy 會使用 input_task_id。

    該模型必須是 GLB、glTF、OBJ、FBX 或 STL 檔案，若來自 http 或 https URL 則最大為 400 MB，若為 Data URI 則最大為 100 MB。對於 Data URI，請使用 MIME type application/octet-stream。

    超過 100 MB 的檔案還必須遵循以下規則：

    • GLB、glTF、FBX 或 OBJ 檔案最多可包含 10,000,000 個面。Meshy 將面計為三角形，因此一個四邊形計為 2 個面，被多次繪製的 mesh 每個副本計為一次。
    • FBX 檔案必須是 7.1 或更高版本的二進位 FBX。
    • GLB 或 glTF 檔案不得使用 Draco 壓縮。
  • Name
    target_formats
    Type
    string[]
    必選
    Description

    要生成的檔案格式。至少列出一個。列表缺失或為空將返回 400。

    可用值：

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

返回值

回應中的 result 欄位保存新 Convert 任務的 ID。

失敗模式

  • Name
    400 - Bad Request
    Description

    該請求無法執行。錯誤訊息會說明發現了什麼問題。例如：

    • 缺少參數：既未發送 model_url，也未發送 input_task_id。
    • 缺少 target_formats：target_formats 缺失或未列出任何格式。
    • 輸入任務無效：input_task_id 不是帶有模型檔案的成功 API 任務。
    • 模型格式無效：model_url 檔案的副檔名不受支援。
    • URL 無法存取：Meshy 無法下載 model_url 檔案。
    • 模型檔案過大：model_url 檔案來自 http 或 https URL 時超過 400 MB，或作為 Data URI 時超過 100 MB。
    • 面數過多：model_url 檔案超過 100 MB，且面數超過 10,000,000。請減少面數後重新發送檔案。
    • ASCII FBX 超過 100 MB：model_url 檔案是超過 100 MB 的 ASCII FBX。請將其以二進位 FBX 或 GLB 格式發送。
    • 模型檔案無法讀取：model_url 檔案超過 100 MB，且 Meshy 無法讀取其檔案頭。例如，它是經過 Draco 壓縮的 GLB 或 glTF，或是早於 7.1 版本的二進位 FBX。
    • 模型檔案頭過於複雜：model_url 檔案超過 100 MB，其檔案頭中包含過多需要檢查的 mesh、節點或記錄。請減少檔案中的物件數量後重新發送。

    請修正請求後重新發送。參閱錯誤。

  • Name
    401 - Unauthorized
    Description

    API 金鑰缺失或無效。請檢查 Authorization 請求標頭。

  • Name
    402 - Payment Required
    Description

    例如：

    • 積分不足：帳戶沒有足夠的積分來完成此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
    • 免費方案：創建任務需要付費方案。請在你的訂閱設定中升級方案，然後重試。
  • Name
    403 - Forbidden
    Description

    input_task_id 是浮雕模型，此端點無法轉換該類型。錯誤訊息為 This model type does not support this operation。請發送其他模型。

  • Name
    404 - Not Found
    Description

    input_task_id 與你的任何任務都不符合。請檢查任務 ID，然後重新發送請求。

  • Name
    429 - Too Many Requests
    Description

    你已超出速率限制。請等待後重試。參閱速率限制。

GET/openapi/v1/convert/:id

取得 Convert 任務

根據 ID 回傳一個 Convert 任務。

Request

GET
/openapi/v1/convert/:id
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

參數

  • Name
    id
    Type
    path
    Description

    來自建立回應的任務 ID。

回傳值

Convert 任務物件。

DELETE/openapi/v1/convert/:id

刪除 Convert 任務

永久刪除一個 Convert 任務，包括其模型和資料。刪除操作無法復原。

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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 keeps 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."
}

路徑參數

  • Name
    id
    Type
    path
    Description

    要刪除的任務的 ID。

任務狀態

刪除一個 PENDING 任務會退還你在建立該任務時所使用的積分。

IN_PROGRESS 任務無法被刪除。該請求會回傳 409 Conflict， 並且任務會繼續執行。Meshy 不會為已經開始的任務退款， 因此刪除它既會損失積分，也會損失結果。請等待它 變為 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

刪除處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務 不會退還其積分。

回傳值

任務被刪除時回傳 200 OK；當任務處於 IN_PROGRESS 狀態時回傳 409 Conflict。

GET/openapi/v1/convert

取得 Convert 任務列表

回傳你的 Convert 任務列表。

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

參數

  • Name
    page_num
    Type
    integer
    預設值 1
    Description

    要回傳的頁碼，最大為 255。更大的值將回傳 400。

  • Name
    page_size
    Type
    integer
    預設值 10
    Description

    每頁的任務數量，最大為 100。

  • Name
    sort_by
    Type
    string
    Description

    排序順序。

    可用值：

    • +created_at：從最早開始
    • -created_at：從最新開始

回傳值

一個分頁的 Convert 任務物件列表。

GET/openapi/v1/convert/:id/stream

以串流方式取得 Convert 任務

以伺服器發送事件（SSE）的形式，串流取得 Convert 任務的更新。

Request

GET
/openapi/v1/convert/:id/stream
curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

參數

  • Name
    id
    Type
    path
    Description

    來自建立回應的任務 ID。

回傳值

以伺服器發送事件形式回傳 Convert 任務物件 的資料串流。

每個事件都包含完整的任務物件，其結構與 Get 端點回傳的內容相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位尚無值。

Convert 任務物件

Convert 任務物件描述對 3D 模型的一次格式轉換。它儲存了任務的狀態、progress，以及任務成功時的模型檔案。

屬性

  • Name
    id
    Type
    string
    Description

    任務 ID。請將其視為不透明字串，不要依賴其格式。

  • Name
    type
    Type
    string
    Description

    任務類型，始終為 convert。

  • Name
    model_urls
    Type
    object
    Description

    轉換後模型的下載連結，每種檔案格式對應一個。只有 target_formats 中的格式才有對應的連結。未請求的格式沒有對應的鍵，而不是空字串。

  • Name
    progress
    Type
    integer
    Description

    任務完成的百分比。在任務開始前為 0，成功後為 100。

  • Name
    status
    Type
    string
    Description

    任務狀態，為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED 或 CANCELED 之一。

  • Name
    preceding_tasks
    Type
    integer
    Description

    佇列中排在此任務之前的任務數量。該值僅在任務處於 PENDING 狀態時才有意義。

  • Name
    created_at
    Type
    timestamp
    Description

    任務建立的時間，以 Unix 毫秒數表示。

  • Name
    started_at
    Type
    timestamp
    Description

    任務開始的時間，以 Unix 毫秒數表示。在任務開始前為 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    任務結束的時間，以 Unix 毫秒數表示。在任務結束前為 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    任務下載連結過期的時間，以 Unix 毫秒數表示。在任務結束前為 0。

  • Name
    texture_urls
    Type
    array
    Description

    任務成功時，模型的 texture 貼圖下載連結：一個物件陣列，每個 texture 集合對應一個物件。每個物件都有一個 base_color 連結，還可以有 metallic、roughness、normal、emission 和 metallic_roughness 連結。在任務成功前為 null；當模型沒有 texture 貼圖時為空陣列。

  • Name
    task_error
    Type
    object
    Description

    任務失敗時的錯誤詳情。參見 錯誤。

  • Name
    consumed_credits
    Type
    integer
    Description

    任務消耗的積分數量，Convert 任務為 1。對於 FAILED 任務，該值為 0。