Text to 3D API

Text to 3D API 是一項功能，可讓你將 Meshy 的文字生成 3D 能力整合到自己的應用程式中。在本節中，你將會找到開始使用此 API 所需的全部資訊。

文字生成 3D 採用兩步驟工作流程。首先，建立一個 preview 任務（mode: "preview"）以產生不含 texture 的 3D mesh，以便你評估其形狀。然後，將已完成的 preview 任務的任務 ID 傳遞給 refine 任務（mode: "refine"），以為該 mesh 套用 texture。這兩個步驟共用同一個 endpoint。

POST/openapi/v2/text-to-3d

Create a Text to 3D Preview Task

此 endpoint 用於建立一個 Text to 3D 預覽任務，根據文字 prompt 生成一個無貼圖的 3D 網格（僅幾何體）。這是兩步工作流程的第一步。預覽成功後，使用回傳的任務 ID 建立一個 refine 任務以進行貼圖處理。完整的回應結構請參考 Text to 3D 任務物件。

該任務在背景執行。關於通常所需的時間，請參閱處理時間。

參數

Name
mode
Type
string
必選
Description
建立預覽任務時，此欄位應設定為 "preview"。
Name
prompt
Type
string
必選
Description
描述該 3D 模型是什麼類型的物件。最多 800 個字元。
Name
model_type
Type
string
預設值 standard
Description
指定 3D 網格生成的類型。
可用值：
- standard：常規高細節 3D 網格生成。
- smart-topology：透過 ai_model（meshy-t2 或 meshy-t2.5）選擇 Smart Topology 模型。
- lowpoly（已 deprecated，將於2026 年 10 月 30 日下線）：生成經過最佳化、多邊形更簡潔的 low-poly 網格。我們建議改用 Meshy T2.5：即搭配 meshy-t2.5 的 smart-topology。
選擇 smart-topology 時，should_remesh 和 decimation_mode 將被忽略，且僅接受 topology: triangle。
lowpoly 將於2026 年 10 月 30 日下線。此日期之後，使用 model_type: "lowpoly" 的請求將回傳錯誤。我們建議切換到 Meshy T2.5（model_type: "smart-topology" 搭配 ai_model: "meshy-t2.5"）。選擇 lowpoly 時，ai_model、topology、target_polycount 和 should_remesh 將被忽略。
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 設定面數。
- meshy-t2.5（預設）：為遊戲 asset 提供更銳利的細節。輸出三角形網格，且可透過 target_polycount 設定面數。
Name
geometry_resolution
Type
string
預設值 standard
Description
geometry 生成階段。2k 以 2048³ 執行 Ultra 階段；4k 以 4096³ 執行，以獲得最精細的表面細節。
可用值：standard、2k、4k
僅在 preview mode 下支援。需要 meshy-7.1 或 latest。
Name
ultra_mode
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 geometry_resolution。ultra_mode: true 等同於 geometry_resolution: "2k"。
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：生成以四邊形為主的網格。
- triangle：生成經過抽稀的三角形網格。
Smart Topology 的輸出僅支援三角形。若將 quad 與 ai_model 的 meshy-t2 或 meshy-t2.5 一同請求，將回傳錯誤。
Name
decimation_mode
Type
integer
Description
透過設定面數級別啟用自適應抽稀。設定後，target_polycount 將被忽略。
可用值：
- 1：自適應 —— 超高面數。
- 2：自適應 —— 高面數。
- 3：自適應 —— 中等面數。
- 4：自適應 —— 低面數。

Name
target_polycount
Type
integer
Description
輸出中目標多邊形（面）數量。實際數量可能因 geometry 情況而與目標值有所偏差。
target_polycount 在兩種獨立情況下生效：
- Remesh —— 在 standard 模型上設定 should_remesh: true。網格會被重新生成（抽稀）到大約該數量。範圍為 100 到 300,000，預設 30,000。如果設定了 decimation_mode，則其優先順序更高，target_polycount 將被忽略。
- Smart Topology —— 使用 model_type: smart-topology 且 ai_model 為 meshy-t2 或 meshy-t2.5。模型將直接按該面數生成；不會執行 remesh，也不需要 should_remesh。對於 meshy-t2：範圍為 100 到 15,000，預設 4,000。對於 meshy-t2.5：範圍為 100 到 30,000，預設 15,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
art_style
Type
string
⚠ 已棄用
預設值 realistic
Description
Meshy-6 不支援此參數。使用 Meshy-6 的請求將忽略 art_style，某些組合可能會導致錯誤。可用值：realistic、sculpture。
使用 Sculpture 風格時，enable_pbr 應設定為 false，因為 Sculpture 風格會生成自己的一套 PBR 貼圖。
Name
moderation
Type
boolean
預設值 false
Description
當設定為 true 時，輸入內容將自動被審查是否存在潛在有害內容。如果偵測到有害內容，該任務將不會繼續生成。
將對 prompt 中的文字進行審查。
Name
target_formats
Type
string[]
Description
指定輸出中應包含哪些 3D 檔案格式。僅會生成並回傳所請求的格式，這可以減少任務完成時間。省略時，將包含所有支援的格式。
可用值：glb、obj、fbx、stl、usdz、3mf
省略時，除 3mf 外的所有格式都會生成。只有明確指定時才會包含 3mf。
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
當設定為 true 時，任務會額外渲染一個透明背景（RGBA）版本的預覽圖，並在 GET 回應中以 alpha_thumbnail_url 回傳。現有的 thumbnail_url 欄位保持不變。
Name
auto_size
Type
boolean
預設值 false
Description
當設定為 true 時，服務會使用 AI 視覺自動估算物件的真實世界高度，並相應地調整模型尺寸。除非明確設定 origin_at，否則原點預設設定為 bottom。

僅當 auto_size = true

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

回傳值

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

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：缺少必需參數（例如 prompt、mode）。
- 參數無效：art_style 不是允許的值之一。
- prompt 過長：prompt 超過字元限制。
- low poly 不支援該模型：ai_model: "meshy-6-lite" 不支援 model_type: "lowpoly"。
- Ultra 不支援該模型：geometry_resolution 需要 meshy-7.1 或 latest。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查您的 API 金鑰。
Name
402 - Payment Required
Description
積分不足，無法執行此任務。
Name
429 - Too Many Requests
Description
您已超出速率限制。

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

POST/openapi/v2/text-to-3d

建立 Text to 3D Refine 任務

此 endpoint 用於建立一個 Text to 3D refine 任務，為已完成的預覽 mesh 套用 texture。你必須提供來自成功的預覽任務的 preview_task_id。這是兩步工作流程中的第二步。

該任務會在背景執行。有關通常所需時間，請參閱處理時間。

參數

Name
mode
Type
string
必選
Description
建立 refine 任務時，該欄位應設定為 "refine"。
Name
preview_task_id
Type
string
必選
Description
對應的預覽任務 id。
給定預覽任務的狀態必須為 SUCCEEDED。
Name
enable_pbr
Type
boolean
預設值 false
Description
在基礎顏色之外產生 PBR 貼圖（金屬度、粗糙度、法線）。當 ai_model 為 meshy-6 時還會包含自發光貼圖，但在 texture_resolution: 8k 時除外（不會產生自發光貼圖）。meshy-6-lite、meshy-7.1 和 latest 不會產生自發光貼圖，未設定 ai_model 的 meshy-t2 預覽任務的 refine 同樣不會產生。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎顏色 texture 解析度。可選值為 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。更高的解析度能捕捉更多表面細節。僅適用於 refine mode。
4k 和 8k 需要 ai_model 為 meshy-6、meshy-7.1 或 latest。在 8k 下，不會產生自發光貼圖。
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 編碼 data URI。data URI 範例：data:image/jpeg;base64,<your base64-encoded image data>
如果原始 asset 與上傳圖片之間存在較大的 geometry 差異，圖片 texture 產生可能無法達到最佳效果。指導 texture 產生過程時，texture_image_url 和 texture_prompt 只能使用其中之一。如果同時提供了這兩個參數，則預設使用 texture_prompt 對模型進行 texture 處理。
Name
ai_model
Type
string
預設值 inherited from the preview task
Description
用於 refine 的模型 ID。
可用值：
- meshy-6-lite、meshy-6、meshy-7.1、latest（Meshy 7.1）
- meshy-7（已棄用）：請改用 meshy-7.1。
省略此參數將繼承預覽任務所使用的模型，從而使預覽任務及其 refine 始終使用同一模型。傳入明確值可覆蓋這種繼承關係。
明確傳入的 latest 在此處的解析方式與在預覽任務中完全一致（目前為 Meshy 7.1），因此 latest 預覽任務及其 latest refine 始終落在同一個 texture 模型上。
Name
moderation
Type
boolean
預設值 false
Description
設定為 true 時，系統會自動對輸入內容進行潛在有害內容篩查。如果偵測到有害內容，任務將不會繼續進行產生。
來自 texture_prompt 的文字和來自 texture_image_url 的圖片都會被篩查。
Name
remove_lighting
Type
boolean
預設值 true
Description
從基礎顏色 texture 中移除高光和陰影，產生在自訂光照設定下效果更好的更乾淨的結果。
僅在 ai_model 為 meshy-6 時生效。meshy-7.1 和 latest 會接受該參數但忽略它，未設定 ai_model 的 meshy-t2 預覽任務的 refine 同樣如此。若在 meshy-6-lite 中設定該參數會回傳錯誤。
Name
target_formats
Type
string[]
Description
指定輸出中應包含哪些 3D 檔案格式。僅會產生並回傳所請求的格式，這可以縮短任務完成時間。省略時，將包含所有支援的格式。
可用值：glb、obj、fbx、stl、usdz、3mf
省略時，將產生除 3mf 之外的所有格式。3mf 僅在明確指定時才會包含。
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
設定為 true 時，任務會額外算繪預覽的透明背景（RGBA）版本，並在 GET 回應中以 alpha_thumbnail_url 回傳。現有的 thumbnail_url 欄位保持不變。
Name
auto_size
Type
boolean
預設值 false
Description
設定為 true 時，服務將使用 AI 視覺自動估算物件的真實世界高度，並據此調整模型大小。除非明確設定了 origin_at，否則 origin 預設將為 bottom。

僅當 auto_size = true

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

回傳值

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

失敗模式

Name
400 - Bad Request
Description
請求無法被接受。常見原因：
- 任務 ID 無效：preview_task_id 無效或不存在。
- 任務尚未就緒：該預覽任務尚未成功完成。
- 模型不匹配：預覽任務的 AI 模型與所請求的 refine 模型不相容。
- remove_lighting 不支援該模型：在設定了 ai_model: "meshy-6-lite" 的同時設定了 remove_lighting。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查你的 API key。
Name
402 - Payment Required
Description
執行此任務所需的 credits 不足。
Name
404 - Not Found
Description
未找到 preview_task_id 指定的預覽任務。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

GET/openapi/v2/text-to-3d/:id

取得一個文字生成 3D 任務

透過提供有效的任務 id，此 endpoint 允許你取得一個 Text to 3D 任務。請參閱 The Text to 3D Task Object 查看 Text to 3D 任務物件所包含的屬性。

此 endpoint 對 preview 和 refine 任務皆適用。

參數

Name
id
Type
path
Description
要取得的 Text to 3D 任務的唯一識別碼。

回傳值

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

範例

模式	範例模型
Preview
Refine

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

DELETE/openapi/v2/text-to-3d/:id

刪除 Text to 3D 任務

此 endpoint 將永久刪除一個 Text to 3D 任務，包括所有關聯的模型和資料。此操作不可撤銷。

路徑參數

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

任務狀態

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

已處於 IN_PROGRESS 狀態的任務無法被刪除：請求會被拒絕並返回 409 Conflict，任務將繼續執行。工作行程已經開始處理的任務，其 credits 不可退還，因此在執行過程中刪除它會使您同時損失 credits 和結果。請等待任務到達 SUCCEEDED、FAILED 或 CANCELED 狀態後，再將其刪除。

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

返回值

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

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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/v2/text-to-3d

獲取 Text to 3D 任務列表

此 endpoint 允許你獲取 Text to 3D 任務的列表。

參數

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

回傳值

回傳一個分頁的Text to 3D 任務物件列表。

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

GET/openapi/v2/text-to-3d/:id/stream

串流取得 Text to 3D 任務

此 endpoint 使用 Server-Sent Events（SSE）為 Text to 3D 任務提供即時更新串流。

參數

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

回傳值

以 Server-Sent Events 的形式回傳 Text to 3D 任務物件的串流。

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

Text to 3D 任務物件

Text to 3D 任務物件是 Meshy 用來追蹤從文字輸入生成 3D 模型的工作單元。Text to 3D API 有兩個階段，preview 和 refine。Preview 階段用於生成僅包含 mesh 的 3D 模型，refine 階段則基於 preview 階段的結果生成帶有 texture 的 3D 模型。

該物件具有以下屬性：

屬性

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
Text to 3D 任務的類型。可能的值為 text-to-3d-preview（表示 preview 階段任務）和 text-to-3d-refine（表示 refine 階段任務）。
Name
model_urls
Type
object
Description
Meshy 生成的帶 texture 的 3D 模型檔案的可下載 URL。如果某種格式未生成，則會省略該格式對應的屬性，而不是回傳空字串。
- Name
  glb
  Type
  string
  Description
  GLB 檔案的可下載 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 檔案的可下載 URL。
- Name
  usdz
  Type
  string
  Description
  USDZ 檔案的可下載 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 檔案的可下載 URL。
- Name
  mtl
  Type
  string
  Description
  MTL 檔案的可下載 URL。
- Name
  stl
  Type
  string
  Description
  STL 檔案的可下載 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 檔案的可下載 URL。僅在透過 target_formats 請求了 3mf 時才會出現。
Name
prompt
Type
string
Description
這是用於建立任務時未經修改的 prompt。
Name
negative_prompt
Type
string
⚠ 已棄用
Description
為保持向後相容而保留。此欄位對生成的模型沒有任何功能性影響。
Name
art_style
Type
string
⚠ 已棄用
Description
建立 preview 任務時使用的未經修改的 art_style。Meshy-6 不支援此參數。
Name
texture_richness
Type
string
⚠ 已棄用
Description
為保持向後相容而保留。此欄位對生成的模型沒有任何功能性影響。
Name
texture_prompt
Type
string
Description
在 refine 階段用於指導 texture 生成過程的附加文字 prompt。
Name
ultra_mode
Type
boolean
⚠ 已棄用
Description
已棄用；請改為讀取 geometry_resolution。
Name
geometry_resolution
Type
string
Description
preview 任務執行所使用的 Ultra 檔位（2k 或 4k）；standard 檔位時省略此欄位。
Name
texture_image_url
Type
string
Description
用於指導 texture 生成過程的 texture 圖片的可下載 URL。
Name
thumbnail_url
Type
string
Description
模型檔案縮圖的可下載 URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景（RGBA）版本的可下載 URL。僅在任務建立時設定了 alpha_thumbnail: true 且透明預覽成功渲染時才會出現；否則將省略此欄位。
Name
video_url
Type
string
⚠ 已棄用
Description
預覽影片的可下載 URL。將在未來版本中移除。
Name
progress
Type
integer
Description
任務的進度。如果任務尚未開始，該屬性值為 0。一旦任務成功，該值將變為 100。
Name
started_at
Type
timestamp
Description
任務開始時的時間戳，以毫秒為單位。如果任務尚未開始，該屬性值為 0。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日星期五 GMT 時間中午 12:00:00 表示為 1693569600000。這適用於 Meshy API 中的所有時間戳。
Name
created_at
Type
timestamp
Description
任務建立時的時間戳，以毫秒為單位。
Name
finished_at
Type
timestamp
Description
任務完成時的時間戳，以毫秒為單位。如果任務尚未完成，該屬性值為 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，或任務在未設定 ai_model 的情況下對 meshy-t2 的 preview 進行 refine，則會省略此屬性。
Name
preceding_tasks
Type
integer
Description
排在前面的任務數量。
此欄位的值僅在任務狀態為 PENDING 時才有意義。
Name
task_error
Type
object
Description
失敗任務的錯誤詳情。完整的 task_error 物件參考請參見錯誤。
Name
consumed_credits
Type
integer
Description
該任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現此欄位。對於 FAILED 的任務，該值回傳 0（失敗時積分會被退還）。

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}