Text to 3D API

在你自己的應用程式中根據文字提示生成 3D 模型。

文字生成 3D 分兩個步驟進行。首先，建立一個 preview 任務（mode: "preview"）以生成不帶 texture 的 3D mesh，這樣你就可以檢查其形狀。然後，將成功的 preview 任務的任務 ID 傳送給 refine 任務（mode: "refine"），為 mesh 加上 texture。這兩個步驟使用相同的 endpoint。

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

建立 Text to 3D preview 任務

建立一個 Text to 3D preview 任務，根據文字 prompt 生成一個未貼圖的 3D mesh（僅幾何體）。這是兩步工作流程的第一步。preview 成功後，將其任務 ID 傳送到 refine 任務中，為 mesh 新增 texture。參見建立 Text to 3D refine 任務。完整的回應模式請參見 Text to 3D 任務物件。

該任務在背景執行。關於任務通常需要多長時間，請參見處理時間。

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

參數

Name
mode
Type
string
必選
Description
兩步工作流程中的步驟。傳送 preview 以建立一個 preview 任務。
Name
prompt
Type
string
必選
Description
描述要生成的物件的文字，最多 800 個字元。超出長度將回傳 400。
Name
model_type
Type
string
預設值 standard
Description
要生成的 3D mesh 的類型。
可選值：
- standard：高精度 3D mesh
- smart-topology：Smart Topology mesh。透過 ai_model（meshy-t2 或 meshy-t2.5）選擇模型。
使用 smart-topology 時，Meshy 會忽略 should_remesh 和 decimation_mode，並且只接受 topology: triangle。
Name
ai_model
Type
string
預設值 latest
Description
用於生成 3D 模型的 AI 模型。可用值取決於 model_type。
標準模型（model_type: standard）：
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest：Meshy 7.1
- meshy-7（已棄用）：請改為傳送 meshy-7.1
Smart Topology 模型（model_type: smart-topology）：
- meshy-t2：更清晰的 topology，原生分離的部件，三角形輸出，面數透過 target_polycount 設定
- meshy-t2.5（預設）：遊戲 asset 所需的更銳利細節，三角形輸出，面數透過 target_polycount 設定
Name
geometry_resolution
Type
string
預設值 standard
Description
幾何體生成階段。僅適用於 preview 任務。在 refine 中使用此參數將回傳 400。
可選值：
- standard
- 2k：以 2048³ 執行 Ultra 階段
- 4k：以 4096³ 執行 Ultra 階段，以取得更精細的表面細節
2k 需要 meshy-7.1、latest 或已棄用的 meshy-7。4k 需要 meshy-7.1 或 latest。其他模型將回傳 400。
Name
ultra_mode
Type
boolean
⚠ 已棄用
預設值 false
Description
請改為傳送 geometry_resolution。ultra_mode: true 等同於 geometry_resolution: "2k"。
Name
should_remesh
Type
boolean
預設值 true (meshy-6-lite), false (other models)
Description
生成後是否對模型進行 remesh。如需取得最高品質的 3D 模型，請傳送 false。

僅當 should_remesh = true

Name
topology
Type
string
預設值 triangle
Description
重新生成的模型的面類型。
可選值：
- quad：以四邊形為主的 mesh
- triangle：經過簡化的三角形 mesh
Smart Topology 的輸出僅支援三角形。當 ai_model 為 meshy-t2 或 meshy-t2.5 時傳送 quad 將回傳 400。
Name
decimation_mode
Type
integer
Description
按等級調整的自適應面數。設定此參數後，Meshy 會忽略 target_polycount。
可選值：
- 1：ultra
- 2：high
- 3：medium
- 4：low

Name
target_polycount
Type
integer
Description
目標面數。實際結果可能因幾何體不同而與目標值有所差異。該參數在以下兩種獨立情況下生效：
- Remesh：在 standard 模型上設定 should_remesh: true 時。Meshy 會將 mesh 重新生成（簡化）到約為該數值。如果設定了 decimation_mode，Meshy 會使用它並忽略 target_polycount。
- Smart Topology：當 model_type: smart-topology 且 ai_model 為 meshy-t2 或 meshy-t2.5 時。Meshy 會直接按該面數生成模型。此時不會執行 remesh，也不需要 should_remesh。
下表展示了每種情況的取值範圍和預設值：
情況範圍預設值
Remesh 100 至 300000 30000
meshy-t2 100 至 15000 4000
meshy-t2.5 100 至 30000 15000
超出範圍的值將回傳 400。

情況	範圍	預設值
Remesh	`100` 至 `300000`	`30000`
`meshy-t2`	`100` 至 `15000`	`4000`
`meshy-t2.5`	`100` 至 `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ 已棄用
預設值 auto
Description
請勿使用此參數。它不會影響輸出結果。
可選值：
- off：停用 symmetry
- auto：根據輸入的幾何體套用 symmetry
- on：在生成過程中強制使用 symmetry
Name
pose_mode
Type
string
預設值 ""
Description
生成模型的姿態。
可選值：
- 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 會忽略它。
Name
moderation
Type
boolean
預設值 false
Description
在生成之前是否篩查 prompt 中的有害內容。如果 Meshy 偵測到有害內容，請求將回傳 400，且 Meshy 不會建立任務。
Name
target_formats
Type
string[]
Description
要生成的檔案格式。Meshy 僅生成並回傳這些格式，這可以縮短任務時間。如果不設定此參數，Meshy 會生成除 3mf 之外的所有格式，3mf 僅在你要求時才會生成。
可選值：
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
是否同時渲染一張帶透明背景（RGBA）的預覽圖，取得任務時將在 alpha_thumbnail_url 中回傳。thumbnail_url 不會改變。
Name
auto_size
Type
boolean
預設值 false
Description
是否使用 AI 視覺估算物件的真實世界高度，並據此調整模型尺寸。除非設定了 origin_at，否則 Meshy 會將 origin 放置在底部。

僅當 auto_size = true

Name
origin_at
Type
string
預設值 bottom
Description
模型 origin 的放置位置，bottom 或 center。

回傳值

回應的 result 欄位中保存了新建立的 Text to 3D 任務的 ID。

失敗模式

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現的問題。例如：
- 缺少參數：缺少必要的參數，例如 prompt 或 mode。
- Prompt 過長：prompt 超過了字元限制。
- 不支援該模型使用 Ultra：geometry_resolution 為 2k 或 4k，而 ai_model 無法執行該功能。
請修正請求後重新傳送。參見 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來完成此任務，或帳戶已達到積分上限。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在你的訂閱設定中升級方案，然後重試。
Name
403 - Forbidden
Description
內容審核（moderation）攔截了該 prompt 或輸入圖片。請更改輸入內容後重試。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。參見速率限制。

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

建立 Text to 3D refine 任務

建立一個 Text to 3D refine 任務，為已完成的 preview 任務的 mesh 新增 texture。將成功的 preview 任務的 ID 作為 preview_task_id 送出。請參閱建立 Text to 3D preview 任務。這是兩步驟工作流程的第二步。

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

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

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

Response

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

參數

Name
mode
Type
string
必選
Description
兩步驟工作流程中的步驟。送出 refine 以建立 refine 任務。
Name
preview_task_id
Type
string
必選
Description
要新增 texture 的 preview 任務的 ID。該 preview 任務的狀態必須為 SUCCEEDED。
Name
enable_pbr
Type
boolean
預設值 false
Description
是否在產生基礎顏色貼圖的同時也產生 PBR 貼圖（金屬度、粗糙度和法線）。
使用 ai_model 為 meshy-6 時，Meshy 還會產生一張發光貼圖，但在 texture_resolution: 8k 時除外。meshy-6-lite、meshy-7、meshy-7.1 和 latest 不會產生發光貼圖。對未設定 ai_model 的 meshy-t2 或 meshy-t2.5 preview 進行 refine 時也不會產生。使用 ai_model: meshy-n1 時，設為 true 會回傳 400。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎顏色 texture 的解析度。僅適用於 refine 任務。若在 preview 中設定此參數會回傳 400。
可用值：
- 2k：2048×2048
- 4k：4096×4096
- 8k：8192×8192
更高的解析度能捕捉更多表面細節。4k 和 8k 需要 ai_model 為 meshy-6、meshy-7.1 或 latest。使用 meshy-n1 時，設定這些值會回傳 400。在 8k 時，Meshy 不會產生發光貼圖。
Name
hd_texture
Type
boolean
⚠ 已棄用
預設值 false
Description
請改為送出 texture_resolution。hd_texture: true 等同於 texture_resolution: "4k"。如果兩者都送出，Meshy 會使用 texture_resolution。
Name
texture_prompt
Type
string
Description
用於指導 texturing 的文字，最多 800 個字元。超出長度會回傳 400。請送出 texture_prompt 或 texture_image_url，不要同時送出兩者。如果兩者都送出，Meshy 會使用 texture_prompt。使用 ai_model: meshy-n1 時，送出該參數會回傳 400。
Name
texture_image_url
Type
string
Description
用於指導 texturing 的 2D 圖片，可以是公開 URL 或 base64 編碼的 data URI，例如 data:image/jpeg;base64,<your base64-encoded image data>。
圖片必須為 .jpg、.jpeg、.png 或 .webp 檔案，大小不超過 20 MB，每邊至少 32 像素，且像素總數（寬 × 高）不超過 178,956,970。
使用 ai_model: meshy-n1 時，Meshy 會將該圖片作為正面視角進行 texturing。
當圖片中的形狀與模型差異較大時，基於圖片的 texturing 效果可能不佳。
Name
ai_model
Type
string
預設值 inherited from the preview task
Description
用於為 mesh 新增 texture 的 AI 模型。
可用值：
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest：Meshy 7.1
- meshy-n1：僅根據參考圖片產生 2K 基礎顏色 texture。不支援文字 prompt，不產生 PBR 貼圖，也不支援 4K 或 8K。
- meshy-7（已棄用）：請改為送出 meshy-7.1
省略此參數將使用該 preview 任務所用的模型，使 preview 與其 refine 全程使用同一模型。送出某個值可覆蓋該設定。明確指定 latest 時的解析方式與 preview 任務相同，因此使用 latest 的 preview 及其對應的 latest refine 始終使用同一個 texture 模型。
使用 meshy-n1 時，Meshy 會根據 texture_image_url 新增 texture。如果未提供該參數，Meshy 會使用 meshy-7.1 或 latest preview 中儲存的參考圖片。其他任何 preview 若未送出 texture_image_url 都會回傳 400。該 preview 的三角面數最多為 7,999,999。若 preview 已被 remesh 為四邊形網格，則會回傳 400。
Name
moderation
Type
boolean
預設值 false
Description
是否在產生前對 texture_prompt 和 texture_image_url 進行有害內容審查。如果 Meshy 偵測到有害內容，請求會回傳 400，且 Meshy 不會建立任務。
Name
remove_lighting
Type
boolean
預設值 true
Description
是否從基礎顏色 texture 中移除高光和陰影。更乾淨的結果在自訂光照下效果更好。
僅當 ai_model 為 meshy-6 時生效。meshy-7.1 和 latest 接受該參數但會忽略它，對未設定 ai_model 的 meshy-t2 或 meshy-t2.5 preview 進行 refine 時同樣如此。與 meshy-6-lite 一起送出會回傳 400。使用 meshy-n1 時，設為 true 會回傳 400。
Name
target_formats
Type
string[]
Description
要產生的檔案格式。Meshy 僅產生並回傳這些格式，這樣可以縮短任務時間。如果省略此參數，Meshy 會產生除 3mf 之外的所有格式，僅在您請求時才產生 3mf。
可用值：
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
是否同時算繪一張帶透明背景（RGBA）的預覽圖，在取得任務時透過 alpha_thumbnail_url 回傳。thumbnail_url 不會改變。
Name
auto_size
Type
boolean
預設值 false
Description
是否使用 AI 視覺估算物體的真實世界高度並據此調整模型尺寸。除非設定了 origin_at，否則 Meshy 會將 origin 放在底部。

僅當 auto_size = true

Name
origin_at
Type
string
預設值 bottom
Description
模型 origin 的放置位置，bottom 或 center。

回傳值

回應的 result 欄位保存新 Text to 3D 任務的 ID。

失敗情形

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現了什麼問題。例如：
- 無效的任務 ID：preview_task_id 無效，或與您的任何 preview 任務都不相符。
- 任務尚未就緒：該 preview 任務尚未成功完成。
- 模型不相符：該 preview 任務的 AI 模型與所請求的 refine 模型不相容。
- remove_lighting 不受支援的模型：remove_lighting 與 ai_model: "meshy-6-lite" 一起送出。
- Meshy N1 缺少參考圖片：送出了 ai_model: meshy-n1 但未提供 texture_image_url，且該 preview 沒有 Meshy N1 可用的參考圖片。請送出 texture_image_url。
- Meshy N1 的四邊形 preview：對已被 remesh 為四邊形網格的 preview 送出了 ai_model: meshy-n1。請使用其他 ai_model 對其進行 refine。
- Meshy N1 三角面數過多：使用 ai_model: meshy-n1 時，該 preview 的三角面數超過 7,999,999。請使用其他 ai_model 對其進行 refine。
- Meshy N1 不支援的選項：ai_model: meshy-n1 與以下任一選項一起送出：
  - texture_prompt
  - enable_pbr: true
  - texture_resolution 為 4k 或 8k
  - hd_texture: true 且未設定 texture_resolution
  - remove_lighting: true
修正請求後重新送出。請參閱 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查您的 Balance，然後重試。
- 免費方案：建立任務需要付費方案。請在您的訂閱設定中升級您的方案，然後重試。
Name
403 - Forbidden
Description
內容審核攔截了該 prompt 或輸入圖片。請更改輸入內容，然後重試。
Name
429 - Too Many Requests
Description
您已超出速率限制。請稍候後重試。請參閱速率限制。

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

取得 Text to 3D 任務

根據任務 ID 返回對應的 Text to 3D 任務。此介面同時適用於 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": null,

  "consumed_credits": 20
}

參數

Name
id
Type
path
Description
建立回應中返回的任務 ID。

回傳值

Text to 3D 任務物件。

範例

下表展示了每種 mode 下的範例模型。

Mode	範例模型
Preview
Refine

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

刪除一個 Text to 3D 任務

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

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 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/v2/text-to-3d

獲取 Text to 3D 任務列表

返回您的 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": null,

    "consumed_credits": 20
  }
]

參數

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：最新的在前

返回值

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

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

流式取得 Text to 3D 任務

以伺服器傳送事件（SSE）的形式串流推送 Text to 3D 任務的更新。

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.
// These examples are shortened. Each event holds the full task object.
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": null,

"consumed_credits": 20
}

參數

Name
id
Type
path
Description
來自建立回應的任務 ID。

回傳值

以伺服器傳送事件的形式回傳 Text to 3D 任務物件的串流。

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

Text to 3D 任務物件

Text to 3D 任務物件描述了一個根據文字 prompt 生成 3D 模型的任務。它儲存了任務的狀態、progress，以及任務成功後的模型檔案。Text to 3D 有兩個階段，preview 和 refine。preview 任務生成僅含網格的 3D 模型，refine 任務則根據 preview 的結果生成帶貼圖的 3D 模型。

屬性

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": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
任務 ID。請將其視為一個不透明的字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，text-to-3d-preview 表示 preview 任務，text-to-3d-refine 表示 refine 任務。
Name
model_urls
Type
object
Description
生成的 3D 模型的下載 URL，每種檔案格式對應一個。任務未生成的格式不會有對應的鍵，而不是空字串。
- 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
texture_prompt
Type
string
Description
你傳送的、用於指導 refine 階段貼圖的文字 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
你傳送的、用於指導貼圖的圖片的下載 URL。
Name
thumbnail_url
Type
string
Description
3D 模型縮圖的下載 URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景版本（RGBA）的下載 URL。僅當你在建立任務時設定了 alpha_thumbnail: true，並且 Meshy 已算繪出透明預覽圖時才會出現。
Name
progress
Type
integer
Description
任務完成的百分比。任務開始前為 0，成功後為 100。
Name
started_at
Type
timestamp
Description
任務開始的時間，以 Unix 毫秒表示。任務開始前為 0。
Name
created_at
Type
timestamp
Description
任務建立的時間，以 Unix 毫秒表示。
Name
finished_at
Type
timestamp
Description
任務完成的時間，以 Unix 毫秒表示。任務完成前為 0。
Name
status
Type
string
Description
任務狀態，取值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED 或 CANCELED 之一。
Name
texture_urls
Type
array
Description
生成的 texture 貼圖的下載 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-6-lite、meshy-7、meshy-7.1 或 latest。
  
  texture_resolution 為 8k。
  
  該任務是在未設定 ai_model 的情況下，對 meshy-t2 或 meshy-t2.5 的 preview 進行 refine。
Name
preceding_tasks
Type
integer
Description
排在此任務之前的佇列任務數量。該值僅在任務處於 PENDING 狀態時才有意義。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。除非狀態為 FAILED，否則為 null。參見錯誤。
Name
consumed_credits
Type
integer
Description
任務消耗的積分數量。當狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現該欄位。對於 FAILED 的任務，該值為 0，因為 Meshy 會在任務失敗時退還積分。