文字生成 3D API

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

文字生成 3D 採用兩步驟工作流程。首先，建立一個預覽任務（mode: "preview"）生成不帶貼圖的 3D 網格，以便評估模型形狀。然後，將已完成的預覽任務 ID 傳入精細化任務（mode: "refine"）來為網格添加貼圖。兩個步驟使用同一個介面。

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

建立文字生成3D預覽任務

該介面用於建立文字生成3D預覽任務，根據文字提示生成不帶貼圖的 3D 網格（僅幾何體）。這是兩步驟工作流程的第一步。預覽任務成功後，使用返回的任務 ID 建立精細化任務來添加貼圖。完整回應結構請參考文字生成3D任務物件。

參數

Name
mode
Type
string
必選
Description
建立預覽任務時，該欄位應設置為 "preview"。
Name
prompt
Type
string
必選
Description
描述 3D 模型是什麼類型的物體。最多 600 個字元。
Name
model_type
Type
string
預設值 standard
Description
指定3D網格生成的類型。
可選值：
- standard：常規高細節3D網格生成。
- smart-topology：透過 ai_model 選擇 Smart Topology 模型（meshy-t2）。
- lowpoly（已棄用）：生成優化後多邊形更簡潔的低面數網格。建議改用 smart-topology。
使用 smart-topology 時，should_remesh、decimation_mode 將被忽略，且 topology 僅接受 triangle。
使用 lowpoly 時，ai_model、topology、target_polycount、should_remesh 將被忽略。
Name
ai_model
Type
string
預設值 latest
Description
要使用的模型 ID。可選值取決於 model_type。
標準生成（model_type: standard）：
- meshy-5、meshy-6、meshy-7、latest（Meshy 7）
Smart Topology 生成（model_type: smart-topology）：
- meshy-t2（預設）：Smart Topology 模型——更簡潔的拓撲佈線、原生分件、僅輸出三角面，並可透過 target_polycount 指定目標面數。
Name
ultra_mode
Type
boolean
預設值 false
Description
啟用 Ultra 生成，獲得更高保真度的幾何形狀和更精細的表面細節。生成耗時更長，並額外消耗 5 積分。
僅當 ai_model 為 meshy-7（或 latest）時支援，且僅適用於 preview 模式。
Name
should_remesh
Type
boolean
預設值 false (meshy-6, meshy-7), true (others)
Description
控制是否啟用重建網格階段。為獲得最高質量的模型，我們建議將 should_remesh 設置為 false。

僅當 should_remesh = true

Name
topology
Type
string
預設值 triangle
Description
指定生成模型的拓撲結構。
可選值：
- quad：生成以四邊形為主的網格
- triangle：生成簡化的三角網格
Smart Topology 僅輸出三角面。與 ai_model: meshy-t2 同時指定 quad 會返回錯誤。
Name
decimation_mode
Type
integer
Description
透過設置面數級別啟用自適應減面。設置後，target_polycount 將被忽略。
可選值：
- 1：自適應——超高面數。
- 2：自適應——高面數。
- 3：自適應——中等面數。
- 4：自適應——低面數。

Name
target_polycount
Type
integer
Description
輸出模型的目標面數。實際面數可能會根據幾何複雜度與目標值有所偏差。
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。模型將直接以該面數生成，不執行重建網格，也無需設置 should_remesh。取值範圍 100 到 15,000，預設 4,000。

Name
symmetry_mode
Type
string
⚠ 已棄用
預設值 auto
Description
已棄用。該參數不再影響輸出。
symmetry_mode 欄位控制模型生成過程中的對稱性行為。
可選值：
- off：關閉對稱
- auto：根據輸入幾何自動判斷並應用對稱
- on：強制對稱生成
Name
pose_mode
Type
string
預設值 ""
Description
指定生成模型的姿態模式。
可選值：
- a-pose：生成 A Pose 的模型。
- t-pose：生成 T Pose 的模型。
- ""（空字串）：不應用特定姿態。
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 超出字元數限制。
Name
401 - Unauthorized
Description
認證失敗。請檢查您的 API 密鑰。
Name
402 - Payment Required
Description
積分不足，無法執行此任務。
Name
429 - Too Many Requests
Description
您已超過請求頻率限制。

請求

POST

/openapi/v2/text-to-3d

# 僅使用必要參數的簡單預覽
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"
}'

# 啟用重建網格和 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",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

回應

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

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

建立文字生成3D精細化任務

該介面用於建立文字生成3D精細化任務，為已完成的預覽網格添加貼圖。你需要提供來自已成功預覽任務的 preview_task_id。這是兩步驟工作流程的第二步。

參數

Name
mode
Type
string
必選
Description
建立精細化任務時，該欄位應設置為 "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-7（以及 latest）不會生成自發光貼圖。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎色貼圖的解析度。可選值為 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。解析度越高，捕捉的表面細節越豐富。僅適用於 refine 模式。
4k 和 8k 需要 ai_model 為 meshy-6、meshy-7 或 latest。在 8k 下不會生成自發光貼圖。
Name
hd_texture
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 texture_resolution，等同於 texture_resolution: "4k"。當兩者同時設置時，以 texture_resolution 為准。
Name
texture_prompt
Type
string
Description
提供額外的文本提示以引導貼圖過程。最多 600 個字元。
Name
texture_image_url
Type
string
Description
提供 2D 圖片以引導貼圖過程。目前支援 .jpg、.jpeg 和 .png 格式。
提供圖片有兩種方式：
- 公網可訪問的 URL：可從公網訪問的圖片連結
- Data URI：圖片的 base64 編碼 Data URI。例如：data:image/jpeg;base64;<your base64-encoded image data>
如果原始資產與上傳圖片在幾何上有較大差異，圖像貼圖效果可能不佳。texture_image_url 和 texture_prompt 只能二選一。如果都提供，則默認使用 texture_prompt 進行貼圖。
Name
ai_model
Type
string
預設值 latest
Description
用於優化的模型ID。可選值：meshy-5、meshy-6、meshy-7、latest（Meshy 7）。
此處的 latest 與 preview 任務的 latest 按同一規則解析（當前為 Meshy 7），因此 latest 的 preview 任務與其 latest 的 refine 任務始終落在同一個貼圖模型上。
Name
moderation
Type
boolean
預設值 false
Description
當設置為 true 時，輸入內容將自動進行潛在有害內容篩查。如果檢測到有害內容，任務將不會進入生成階段。
texture_prompt 中的文本和 texture_image_url 中的圖片都將被篩查。
Name
remove_lighting
Type
boolean
預設值 true
Description
移除基礎色貼圖中的高光和陰影，生成更純淨的效果，在自定義光照設置下表現更佳。
僅當 ai_model 為 meshy-6 時生效。在 meshy-7（以及 latest）下該參數會被接受但被忽略。
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
請求不合法。常見原因：
- 任務 ID 無效：preview_task_id 無效或不存在。
- 任務未就緒：預覽任務尚未成功完成。
- 模型不匹配：預覽任務的 AI 模型與請求的精細化模型不相容。
Name
401 - Unauthorized
Description
認證失敗。請檢查您的 API 密鑰。
Name
402 - Payment Required
Description
積分不足，無法執行此任務。
Name
404 - Not Found
Description
未找到 preview_task_id 指定的預覽任務。
Name
429 - Too Many Requests
Description
您已超過請求頻率限制。

請求

POST

/openapi/v2/text-to-3d

# 基本精細化任務
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
}'

# 啟用自動尺寸和 GLB 格式的精細化
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
}'

回應

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

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

取得文字生成3D任務

該介面允許你透過有效的任務 id 取得文字生成3D任務。請參考文字生成3D任務物件檢視任務物件包含的屬性。

該介面同時適用於預覽和精細化任務。

參數

Name
id
Type
path
Description
要取得的文字生成3D任務的唯一識別符。

返回值

回應包含文字生成3D任務物件。詳情請查看文字生成3D任務物件部分。

範例

模式	範例模型
預覽
精細化

請求

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}"

回應

{
  "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

刪除文字轉 3D 任務

此端點可永久刪除文字轉3D任務，包括所有關聯的模型和數據。此操作不可逆。

路徑參數

Name
id
Type
path
Description
要刪除的文字轉3D任務的ID。

返回值

成功則返回 200 OK。

請求

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}"

回應

// 成功則返回 200 Ok。

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

取得文字生成3D任務列表

該介面用於取得文字生成3D任務列表。

參數

Name
page_num
Type
integer
預設值 1
Description
分頁頁碼。
Name
page_size
Type
integer
預設值 10
Description
分頁大小限制。最大允許 50 條。
Name
sort_by
Type
string
Description
排序欄位。
可選值：
- +created_at：按創建時間升序排列。
- -created_at：按創建時間降序排列。

返回值

返回 Text to 3D 任務物件的分頁列表。

請求

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}"

回應

[
  {
    "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

流式取得文字生成3D任務

該介面透過 Server-Sent Events (SSE) 實時流式返回文字生成3D任務的進度更新。

參數

Name
id
Type
path
Description
要流式取得的文字生成3D任務的唯一識別符。

返回值

返回文字生成3D任務物件的 SSE 實時流。

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

請求

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}"

回應流

// 錯誤事件範例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 訊息事件範例，展示任務進度。
// 對於 PENDING 或 IN_PROGRESS 狀態的任務，回應流不會包含所有欄位。
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
}

文字生成3D任務物件

文字生成3D任務物件是 Meshy 用於追蹤從文字輸入生成 3D 模型的工作單元。文字生成3D API 分為兩個階段：preview（預覽）和 refine（精細化）。預覽階段用於生成僅有網格的 3D 模型，精細化階段則基於預覽結果生成帶貼圖的 3D 模型。

該物件包含以下屬性：

屬性

Name
id
Type
string
Description
任務的唯一識別符。雖然我們採用 k-sortable UUID 作為任務 id 的實現細節，但你不應對 id 格式做任何假設。
Name
type
Type
string
Description
文字生成3D任務的類型。返回值為 text-to-3d-preview（預覽階段任務）或 text-to-3d-refine（精細化階段任務）。
Name
model_urls
Type
object
Description
Meshy 生成的帶貼圖 3D 模型文件的可下載連結。如果某種格式未生成，則不會返回該屬性。
- Name
  glb
  Type
  string
  Description
  GLB 檔案的可下載連結。
- Name
  fbx
  Type
  string
  Description
  FBX 檔案的可下載連結。
- Name
  usdz
  Type
  string
  Description
  USDZ 檔案的可下載連結。
- Name
  obj
  Type
  string
  Description
  OBJ 檔案的可下載連結。
- Name
  mtl
  Type
  string
  Description
  MTL 檔案的可下載連結。
- Name
  stl
  Type
  string
  Description
  STL 檔案的可下載連結。
- Name
  3mf
  Type
  string
  Description
  3MF 檔案的可下載連結。僅在透過 target_formats 請求 3mf 時返回。
Name
prompt
Type
string
Description
建立任務時使用的原始 prompt。
Name
negative_prompt
Type
string
⚠ 已棄用
Description
為相容性保留，對生成模型無實際影響。
Name
art_style
Type
string
⚠ 已棄用
Description
建立預覽任務時使用的原始 art_style。Meshy-6 不再支援。
Name
texture_richness
Type
string
⚠ 已棄用
Description
為相容性保留，對生成模型無實際影響。
Name
texture_prompt
Type
string
Description
精細化階段用於引導貼圖過程的額外文本提示。
Name
ultra_mode
Type
boolean
Description
回顯 preview 任務建立時使用的 ultra_mode 值。僅當 meshy-7（或 latest）的 preview 任務顯式設置了 ultra_mode 時才會出現，否則不返回該欄位。
Name
texture_image_url
Type
string
Description
用於引導貼圖過程的圖片下載連結。
Name
thumbnail_url
Type
string
Description
模型文件縮圖的可下載連結。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景（RGBA）版本的可下載 URL。僅當任務建立時設置了 alpha_thumbnail: true 且成功渲染出透明預覽圖時才會返回，否則會省略該欄位。
Name
video_url
Type
string
⚠ 已棄用
Description
預覽影片的可下載連結。將在後續版本移除。
Name
progress
Type
integer
Description
任務進度。如果任務尚未開始，該值為 0。任務成功後為 100。
Name
started_at
Type
timestamp
Description
任務開始時間的時間戳（毫秒）。如果任務尚未開始，該值為 0。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日 12:00:00 GMT 表示為 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
任務生成的貼圖 URL 物件數組。通常只包含一個貼圖 URL 物件。每個貼圖 URL 包含以下屬性：
- Name
  base_color
  Type
  string
  Description
  基礎色貼圖的可下載連結。
- Name
  metallic
  Type
  string
  Description
  金屬度貼圖的可下載連結。
  如果任務建立時 enable_pbr: false，則不會返回該屬性。
- Name
  normal
  Type
  string
  Description
  法線貼圖的可下載連結。
  如果任務建立時 enable_pbr: false，則不會返回該屬性。
- Name
  roughness
  Type
  string
  Description
  粗糙度貼圖的可下載連結。
  如果任務建立時 enable_pbr: false，則不會返回該屬性。
- Name
  emission
  Type
  string
  Description
  自發光貼圖的可下載連結。
  如果任務建立時 enable_pbr: false，或 ai_model 為 meshy-5，則不會返回該屬性。
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（失敗時積分會被退還）。

文字生成3D任務物件範例

{
  "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
}