影象生成 3D API

將圖像轉換為 3D 模型，可選擇是否帶貼圖，並可選擇所需的格式。傳送圖像，或使用文字生成影像或影像生成影像任務的輸出結果。

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

創建 Image to 3D 任務

創建一個 Image to 3D 任務。任務會在後台執行。關於任務通常需要多長時間，請參閱處理時間。

Request

POST

/openapi/v1/image-to-3d

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

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible 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_url，否則此項為必填。你想用作輸入的 Text to Image 或 Image to Image 任務的圖像所屬任務的 ID。該任務必須是你透過 API 創建的、狀態為 SUCCEEDED、且只生成了一張圖像的任務。

Name
image_url
Type
string
必選
Description
除非你傳送 input_task_id，否則此項為必填。要轉換為 3D 模型的圖像，可以是公開可存取的 URL，或 base64 編碼的資料 URI，例如 data:image/jpeg;base64,<your base64-encoded image data>。如果兩者都傳送，Meshy 會使用 input_task_id。
圖像必須是 JPG、JPEG、PNG 或 WebP 檔案，大小不超過 20 MB，每邊至少 32 像素，且不超過 178,956,970 像素（寬 × 高）。

Name
model_type
Type
string
預設值 standard
Description
要生成的 3D mesh 類型。
可選值：
- standard：高細節 mesh
- smart-topology：來自 Smart Topology 模型的 mesh，你可以透過 ai_model（meshy-t2 或 meshy-t2.5）來選擇
使用 smart-topology 時，Meshy 會忽略 should_remesh、save_pre_remeshed_model 和 decimation_mode，並且只接受 topology: triangle。
Name
ai_model
Type
string
預設值 latest
Description
用於生成 3D 模型的 AI 模型。可用值取決於 model_type。
Standard 模型（model_type: standard）：
- latest：Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7（已棄用）：請改用 meshy-7.1
Smart Topology 模型（model_type: smart-topology）會生成三角形面，面數可以透過 target_polycount 設定：
- meshy-t2：更乾淨的 topology，且各部件原生分離
- meshy-t2.5（預設）：為遊戲 asset 提供更銳利的細節
Name
geometry_resolution
Type
string
預設值 standard
Description
geometry 生成的處理階段。
可選值：
- standard
- 2k：以 2048³ 執行 Ultra 階段
- 4k：以 4096³ 執行 Ultra 階段，以獲得最多的表面細節
2k 需要 meshy-7.1、latest 或已棄用的 meshy-7。4k 需要 meshy-7.1 或 latest。
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 模型生成 texture 的 AI 模型。留空則使用你所選 ai_model 對應的預設 texture 模型。它不會改變積分消耗。
可選值：
- meshy-7：Meshy 7，帶 PBR 貼圖，texture 最高可達 8K
- meshy-n1：Meshy N1，僅根據參考圖像生成 2K 基礎色 texture
- meshy-6-lite：Meshy 6 Lite，以最低成本生成 2K texture
- meshy-6：Meshy 6，僅作為 ai_model: meshy-6 的預設值
每個 ai_model 都支援 meshy-7、meshy-n1 和 meshy-6-lite。如果所選 texture 模型不支援某個選項，將返回 400。使用 meshy-n1 時，如果生成的模型三角面數超過 7,999,999，任務會失敗，Meshy 會退還對應的積分。設定 should_texture: false 時，Meshy 會忽略 texture_model，但未知值仍會返回 400。
關於每個 texture 模型的作用及如何選擇，請參閱模型。
Name
enable_pbr
Type
boolean
預設值 false
Description
除了基礎色之外，是否同時生成 PBR 貼圖（金屬度、粗糙度和法線）。true 需要 should_texture: true，否則在 should_texture: false 時會返回 400。使用 texture_model: meshy-n1 時，true 會返回 400。
Meshy 6 texture 模型還會生成自發光貼圖，但在 texture_resolution: 8k 時除外。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎色 texture 的尺寸。更大的 texture 能捕捉更多表面細節。
可選值：
- 2k：2048×2048
- 4k：4096×4096
- 8k：8192×8192
4k 和 8k 需要 Meshy 7 或 Meshy 6 texture 模型，使用其他模型會返回 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 生成的圖像，可以是公開可存取的 URL，或 base64 編碼的資料 URI，例如 data:image/jpeg;base64,<your base64-encoded image data>。圖像必須是 JPG、JPEG、PNG 或 WebP 檔案，大小不超過 20 MB，每邊至少 32 像素，且不超過 178,956,970 像素（寬 × 高）。
Meshy 只會使用 texture_prompt 和 texture_image_url 其中之一來指導 texture 生成。如果兩者都傳送，Meshy 會使用 texture_prompt。關於貼圖的積分消耗，請參閱 Pricing。
使用 texture_model: meshy-n1 時，Meshy 會將此圖像作為正視圖來生成 texture；如果留空，則使用輸入圖像。
當圖像的形狀與 3D 模型的 geometry 差異較大時，基於圖像生成 texture 的效果可能不佳。

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
重新生成 mesh 後的面類型。
可選值：
- quad：以四邊面為主的 mesh
- triangle：經過精簡的三角面 mesh
Smart Topology 的輸出只支援三角面，因此在 meshy-t2 或 meshy-t2.5 下使用 quad 會返回 400。使用 texture_model: meshy-n1 時，如果模型經過了 remesh（meshy-6-lite 預設會這樣做），quad 會返回 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 檔案。Meshy 會在 model_urls.pre_remeshed_glb 中返回它。

Name
target_polycount
Type
integer
Description
目標面數。實際結果可能會因模型的 geometry 而與目標值有所差異。
它適用於兩種不同情形：
- 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：無對稱
- auto：根據輸入 geometry 自動選擇對稱方式
- on：強制對稱
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
surface_mode
Type
string
⚠ 已棄用
Description
請改用 ai_model。它不會影響輸出結果，因為它所選擇的模型生成方式已被淘汰。
可接受的值為 organic 和 hard。其他任何值都會返回 400。
Name
image_enhancement
Type
boolean
預設值 true
Description
是否在生成之前最佳化輸入圖像。false 會保留輸入圖像的原始外觀，不進行任何風格處理。
此選項僅適用於 meshy-6、meshy-7.1 或 latest。使用 meshy-6-lite 或 model_type: smart-topology 時會返回 400。
Name
remove_lighting
Type
boolean
預設值 true
Description
是否從基礎色 texture 中移除高光和陰影。處理後的結果更乾淨，在你自己的燈光環境下效果更好。
該選項僅在使用 Meshy 6 texture 模型時生效，若所用 texture 模型不支援該選項，設為 true 時會返回 400。使用 model_type: smart-topology，或使用 ai_model: meshy-6-lite 及其預設 texture 模型時，傳送該參數會返回 400。
Name
moderation
Type
boolean
預設值 false
Description
是否在生成之前對以下輸入內容進行有害內容審核：
- image_url
- texture_image_url
- texture_prompt
如果 Meshy 偵測到有害內容，請求將返回 400，且 Meshy 不會創建任務。
Name
target_formats
Type
string[]
Description
要生成的檔案格式。Meshy 只會生成並返回你列出的格式，這樣可以縮短任務時長。如果留空，Meshy 會生成除 3mf 之外的所有格式，只有在你列出 3mf 時才會生成它。
可選值：
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
預設值 false
Description
是否使用 AI 視覺估算物體的真實高度，並將模型縮放到該尺寸。除非你設定了 origin_at，否則 Meshy 會將 origin 放在底部。
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 秒鐘。

僅當 auto_size = true

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

返回值

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

失敗情形

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現的具體問題。例如：
- 缺少參數：既沒有傳送 image_url，也沒有傳送 input_task_id。
- 輸入任務無效：input_task_id 不是一個狀態為 SUCCEEDED、且只生成了一張圖像的 Text to Image 或 Image to Image 任務。
- 圖像格式無效：image_url 對應的圖像不是 JPG、JPEG、PNG 或 WebP 檔案。
- URL 無法存取：Meshy 無法下載 image_url 對應的圖像，因為該 URL 返回 404 或請求逾時。
- 圖像過大：image_url 或 texture_image_url 對應的圖像超過 20 MB。
- 圖像尺寸無效：image_url 或 texture_image_url 對應的圖像某一邊短於 32 像素，或超過 178,956,970 像素（寬 × 高）。
- 資料 URI 無效：base64 字串格式有誤。
- 參數組合無效：enable_pbr 為 true，且 should_texture 為 false。
- Ultra 不支援所選模型：geometry_resolution 為 2k 或 4k，但所用的 ai_model 不支援該階段。
- 圖像相關選項不支援所選模型：以下情況之一：
  - 在 ai_model: "meshy-6-lite" 或 model_type: "smart-topology" 下傳送了 image_enhancement。
  - 在 model_type: "smart-topology" 下，或在 ai_model: "meshy-6-lite" 及其預設 texture 模型下傳送了 remove_lighting。
- texture 模型無效：texture_model 不是可用值之一。
- texture 模型不可用：texture_model 為 meshy-6，但 ai_model 不是 meshy-6。請傳送 meshy-7、meshy-n1 或 meshy-6-lite，或將其留空。
- 所選 texture 模型不支援該選項：請求向 texture 模型請求了它不支援的選項，例如在 meshy-n1 下設定 enable_pbr: true，或在 meshy-6-lite 下請求 4k texture。請參閱模型。
修正請求後重新傳送。請參閱 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分 balance，然後重試。
- 免費方案：創建任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
Name
403 - Forbidden
Description
內容審核攔截了 prompt 或某個輸入圖像。請更改輸入內容後重試。
Name
404 - Not Found
Description
input_task_id 與你的任何任務都不匹配。請檢查任務 ID，然後重新傳送請求。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。請參閱速率限制。

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

取得 Image to 3D 任務

根據 ID 返回一個 Image to 3D 任務。

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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",
      "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": 30
}

參數

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

返回值

Image to 3D 任務物件。

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

刪除影象生成 3D 任務

永久刪除一個影象生成 3D 任務，包括它的模型和資料。刪除操作無法復原。

Request

DELETE

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

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

列出 Image to 3D 任務

返回您的 Image to 3D 任務列表。

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "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",
        "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": 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：最新優先

返回值

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

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

流式取得 Image to 3D 任務

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/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": "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",
      "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": 30
}

參數

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

回傳值

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

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

Image to 3D 任務物件

一個 Image to 3D 任務物件描述了一次從影像生成 3D 模型的任務。它保存了任務的狀態、進度，以及任務成功後的模型檔案。

屬性

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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": "",
  "texture_image_url": "",
  "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",
      "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": 30
}

Name
id
Type
string
Description
任務 ID。請將其視為一個不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 image-to-3d。
Name
model_urls
Type
object
Description
生成的 3D 模型的下載連結，每種檔案格式對應一個。任務未生成的格式不會有對應的鍵，而不是空字串。
- 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
3D 模型預覽圖的下載連結。當存在 thumbnail_urls 時，它與 thumbnail_urls.front 是同一張圖片。Meshy 保留此欄位是為了向後相容。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景版本（RGBA）的下載連結。僅當你在建立任務時設定了 alpha_thumbnail: true 且 Meshy 渲染出了透明預覽圖時才會出現。
Name
thumbnail_urls
Type
object
Description
從四個方向查看 3D 模型的預覽圖下載連結。每個值都是一個指向 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_url
Type
string
Description
用於指導 texture 生成的圖片的下載連結。
Name
ultra_mode
Type
boolean
⚠ 已棄用
Description
請改用 geometry_resolution。
Name
geometry_resolution
Type
string
Description
任務執行的 Ultra 檔位，2k 或 4k。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 貼圖，是一個物件陣列。它通常只包含一個物件，具有以下欄位：
- 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
  自發光貼圖的下載連結。只有當你在建立任務時同時滿足以下所有條件時，Meshy 才會包含此欄位：
  
  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 會在任務失敗時退還積分。