Multi-Image to 3D API

透過同一物體從不同角度拍攝的一到四張圖片生成 3D 模型。

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

建立 Multi-Image to 3D 任務

建立一個 Multi-Image to 3D 任務。該任務在背景執行。關於任務通常需要多長時間，參見處理時間。關於任務包含哪些欄位，參見Multi-Image to 3D 任務物件。

Request

POST

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

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

# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

參數

Name
input_task_id
Type
string
必選
Description
除非你傳送 image_urls，否則此項為必填。一個 Text to Image 或 Image to Image 任務（包括多視角任務）的 ID。Meshy 會使用該任務的一到四張圖片作為輸入。該任務必須是你透過 API 建立、且狀態為 SUCCEEDED 的任務。

Name
image_urls
Type
array
必選
Description
除非你傳送 input_task_id，否則此項為必填。一到四張圖片，每張圖片可以是可公開存取的 URL，也可以是 Data URI，例如 data:image/jpeg;base64,<your base64-encoded image data>。如果兩者都傳送，Meshy 會使用 input_task_id。
每張圖片必須是 .jpg、.jpeg、.png 或 .webp 格式的檔案，大小不超過 20 MB，每邊至少 32 像素，且像素總數（寬 × 高）不超過 178,956,970。超過四張圖片會傳回 400。
為獲得最佳效果，這些圖片應呈現同一物體的不同角度。使用 meshy-7.1 或 latest 時，Meshy 會將第一張圖片作為正視圖，其餘圖片的順序無關緊要。

Name
ai_model
Type
string
預設值 latest
Description
生成 3D 模型所使用的 AI 模型。
可選值：
- latest：Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7：已 deprecated，請改為傳送 meshy-7.1
Name
geometry_resolution
Type
string
預設值 standard
Description
生成的 geometry 細節程度。
可選值：
- standard
- 2k：以 2048³ 執行 Ultra 處理流程。需要 meshy-7.1、latest 或已 deprecated 的 meshy-7。
Name
ultra_mode
Type
boolean
⚠ 已棄用
預設值 false
Description
請改為傳送 geometry_resolution。ultra_mode: true 等同於 geometry_resolution: "2k"。
Name
should_texture
Type
boolean
預設值 true
Description
是否生成 texture。true 傳回帶 texture 的模型，false 則跳過貼圖步驟，傳回不帶 texture 的 mesh。

僅當 should_texture = true

Name
texture_model
Type
string
預設值 depends on ai_model
Description
在同一任務中根據多個視角為 3D 模型貼圖的 AI 模型。留空則使用你所選 ai_model 的預設貼圖模型。它不會改變積分花費。
可選值：
- meshy-7：Meshy 7，帶 PBR 貼圖及最高 8K 的 texture
- meshy-n1：Meshy N1，僅根據參考圖片生成 2K 基礎色 texture
每種 ai_model 都支援這兩種貼圖模型。使用 meshy-6 或 meshy-6-lite 發起帶 texture 的請求會傳回 400，所選貼圖模型不支援的選項同樣會傳回 400。當 should_texture: false 時，Meshy 會忽略 texture_model，但未知值仍會傳回 400。
使用 meshy-n1 時，Meshy 會根據 texture_image_urls 或 texture_image_url 進行貼圖；若兩者都未傳送，則使用輸入圖片進行貼圖，其中第一張圖片為正視圖。超過 7,999,999 個三角面的生成模型會導致任務失敗，Meshy 會退還相應積分。
關於各貼圖模型的作用及如何選擇，參見模型。
Name
enable_pbr
Type
boolean
預設值 false
Description
是否在基礎色之外額外生成金屬度、粗糙度和法線貼圖。Meshy 6 貼圖模型還會生成自發光貼圖，但在 texture_resolution: 8k 時除外。使用 texture_model: meshy-n1 時，設為 true 會傳回 400。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎色 texture 的尺寸。尺寸越大，捕捉到的表面細節越多。
可選值：
- 2k：2048×2048
- 4k：4096×4096
- 8k：8192×8192
4k 和 8k 需要 Meshy 7 或 Meshy 6 貼圖模型，使用其他模型會傳回 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
用於指導 texture 的文字，最多 800 個字元。超長文字會傳回 400。使用 texture_model: meshy-n1 時，傳送此參數會傳回 400。
Name
texture_image_url
Type
string
Description
一張用於指導 texture 的 2D 圖片，可以是可公開存取的 URL，也可以是 Data URI，例如 data:image/jpeg;base64,<your base64-encoded image data>。該圖片必須是 .jpg、.jpeg、.png 或 .webp 格式的檔案，大小不超過 20 MB，每邊至少 32 像素，且像素總數（寬 × 高）不超過 178,956,970。
如果同時傳送 texture_image_url 和 texture_prompt，Meshy 會使用 texture_prompt。使用 texture_model: meshy-n1 時，Meshy 會將此圖片作為正視圖進行貼圖。
當圖片中的形狀與 3D 模型差異較大時，貼圖效果可能不理想。
Name
texture_image_urls
Type
string[]
Description
一到四張不同視角的物體圖片，用於指導 texture。Meshy 會將第一張圖片作為正視圖，其餘視角（左、背、右）的順序無關緊要。
每張圖片須遵循與 texture_image_url 相同的規則：可以是可公開存取的 URL，也可以是 Data URI，格式為 .jpg、.jpeg、.png 或 .webp，大小不超過 20 MB，每邊至少 32 像素，且像素總數（寬 × 高）不超過 178,956,970。
這些圖片僅用於指導 texture，與 image_urls 無關。兩個清單可以包含不同的圖片，數量也可以不同。
texture_image_urls 需要 Meshy 7 或 Meshy N1 貼圖模型。請搭配以下其中一項傳送：
- ai_model 為 meshy-7.1、latest 或已 deprecated 的 meshy-7
- texture_model 為 meshy-7 或 meshy-n1
不能將其與 texture_image_url 或 texture_prompt 一同傳送。

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
remesh 後模型的面類型。
可選值：
- quad：以四邊面為主的 mesh
- triangle：經過精簡的三角面 mesh
使用 texture_model: meshy-n1 時，若模型被 remesh（meshy-6-lite 預設會進行 remesh），設為 quad 會傳回 400。
Name
target_polycount
Type
integer
預設值 30000
Description
目標面數，範圍為 100 到 300000。實際結果可能與目標值有所差異，具體取決於模型的 geometry。超出範圍的值會傳回 400。
Name
decimation_mode
Type
integer
Description
按級別自適應面數。設定此參數後，Meshy 會忽略 target_polycount。
可選值：
- 1：ultra
- 2：high
- 3：medium
- 4：low
Name
save_pre_remeshed_model
Type
boolean
預設值 false
Description
是否同時儲存 remesh 之前的 GLB，結果會在 model_urls.pre_remeshed_glb 中傳回。

Name
symmetry_mode
Type
string
⚠ 已棄用
預設值 auto
Description
請勿使用此參數。它不會影響輸出結果。
可選值：
- off：無 symmetry
- auto：基於輸入 geometry 的 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
image_enhancement
Type
boolean
預設值 true
Description
生成前是否對輸入圖片進行最佳化。設為 false 會保留輸入圖片的原始外觀，不進行任何風格處理。僅 meshy-6、meshy-7.1 或 latest 支援此參數。與 meshy-6-lite 一同傳送會傳回 400。
Name
remove_lighting
Type
boolean
預設值 true
Description
是否從基礎色 texture 中去除高光和陰影。更乾淨的結果在你自己的光照下表現更好。只有 Meshy 6 貼圖模型會使用此參數，且在 texture_resolution: 8k 時始終會去除光照。使用 texture_model: meshy-n1 時，設為 true 會傳回 400。使用 ai_model: meshy-6-lite 及其預設貼圖模型時，傳送此參數會傳回 400。
Name
moderation
Type
boolean
預設值 false
Description
是否對輸入內容進行有害內容審核。Meshy 會審核每張輸入圖片、texture_image_url 或 texture_image_urls 中的每張圖片，以及 texture_prompt 中的文字。如果 Meshy 發現有害內容，請求會傳回 400，且 Meshy 不會建立任務。
Name
target_formats
Type
string[]
Description
要生成的 3D 檔案格式。Meshy 只會生成並傳回你列出的格式，這樣可以縮短任務耗時。
可選值：
- glb
- obj
- fbx
- stl
- usdz
- 3mf
如果留空，Meshy 會生成除 3mf 之外的所有格式。只有當你列出 3mf 時，Meshy 才會生成它。
Name
auto_size
Type
boolean
預設值 false
Description
是否使用 AI 視覺估算物體的真實世界高度，並據此調整模型尺寸。除非你設定了 origin_at，否則 Meshy 會將原點置於底部。

僅當 auto_size = true

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

Name
alpha_thumbnail
Type
boolean
預設值 false
Description
是否同時渲染一張背景透明（RGBA）的預覽圖，在取得任務時透過 alpha_thumbnail_url 傳回。thumbnail_url 不會改變。
Name
multi_view_thumbnails
Type
boolean
預設值 false
Description
是否同時渲染正、右、後、左四個視角的預覽圖，在取得任務時透過 thumbnail_urls 傳回。thumbnail_url 不會改變，仍顯示正視圖。此選項會使任務增加約 5 秒。

回傳值

回應中的 result 欄位包含新建立的 Multi-Image to 3D 任務的 ID。

失敗情形

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明具體發現了哪種問題。例如：
- 缺少參數：既未傳送 image_urls，也未傳送 input_task_id。
- 輸入任務無效：input_task_id 不是狀態為 SUCCEEDED 的 Text to Image 或 Image to Image 任務，也不是多視角任務。
- 圖片數量無效：image_urls 或 texture_image_urls 中的圖片數量不在 1 到 4 張之間。
- 圖片格式無效：image_urls 中的某張圖片格式不受支援。
- texture 輸入衝突：texture_image_urls 與 texture_image_url、texture_prompt，或 should_texture: false 一同傳送。
- 不支援多視角貼圖的模型：texture_image_urls 與 ai_model 為 meshy-6 或 meshy-6-lite 一同傳送，除非 texture_model 為 meshy-7 或 meshy-n1。
- URL 不可存取：Meshy 無法下載 image_urls 或 texture_image_urls 中的圖片。
- 圖片過大：image_urls、texture_image_url 或 texture_image_urls 中的某張圖片超過 20 MB。
- 圖片尺寸無效：image_urls、texture_image_url 或 texture_image_urls 中的某張圖片某邊短於 32 像素，或像素總數（寬 × 高）超過 178,956,970。
- 多圖片輸入不支援該解析度：geometry_resolution 為 "4k"，而此端點不支援該值。請使用 2k 或 standard。
- 圖片選項不支援該模型：image_enhancement 與 ai_model: "meshy-6-lite" 一同傳送，或 remove_lighting 與 ai_model: "meshy-6-lite" 及其預設貼圖模型一同傳送。
- 貼圖模型無效：texture_model 不是有效的貼圖模型名稱。
- 貼圖模型不可用：帶 texture 的請求傳送了 texture_model 為 meshy-6 或 meshy-6-lite。Multi-Image to 3D 僅支援可從多視角貼圖的貼圖模型。請傳送 meshy-7 或 meshy-n1，或不填 texture_model。
- 貼圖模型不支援該選項：請求向貼圖模型要求了其不支援的選項，例如在 meshy-n1 下設定 enable_pbr: true，或在 meshy-6-lite 下使用 4k texture。參見模型。
請修正請求後重新傳送。參見錯誤。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分上限。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
Name
403 - Forbidden
Description
內容審核攔截了該 prompt 或某張輸入圖片。請修改輸入內容後重試。
Name
404 - Not Found
Description
input_task_id 與你的任何任務都不符合。請檢查任務 ID，然後重新傳送請求。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。參見速率限制。

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

取得 Multi-Image to 3D 任務

根據 ID 回傳一個 Multi-Image to 3D 任務。

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

參數

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

回傳

Multi-Image to 3D 任務物件。

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

刪除一個 Multi-Image to 3D 任務

永久刪除一個 Multi-Image to 3D 任務，包括其模型和資料。刪除操作無法撤銷。

Request

DELETE

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

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

取得多圖生成 3D 任務列表

返回你的多圖生成 3D 任務列表。

Request

GET

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

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

參數

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：從最新到最早

一個分頁的多圖生成 3D 任務物件列表。

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

流式取得 Multi-Image to 3D 任務

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/multi-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.
// 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",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

參數

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

回傳值

以伺服器發送事件形式推送的 Multi-Image to 3D 任務物件資料流。

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

多圖生成 3D 任務物件

多圖生成 3D 任務物件描述了根據一張到四張物體圖片生成 3D 模型的一次生成過程。它儲存了任務的狀態、進度，以及任務成功後的模型檔案。

屬性

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Name
id
Type
string
Description
任務 ID。請將其視為不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 multi-image-to-3d。
Name
model_urls
Type
object
Description
生成的 3D 模型的下載 URL，每種檔案格式一個。任務未生成的格式不會有對應的鍵，而不是空字串。
- Name
  glb
  Type
  string
  Description
  GLB 檔案。
- Name
  fbx
  Type
  string
  Description
  FBX 檔案。
- Name
  obj
  Type
  string
  Description
  OBJ 檔案。
- Name
  usdz
  Type
  string
  Description
  USDZ 檔案。
- Name
  mtl
  Type
  string
  Description
  MTL 檔案，當模型帶有 texture 時會隨 OBJ 檔案一起返回。
- Name
  stl
  Type
  string
  Description
  STL 檔案。
- Name
  3mf
  Type
  string
  Description
  3MF 檔案。僅當 target_formats 包含 3mf 時才會出現。
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Remesh 之前的 GLB 檔案。僅當建立任務時同時設定了 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 且 Meshy 渲染了透明預覽圖時才會出現。
Name
thumbnail_urls
Type
object
Description
3D 模型四個方向預覽圖的下載 URL。每個都是指向 512×512 PNG 圖片的簽名 URL，使用與 thumbnail_url 相同的材質和光照渲染而成。你可以用它們在不下載 GLB 的情況下從多個角度預覽模型。
僅當建立任務時設定了 multi_view_thumbnails: true 且任務達到 SUCCEEDED 狀態時才會出現。未設定 multi_view_thumbnails: true 建立的任務沒有此欄位。
- 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_urls
Type
string[]
Description
建立任務時使用的 texture 參考圖片的下載 URL，順序與你發送時的順序一致。僅當建立任務時提供了 texture_image_urls 時才會出現。
Name
ultra_mode
Type
boolean
⚠ 已棄用
Description
請改為讀取 geometry_resolution。
Name
geometry_resolution
Type
string
Description
任務執行所使用的 Ultra 檔位，即 2k。standard 任務沒有此欄位。
Name
progress
Type
integer
Description
任務完成的百分比。任務開始前為 0，成功後為 100。
Name
started_at
Type
timestamp
Description
任務開始的時間，以 Unix 毫秒表示。任務開始前為 0。
Name
created_at
Type
timestamp
Description
任務建立的時間，以 Unix 毫秒表示。
Name
expires_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
  自發光貼圖。僅當建立任務時同時滿足以下所有條件才會包含：
  
  ai_model: meshy-6，並使用其預設 texture 模型
  
  enable_pbr: true
  
  texture_resolution 為 2k 或 4k
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 會在任務失敗時退還積分。